The NNTrainer function provides interfaces to create and train Machine Learning models on the device locally.

Required Header

#include <nntrainer/nntrainer.h>

Overview

The NNTrainer API provides interfaces to create and train Machine Learning models on the device locally.

This function allows the following operations with NNTrainer:

Interfaces to create a machine learning predefined model or from scratch.
Create/destroy and add new layers to the model.
Create/destroy and set optimizer to the model.
Interfaces to set datasets to feed data to the model.
Summarize the model with the set configuration.
Interfaces to compile and run the model.
Utility functions to set properties for the models and its various sub-parts.

Note that this function set is supposed to be thread-safe.

Related Features

This function is related with the following features:

http://tizen.org/feature/machine_learning
http://tizen.org/feature/machine_learning.training

It is recommended to probe features in your application for reliability.
You can check if a device supports the related features for this function by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
For example, your application accesses to the camera device, then you have to add http://tizen.org/privilege/camera into the manifest of your application.
More details on featuring your application can be found from Feature Element.

Functions
int	ml_train_model_construct (ml_train_model_h *model)
	Constructs the neural network model.
int	ml_train_model_construct_with_conf (const char model_conf, ml_train_model_h model)
	Constructs the neural network model with the given configuration file.
int	ml_train_model_compile (ml_train_model_h model,...)
	Compiles and finalizes the neural network model with the given loss.
int	ml_train_model_run (ml_train_model_h model,...)
	Trains the neural network model.
int	ml_train_model_destroy (ml_train_model_h model)
	Destructs the neural network model.
int	ml_train_model_get_summary (ml_train_model_h model, ml_train_summary_type_e verbosity, char **summary)
	Gets the summary of the neural network model.
int	ml_train_model_add_layer (ml_train_model_h model, ml_train_layer_h layer)
	Adds layer in neural network model.
int	ml_train_model_set_optimizer (ml_train_model_h model, ml_train_optimizer_h optimizer)
	Sets the optimizer for the neural network model.
int	ml_train_model_set_dataset (ml_train_model_h model, ml_train_dataset_h dataset)
	Sets the dataset (data provider) for the neural network model.
int	ml_train_model_get_input_tensors_info (ml_train_model_h model, ml_tensors_info_h *info)
	Gets input tensors information of the model.
int	ml_train_model_get_output_tensors_info (ml_train_model_h model, ml_tensors_info_h *info)
	Gets output tensors information of the model.
int	ml_train_layer_create (ml_train_layer_h *layer, ml_train_layer_type_e type)
	Creates a neural network layer.
int	ml_train_layer_destroy (ml_train_layer_h layer)
	Frees the neural network layer.
int	ml_train_layer_set_property (ml_train_layer_h layer,...)
	Sets the neural network layer Property.
int	ml_train_optimizer_create (ml_train_optimizer_h *optimizer, ml_train_optimizer_type_e type)
	Creates a neural network optimizer.
int	ml_train_optimizer_destroy (ml_train_optimizer_h optimizer)
	Frees the neural network optimizer.
int	ml_train_optimizer_set_property (ml_train_optimizer_h optimizer,...)
	Sets the neural network optimizer property.
int	ml_train_optimizer_set_lr_scheduler (ml_train_optimizer_h optimizer, ml_train_lr_scheduler_h lr_scheduler)
	Sets the learning rate scheduler for the optimizer.
int	ml_train_lr_scheduler_create (ml_train_lr_scheduler_h *lr_scheduler, ml_train_lr_scheduler_type_e type)
	Creates a learning rate scheduler for optimizer.
int	ml_train_lr_scheduler_destroy (ml_train_lr_scheduler_h lr_scheduler)
	Frees the learning rate scheduler.
int	ml_train_lr_scheduler_set_property (ml_train_lr_scheduler_h lr_scheduler,...)
	Sets the learning rate scheduler property.
int	ml_train_dataset_create_with_generator (ml_train_dataset_h *dataset, ml_train_datagen_cb train_cb, ml_train_datagen_cb valid_cb, ml_train_datagen_cb test_cb)
	Creates a dataset with generators to feed to a neural network.
int	ml_train_dataset_create (ml_train_dataset_h *dataset)
	Constructs the dataset.
