Tizen Native API  6.0

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_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_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_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.

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 an NNTrainer model.
typedef void * ml_train_layer_h
 A handle of an NNTrainer layer.
typedef void * ml_train_optimizer_h
 A handle of an NNTrainer optimizer.
typedef void * ml_train_dataset_h
 A handle of an 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_create_with_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.
Parameters:
[out]inputContainer to hold all the input data. Should not be freed by the user.
[out]labelContainer to hold corresponding label data. Should not be freed by the user.
[out]lastContainer 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_dataUser application's private data.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_INVALID_PARAMETERInvalid 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
   return ML_ERROR_NONE;
 }

 // 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;
 ml_train_dataset_h handle;

 status = ml_train_dataset_create_with_generator(&handle,
      rand_dataset_generator, NULL, NULL);
 if (status != ML_ERROR_NONE) {
    // handle error case.
    return status;
 }

 // Destroy the handle if not added to a model.
 status = ml_train_layer_destroy(handle);
 if (status != ML_ERROR_NONE) {
    // handle error case
    return status;
 }
typedef void* ml_train_dataset_h

A handle of an NNTrainer dataset.

Since :
6.0
typedef void* ml_train_layer_h

A handle of an NNTrainer layer.

Since :
6.0
typedef void* ml_train_model_h

A handle of an NNTrainer model.

Since :
6.0
typedef void* ml_train_optimizer_h

A handle of an NNTrainer optimizer.

Since :
6.0

Enumeration Type Documentation

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_UNKNOWN 

Unknown Layer

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

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_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.

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

Since :
6.0
Parameters:
[out]datasetThe 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_fileThe dataset file for training.
[in]valid_fileThe dataset file for validating. Can be null.
[in]test_fileThe dataset file for testing. Can be null.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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

Use this function to create a neural network dataset using generators. The generators will provide data representing a single input batch. 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]datasetThe 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_cbThe dataset generator for training.
[in]valid_cbThe dataset generator for validating. Can be null.
[in]test_cbThe dataset generator for testing. Can be null.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

Frees the neural network dataset.

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

Since :
6.0
Parameters:
[in]datasetThe NNTrainer dataset handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

Sets the neural network dataset property.

Use this function to set dataset property.

Since :
6.0
Parameters:
[in]datasetThe NNTrainer dataset handle.
[in]...Property values with NULL for termination.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]layerThe NNTrainer layer handle from the given description.
[in]typeThe NNTrainer layer type
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]layerThe NNTrainer layer handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid 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]layerThe NNTrainer layer handle.
[in]...Property values with NULL for termination.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid 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 hyperparmeters 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;
 }

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]modelThe NNTrainer model handle.
[in]layerThe NNTrainer layer handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid 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]modelThe NNTrainer model handle.
[in]...hyperparmeters for compiling the model
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

Constructs the neural network model.

Use this function to create neural network model.

Since :
6.0
Remarks:
If the function succeeds, model must be released using ml_train_model_destroy().
http://tizen.org/privilege/mediastorage is needed if model is saved to media storage.
http://tizen.org/privilege/externalstorage is needed if model is saved to external storage.
Parameters:
[out]modelThe NNTrainer model handle from the given description.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid 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_confThe nntrainer model configuration file.
[out]modelThe NNTrainer model handle from the given description.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

Destructs the neural network model.

Use this function to destroy neural network model.

Since :
6.0
Parameters:
[in]modelThe NNTrainer model handle from the given description.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.
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]modelThe NNTrainer model handle to get summary.
[in]verbosityVerbose level of the summary
[out]summaryThe 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_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.
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]modelThe NNTrainer model handle.
[in]...Hyperparmeters for train model.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]modelThe NNTrainer model handle.
[in]datasetThe NNTrainer dataset handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]modelThe NNTrainer model handle.
[in]optimizerThe NNTrainer optimizer handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]optimizerThe NNTrainer optimizer handle.
[in]typeThe NNTrainer optimizer type.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]optimizerThe NNTrainer optimizer handle.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

Sets the neural network optimizer property.

Use this function to set neural network optimizer property.

Since :
6.0
Parameters:
[in]optimizerThe NNTrainer optimizer handle.
[in]...Property values with NULL for termination.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_INVALID_PARAMETERInvalid parameter.