int	ml_train_dataset_add_generator (ml_train_dataset_h dataset, ml_train_dataset_mode_e mode, ml_train_datagen_cb cb, void *user_data)
	Adds data generator callback to dataset.
int	ml_train_dataset_add_file (ml_train_dataset_h dataset, ml_train_dataset_mode_e mode, const char *file)
	Adds data file to dataset.
int	ml_train_dataset_create_with_file (ml_train_dataset_h dataset, const char train_file, const char valid_file, const char test_file)
	Creates a dataset with files to feed to a neural network.
int	ml_train_dataset_destroy (ml_train_dataset_h dataset)
	Frees the neural network dataset.
int	ml_train_dataset_set_property (ml_train_dataset_h dataset,...)
	Sets the neural network dataset property.
int	ml_train_dataset_set_property_for_mode (ml_train_dataset_h dataset, ml_train_dataset_mode_e mode,...)
	Sets the neural network dataset property.
int	ml_train_model_save (ml_train_model_h model, const char *file_path, ml_train_model_format_e format)
	Saves the model.
int	ml_train_model_load (ml_train_model_h model, const char *file_path, ml_train_model_format_e format)
	Loads the model.
int	ml_train_model_get_layer (ml_train_model_h model, const char layer_name, ml_train_layer_h layer)
	Gets neural network layer from the model with the given name.
int	ml_train_model_get_weight (ml_train_model_h model, const char layer_name, ml_tensors_data_h weight, ml_tensors_info_h *info)
	Gets weight tensors and information of the layer.
Typedefs
typedef int(*	ml_train_datagen_cb )(float input, float label, bool last, void user_data)
	Dataset generator callback function for train/valid/test data.
typedef void *	ml_train_model_h
	A handle of a NNTrainer model.
typedef void *	ml_train_layer_h
	A handle of a NNTrainer layer.
typedef void *	ml_train_optimizer_h
	A handle of a NNTrainer optimizer.
typedef void *	ml_train_lr_scheduler_h
	A handle of a NNTrainer learning rate scheduler.
typedef void *	ml_train_dataset_h
	A handle of a NNTrainer dataset.

Typedef Documentation

typedef int(* ml_train_datagen_cb)(float **input, float **label, bool *last, void *user_data)

Dataset generator callback function for train/valid/test data.

The user of the API must provide this callback function to supply data to the model and register the callback with ml_train_dataset_add_generator(). The model will call this callback whenever it needs more data. This function should provide a single element of input and label data in the passed containers. The containers passed by the caller will already be allocated with sufficient space to contain the data. This function callback should fill the data row-wise in the containers provided. The containers represent array of memory to hold inputs for the model. If the model contains two inputs, then input[0] will hold the first input, and input[1] will hold the second input. The same applies for labels as well. The number of inputs and labels, and the size of each input and label should match with the shape of each input and label set in the model. The order of the inputs/labels, in case of multiple of inputs/labels, will be determined based on the sequence of addition of the input layers to the model.

Since :: 6.0

Note:: This function can be called multiple times in parallel when total number of samples are set as a property for this dataset. In this case, last is only used for verification purposes. If total number of samples for the dataset is unknown, this function will be called in sequence.; last has to be set true when filling the last input, label.

Parameters:

[out]	input	Container to hold all the input data. Should not be freed by the user.
[out]	label	Container to hold corresponding label data. Should not be freed by the user.
[out]	last	Container to notify if data is finished. Set true if no more data to provide, else set false. Should not be freed by the user.
[in]	user_data	User application's private data passed along with ml_train_dataset_add_generator().

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

A sample implementation of this function is below: Note : input data information available from outside this function. num_samples : total number of data samples in the dataset. count : number of samples already given. num_inputs : number of inputs. num_labels : number of labels. input_length[num_inputs] : length of the input. With (batch, c, h, w) as input shape, the length will be c * h * w. label_length[num_labels] : length of the label. With (batch, l) as label shape, then length will be l.

 // function signature :
 // int rand_dataset_generator (float **input, float **label, bool *last,
 // void *user_data).

 // This sample fills inputs and labels with random data.
 srand(0);
 if (count >= num_samples) {
   *last = true;
   // handle preparation for start of next epoch
 } else {
   *last = false;
 }

 // Fill input data
 for (int idx = 0; idx < num_inputs; ++ idx) {
   for (int len = 0; len < input_length[idx]; ++ len) {
     input[idx][len] = rand();
   }
 }

 // Fill label data
 for (int idx = 0; idx < num_inputs; ++ idx) {
   for (int len = 0; len < label_length[idx]; ++ len) {
     label[idx][len] = rand();
   }
 }

 // Update the helper variables
 count += 1;

 return ML_ERROR_NONE;

Below is an example of the usage of this sample:

 int status;
 void * user_data;
 ml_train_dataset_h handle;
 status = ml_train_dataset_create(&handle);
 if (status != ML_ERROR_NONE) {
    // handle error case.
    return status;
 }

 status = ml_train_dataset_add_generator(dataset,
      ML_TRAIN_DATASET_MODE_TRAIN, getBatch_train, user_data);
 if (status != ML_ERROR_NONE) {
    // handle error case.
    return status;
 }

 // Destroy the handle if not added to a model.
 status = ml_train_dataset_destroy(handle);
 if (status != ML_ERROR_NONE) {
    // handle error case
    return status;
 }

typedef void* ml_train_dataset_h

A handle of a NNTrainer dataset.

Since :: 6.0

typedef void* ml_train_layer_h

A handle of a NNTrainer layer.

Since :: 6.0

typedef void* ml_train_lr_scheduler_h

A handle of a NNTrainer learning rate scheduler.

Since :: 8.0

typedef void* ml_train_model_h

A handle of a NNTrainer model.

Since :: 6.0

typedef void* ml_train_optimizer_h

A handle of a NNTrainer optimizer.

Since :: 6.0

Enumeration Type Documentation

enum ml_train_dataset_mode_e

Enumeration for the dataset data type of NNTrainer.

Since :: 6.5

Enumerator:

ML_TRAIN_DATASET_MODE_TRAIN	The given data is for used when training
ML_TRAIN_DATASET_MODE_VALID	The given data is for used when validating
ML_TRAIN_DATASET_MODE_TEST	The given data is for used when testing

enum ml_train_layer_type_e

Enumeration for the neural network layer type of NNTrainer.

Since :: 6.0

Enumerator:

ML_TRAIN_LAYER_TYPE_INPUT	Input Layer
ML_TRAIN_LAYER_TYPE_FC	Fully Connected Layer
ML_TRAIN_LAYER_TYPE_BN	Batch Normalization Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_CONV2D	Convolution 2D Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_POOLING2D	Pooling 2D Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_FLATTEN	Flatten Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_ACTIVATION	Activation Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_ADDITION	Addition Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_CONCAT	Concat Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_MULTIOUT	MultiOut Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_EMBEDDING	Embedding Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_RNN	RNN Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_LSTM	LSTM Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_SPLIT	Split Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_GRU	GRU Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_PERMUTE	Permute layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_DROPOUT	Dropout Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_BACKBONE_NNSTREAMER	Backbone using NNStreamer (Since 6.5)
ML_TRAIN_LAYER_TYPE_CENTROID_KNN	Centroid KNN Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_CONV1D	Convolution 1D Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_LSTMCELL	LSTM Cell Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_GRUCELL	GRU Cell Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_RNNCELL	RNN Cell Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_ZONEOUTLSTMCELL	ZoneoutLSTM Cell Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_ATTENTION	Attention Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_MOL_ATTENTION	MoL Attention Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_MULTI_HEAD_ATTENTION	Multi Head Attention Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_LAYER_NORMALIZATION	Layer Normalization Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_POSITIONAL_ENCODING	Positional Encoding Layer type (Since 7.0)
ML_TRAIN_LAYER_TYPE_IDENTITY	Identity Layer type (Since 8.0)
ML_TRAIN_LAYER_TYPE_PREPROCESS_FLIP	Preprocess flip Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_PREPROCESS_TRANSLATE	Preprocess translate Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_PREPROCESS_L2NORM	Preprocess L2Normalization Layer (Since 6.5)
ML_TRAIN_LAYER_TYPE_LOSS_MSE	Mean Squared Error Loss Layer type (Since 6.5)
ML_TRAIN_LAYER_TYPE_LOSS_CROSS_ENTROPY_SIGMOID	Cross Entropy with Sigmoid Loss Layer type (Since 6.5)
ML_TRAIN_LAYER_TYPE_LOSS_CROSS_ENTROPY_SOFTMAX	Cross Entropy with Softmax Loss Layer type (Since 6.5)
ML_TRAIN_LAYER_TYPE_UNKNOWN	Unknown Layer

enum ml_train_lr_scheduler_type_e

Enumeration for the learning rate scheduler type of NNTrainer.

Since :: 8.0

Enumerator:

ML_TRAIN_LR_SCHEDULER_TYPE_CONSTANT	Constant lr scheduler
ML_TRAIN_LR_SCHEDULER_TYPE_EXPONENTIAL	Exponentially lr scheduler
ML_TRAIN_LR_SCHEDULER_TYPE_STEP	Step lr scheduler
ML_TRAIN_LR_SCHEDULER_TYPE_UNKNOWN	Unknown lr scheduler

enum ml_train_model_format_e

Enumeration for the neural network.

Since :: 6.5

Enumerator:

ML_TRAIN_MODEL_FORMAT_BIN	Raw bin file saves model weights required for inference and training without any configurations
ML_TRAIN_MODEL_FORMAT_INI	Ini format file saves model configurations.
ML_TRAIN_MODEL_FORMAT_INI_WITH_BIN	Ini with bin format file saves configurations with parameters required for inference and training.
ML_TRAIN_MODEL_FORMAT_FLATBUFFER	Flatbuffer format file saves model configurations and weights.

enum ml_train_optimizer_type_e

Enumeration for the neural network optimizer type of NNTrainer.

Since :: 6.0

Enumerator:

ML_TRAIN_OPTIMIZER_TYPE_ADAM	Adam Optimizer
ML_TRAIN_OPTIMIZER_TYPE_SGD	Stochastic Gradient Descent Optimizer
ML_TRAIN_OPTIMIZER_TYPE_UNKNOWN	Unknown Optimizer

enum ml_train_summary_type_e

Enumeration for the neural network summary verbosity of NNTrainer.

Since :: 6.0

Enumerator:

ML_TRAIN_SUMMARY_MODEL	Overview of model summary with one-line layer information
ML_TRAIN_SUMMARY_LAYER	Detailed model summary with layer properties
ML_TRAIN_SUMMARY_TENSOR	Model summary layer's including weight information

Function Documentation

int ml_train_dataset_add_file	(	ml_train_dataset_h	dataset,
		ml_train_dataset_mode_e	mode,
		const char *	file
	)

Adds data file to dataset.

Use this function to add a data file from where data is retrieved.

Since :: 6.5

Remarks:: If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. Or, if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. If you can access both storage, you must add all privilege

Parameters:

[in]	dataset	The NNTrainer dataset handle.
[in]	mode	The phase where this file should be used.
[in]	file	file path.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_PERMISSION_DENIED	Permission denied.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_add_generator	(	ml_train_dataset_h	dataset,
		ml_train_dataset_mode_e	mode,
		ml_train_datagen_cb	cb,
		void *	user_data
	)

Adds data generator callback to dataset.

Use this function to add a data generator callback which generates a single element per call to the dataset.

Since :: 6.5

Parameters:

[in]	dataset	The NNTrainer dataset handle.
[in]	mode	The phase where this generator should be used.
[in]	cb	Callback to be used for the generator.
[in]	user_data	user_data to be fed when cb is being called.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_create ( ml_train_dataset_h * dataset )

Constructs the dataset.

Use this function to create a dataset.

Since :: 6.5

Remarks:: If the function succeeds, dataset must be released using ml_train_dataset_destroy(), if not added to a model. If added to a model, dataset is available until the model is released.

Parameters:

[out] dataset The NNTrainer dataset handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_create_with_file	(	ml_train_dataset_h *	dataset,
		const char *	train_file,
		const char *	valid_file,
		const char *	test_file
	)

Creates a dataset with files to feed to a neural network.

Deprecated:: Deprecated since 6.5. Use ml_train_dataset_create() instead.

Use this function to create a neural network dataset using files.

Since :: 6.0

Parameters:

[out]	dataset	The NNTrainer dataset handle from the given description. If not set to a model, dataset should be released using ml_train_dataset_destroy(). If set to a model, dataset is available until model is released.
[in]	train_file	The dataset file for training.
[in]	valid_file	The dataset file for validating. Can be null.
[in]	test_file	The dataset file for testing. Can be null.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_create_with_generator	(	ml_train_dataset_h *	dataset,
		ml_train_datagen_cb	train_cb,
		ml_train_datagen_cb	valid_cb,
		ml_train_datagen_cb	test_cb
	)

Creates a dataset with generators to feed to a neural network.

Deprecated:: Deprecated since 6.5. Use ml_train_dataset_create() instead.

Use this function to create a neural network dataset using generators. The generators will provide data representing a single input element. When setting this dataset to a model, the data generated by the generators should match the input and the label shape for the model.

Since :: 6.0

Remarks:: If the function succeeds, dataset must be released using ml_train_dataset_destroy(), if not set to a model. If set to a model, dataset is available until the model is released.

Parameters:

[out]	dataset	The NNTrainer dataset handle from the given description. If not set to a model, dataset should be released using ml_train_dataset_destroy(). If set to a model, dataset is available until model is released.
[in]	train_cb	The dataset generator for training.
[in]	valid_cb	The dataset generator for validating. Can be null.
[in]	test_cb	The dataset generator for testing. Can be null.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_destroy ( ml_train_dataset_h dataset )

Frees the neural network dataset.

Use this function to destroy dataset. Fails if dataset is owned by a model.

Since :: 6.0

Parameters:

[in] dataset The NNTrainer dataset handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_set_property	(	ml_train_dataset_h	dataset,
			...
	)

Sets the neural network dataset property.

Deprecated:: Deprecated since 6.5. Use ml_train_dataset_set_property_for_mode() instead.

Use this function to set dataset property.

Since :: 6.0

Remarks:: the same property is applied over train, valid, testsets that are added to the dataset, it is recommended to use ml_train_dataset_set_property_for_mode() instead.

Parameters:

[in]	dataset	The NNTrainer dataset handle.
[in]	...	Property values with NULL for termination.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_dataset_set_property_for_mode	(	ml_train_dataset_h	dataset,
		ml_train_dataset_mode_e	mode,
			...
	)

Sets the neural network dataset property.

Use this function to set dataset property for a specific mode.

Since :: 6.5

Parameters:

[in]	dataset	The NNTrainer dataset handle.
[in]	mode	The mode to set the property.
[in]	...	Property values with NULL for termination.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_layer_create	(	ml_train_layer_h *	layer,
		ml_train_layer_type_e	type
	)

Creates a neural network layer.

Use this function to create neural network layer.

Since :: 6.0

Remarks:: If the function succeeds, layer must be released using ml_train_layer_destroy(), if not added to a model. If added to a model, layer is available until the model is released.

Parameters:

[out]	layer	The NNTrainer layer handle from the given description.
[in]	type	The NNTrainer layer type

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_layer_destroy ( ml_train_layer_h layer )

Frees the neural network layer.

Use this function to destroy neural network layer. Fails if layer is owned by a model.

Since :: 6.0

Parameters:

[in] layer The NNTrainer layer handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_layer_set_property	(	ml_train_layer_h	layer,
			...
	)

Sets the neural network layer Property.

Use this function to set neural network layer Property.

Since :: 6.0

Parameters:

[in]	layer	The NNTrainer layer handle.
[in]	...	Property values with NULL for termination.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

Here is an example of the usage of this function:

 int status;
 ml_train_layer_h handle;

 status = ml_train_layer_create(&handle, ML_TRAIN_LAYER_TYPE_FC);
 if (status != ML_ERROR_NONE) {
    // Handle error case
    return status;
 }

 // Many of these hyperparameters are optional
 status = ml_train_layer_set_property(handle, "input_shape=1:1:6270",
      "unit=10", "bias_initializer=zeros", "activation=sigmoid",
      "weight_regularizer=l2_norm", "weight_initializer=he_uniform", NULL);
 if (status != ML_ERROR_NONE) {
    // Handle error case
    ml_train_layer_destroy(handle);
    return status;
 }

 status = ml_train_layer_destroy(handle);
 if (status != ML_ERROR_NONE) {
    // Handle error case
    return status;
 }

int ml_train_lr_scheduler_create	(	ml_train_lr_scheduler_h *	lr_scheduler,
		ml_train_lr_scheduler_type_e	type
	)

Creates a learning rate scheduler for optimizer.

Use this function to create learning rate scheduler for optimizer. If not set to a optimizer, lr_scheduler should be released using ml_train_lr_scheduler_destroy(). If set to a optimizer, lr_scheduler is available until optimizer is released.

Since :: 8.0

Remarks:: If the function succeeds, lr_scheduler must be released using ml_train_lr_scheduler_destroy(), if not set to a optimizer. If set to a optimizer, lr_scheduler is available until the optimizer is released.

Parameters:

[out]	lr_scheduler	The NNTrainer learning rate scheduler handle.
[in]	type	The NNTrainer learning rate scheduler type.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_lr_scheduler_destroy ( ml_train_lr_scheduler_h lr_scheduler )

Frees the learning rate scheduler.

Use this function to destroy learning rate scheduler. Fails if learning rate scheduler is owned by a optimizer.

Since :: 8.0

Parameters:

[in] lr_scheduler The NNTrainer learning rate scheduler handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_lr_scheduler_set_property	(	ml_train_lr_scheduler_h	lr_scheduler,
			...
	)

Sets the learning rate scheduler property.

Use this function to set learning rate scheduler property.

Since :: 8.0

Parameters:

[in]	lr_scheduler	The NNTrainer learning rate scheduler handle.
[in]	...	Property values with NULL for termination.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_add_layer	(	ml_train_model_h	model,
		ml_train_layer_h	layer
	)

Adds layer in neural network model.

Use this function to add a layer to the model. The layer is added to the end of the existing layers in the model. This transfers the ownership of the layer to the network. No need to destroy the layer once it is added to a model.

Since :: 6.0

Parameters:

[in]	model	The NNTrainer model handle.
[in]	layer	The NNTrainer layer handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_compile	(	ml_train_model_h	model,
			...
	)

Compiles and finalizes the neural network model with the given loss.

Use this function to initialize neural network model. Various hyperparameter before compile the model can be set. Once compiled, any modification to the properties of model or layers/dataset/optimizer in the model will be restricted. Further, addition of layers or changing the optimizer/dataset of the model will not be permitted.

Since :: 6.0

Parameters:

[in]	model	The NNTrainer model handle.
[in]	...	hyperparameters for compiling the model

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_construct ( ml_train_model_h * model )

Constructs the neural network model.

Use this function to create neural network model. Privilege is needed if model contains save_path pointing to either media storage or external storage.

Since :: 6.0

Remarks:: If the function succeeds, model must be released using ml_train_model_destroy().; If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. Or, if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. If you want to access both storage, you must add all the privileges.

Parameters:

[out] model The NNTrainer model handle from the given description.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_PERMISSION_DENIED	Permission denied.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_construct_with_conf	(	const char *	model_conf,
		ml_train_model_h *	model
	)

Constructs the neural network model with the given configuration file.

Use this function to create neural network model with the given configuration file.

Since :: 6.0

Remarks:: If the function succeeds, model must be released using ml_train_model_destroy().

Parameters:

[in]	model_conf	The nntrainer model configuration file.
[out]	model	The NNTrainer model handle from the given description.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_destroy ( ml_train_model_h model )

Destructs the neural network model.

Use this function to destroy neural network model.

Since :: 6.0

Parameters:

[in] model The NNTrainer model handle from the given description.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_get_input_tensors_info	(	ml_train_model_h	model,
		ml_tensors_info_h *	info
	)

Gets input tensors information of the model.

Use this function to get input tensors information of the model. destroy info with ml_tensors_info_destroy() after use.

Since :: 6.5

Remarks:: model must be compiled before calling this function.; The returned info is newly created so it does not reflect future changes in the model.; On returning error, info must not be destroyed with ml_tensors_info_destroy()

Parameters:

[in]	model	The NNTrainer model handle.
[out]	info	The tensors information handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.
ML_ERROR_OUT_OF_MEMORY	Failed to allocate required memory.

int ml_train_model_get_layer	(	ml_train_model_h	model,
		const char *	layer_name,
		ml_train_layer_h *	layer
	)

Gets neural network layer from the model with the given name.

Use this function to get already created Neural Network Layer. The returned layer must not be released as it is owned by the model.

Since :: 7.0

Remarks:: The modification through ml_train_layer_set_property() after compiling the model by calling `ml_train_model_compile()` strictly restricted.

Parameters:

[in]	model	The NNTrainer model handler from the given description.
[in]	layer_name	Name of the already created layer.
[out]	layer	The NNTrainer Layer handler from the given description.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_get_output_tensors_info	(	ml_train_model_h	model,
		ml_tensors_info_h *	info
	)

Gets output tensors information of the model.

Use this function to get output tensors information of the model. destroy info with ml_tensors_info_destroy() after use.

Since :: 6.5

Remarks:: model must be compiled before calling this function.; the returned info is newly created so it does not reflect future changes in the model; On returning error, info must not be destroyed with ml_tensors_info_destroy()

Parameters:

[in]	model	The NNTrainer model handle.
[out]	info	The tensors information handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.
ML_ERROR_OUT_OF_MEMORY	Failed to allocate required memory.

int ml_train_model_get_summary	(	ml_train_model_h	model,
		ml_train_summary_type_e	verbosity,
		char **	summary
	)

Gets the summary of the neural network model.

Use this function to get the summary of the neural network model.

Since :: 6.0

Remarks:: If the function succeeds, summary should be released using free().

Parameters:

[in]	model	The NNTrainer model handle to get summary.
[in]	verbosity	Verbose level of the summary
[out]	summary	The summary of the current model. Avoid logic to parse and exploit summary if possible.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_get_weight	(	ml_train_model_h	model,
		const char *	layer_name,
		ml_tensors_data_h *	weight,
		ml_tensors_info_h *	info
	)

Gets weight tensors and information of the layer.

Use this function to get weight tensors and information of the layer. destroy info with ml_tensors_info_destroy() after use. destroy weight with ml_tensors_data_destroy() after use.

Since :: 8.0

Remarks:: model must be compiled before calling this function.; the returned info weight are newly created so it does not reflect future changes in the model; On returning error, info must not be destroyed with ml_tensors_info_destroy()

Parameters:

[in]	model	The NNTrainer model handle.
[in]	layer_name	The name of the layer handle.
[out]	weight	The weight tensors handle.
[out]	info	The weights information handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.
ML_ERROR_OUT_OF_MEMORY	Failed to allocate required memory.

int ml_train_model_load	(	ml_train_model_h	model,
		const char *	file_path,
		ml_train_model_format_e	format
	)

Loads the model.

Use this function to load the current model. format describes various formats in which various selections of the parameters of the models can be loaded. Some formats may load parameters required for training. Some other formats may load model configurations. Unless stated otherwise, loading model configuration requires a freshly constructed model with ml_train_model_construct() without ml_train_model_compile(), loading model parameter requires ml_train_model_compile() to be called upon the model before calling this function.

Since :: 6.5

Remarks:: If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. Or, if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. If you want to access both storage, you must add all the privileges.

Parameters:

[in]	model	The NNTrainer model handle to load.
[in]	file_path	File path to load the file.
[in]	format	Format flag to determine which format should be used to load.

Returns:: 0 on success, Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_PERMISSION_DENIED	Permission denied.
ML_ERROR_INVALID_PARAMETER	The given file_path is invalid or model is not in valid state to load.

See also:: ml_train_model_format_e to check which part of the model is loaded.

int ml_train_model_run	(	ml_train_model_h	model,
			...
	)

Trains the neural network model.

Use this function to train the compiled neural network model with the passed training hyperparameters. This function will return once the training, along with requested validation and testing, is completed.

Since :: 6.0

Parameters:

[in]	model	The NNTrainer model handle.
[in]	...	Hyperparameters for train model.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_save	(	ml_train_model_h	model,
		const char *	file_path,
		ml_train_model_format_e	format
	)

Saves the model.

Use this function to save the current model. format describes various formats in which various selections of the parameters of the models can be saved. Some formats may save parameters required for training. Some other formats may save model configurations. Unless stated otherwise, ml_train_model_compile() has to be called upon the model before calling this function.

Since :: 6.5

Remarks:: Saved ini, if any, is not guaranteed to be identical to the original ini that maybe used to load the model.; If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. Or, if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. If you want to access both storage, you must add all the privileges.

Parameters:

[in]	model	The NNTrainer model handle to save.
[in]	file_path	File path to save the file.
[in]	format	Format flag to determine which format should be used to save.

Returns:: 0 on success, Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_PERMISSION_DENIED	Permission denied.
ML_ERROR_INVALID_PARAMETER	The given file_path is invalid or taken, or model is not compiled.

See also:: ml_train_model_format_e to check which part of the model is saved.

int ml_train_model_set_dataset	(	ml_train_model_h	model,
		ml_train_dataset_h	dataset
	)

Sets the dataset (data provider) for the neural network model.

Use this function to set dataset for running the model. The dataset will provide training, validation and test data for the model. This transfers the ownership of the dataset to the network. No need to destroy the dataset once it is set to a model.

Since :: 6.0

Remarks:: Unsets the previously set dataset, if any. The previously set dataset must be freed using ml_train_dataset_destroy().

Parameters:

[in]	model	The NNTrainer model handle.
[in]	dataset	The NNTrainer dataset handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_model_set_optimizer	(	ml_train_model_h	model,
		ml_train_optimizer_h	optimizer
	)

Sets the optimizer for the neural network model.

Use this function to set neural network optimizer. This transfers the ownership of the optimizer to the network. No need to destroy the optimizer if it is to a model.

Since :: 6.0

Remarks:: Unsets the previously set optimizer, if any. The previously set optimizer must be freed using ml_train_optimizer_destroy().

Parameters:

[in]	model	The NNTrainer model handle.
[in]	optimizer	The NNTrainer optimizer handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_optimizer_create	(	ml_train_optimizer_h *	optimizer,
		ml_train_optimizer_type_e	type
	)

Creates a neural network optimizer.

Use this function to create neural network optimizer. If not set to a model, optimizer should be released using ml_train_optimizer_destroy(). If set to a model, optimizer is available until model is released.

Since :: 6.0

Remarks:: If the function succeeds, optimizer must be released using ml_train_optimizer_destroy(), if not set to a model. If set to a model, optimizer is available until the model is released.

Parameters:

[out]	optimizer	The NNTrainer optimizer handle.
[in]	type	The NNTrainer optimizer type.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_optimizer_destroy ( ml_train_optimizer_h optimizer )

Frees the neural network optimizer.

Use this function to destroy neural network optimizer. Fails if optimizer is owned by a model.

Since :: 6.0

Parameters:

[in] optimizer The NNTrainer optimizer handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_optimizer_set_lr_scheduler	(	ml_train_optimizer_h	optimizer,
		ml_train_lr_scheduler_h	lr_scheduler
	)

Sets the learning rate scheduler for the optimizer.

Use this function to set learning rate scheduler. This transfers the ownership of the scheduler to the optimizer. No need to destroy the optimizer if it is to a model.

Since :: 8.0

Remarks:: Unsets the previously set lr_scheduler, if any. The previously set lr_scheduler must be freed using ml_train_lr_scheduler_destroy().

Parameters:

[in]	optimizer	The NNTrainer optimizer handle.
[in]	lr_scheduler	The NNTrainer lr scheduler handle.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

int ml_train_optimizer_set_property	(	ml_train_optimizer_h	optimizer,
			...
	)

Sets the neural network optimizer property.

Use this function to set neural network optimizer property.

Since :: 6.0

Parameters:

[in]	optimizer	The NNTrainer optimizer handle.
[in]	...	Property values with NULL for termination.

Returns:: 0 on success. Otherwise a negative error value.

Return values:

ML_ERROR_NONE	Successful.
ML_ERROR_NOT_SUPPORTED	Not supported.
ML_ERROR_INVALID_PARAMETER	Invalid parameter.

Note:: For now the properties for Exponential learning rate scheduler(decay_rate, decay_steps) can be set using ml_train_optimizer_set_property() for backward compatibility. But ml_train_optimizer_set_property() will not support to set decay_rate, decay_steps properties from later version. Use ml_train_lr_scheduler_set_property() instead.

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation