Tizen Native API  7.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_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_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.

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_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]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 passed along with ml_train_dataset_add_generator().
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
 } 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 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 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

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

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.

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_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]datasetThe NNTrainer dataset handle.
[in]modeThe phase where this file should be used.
[in]filefile path.
Returns:
0 on success. Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_PERMISSION_DENIEDPermission denied.
ML_ERROR_INVALID_PARAMETERInvalid parameter.

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]datasetThe NNTrainer dataset handle.
[in]modeThe phase where this generator should be used.
[in]cbCallback to be used for the generator.
[in]user_datauser_data to be fed when cb is being called.
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 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]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.
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]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.

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

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

Sets the neural network dataset property.

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

Since :
6.5
Parameters:
[in]datasetThe NNTrainer dataset handle.
[in]modeThe 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_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 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;
 }

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]...hyperparameters 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. 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]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_PERMISSION_DENIEDPermission denied.
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.

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_destory()
Parameters:
[in]modelThe NNTrainer model handle.
[out]infoThe tensors information 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.
ML_ERROR_OUT_OF_MEMORYFailed 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 deleted as it is owned by the model.

Since :
7.0
Remarks:
The modification through ml_trin_layer_set_property() after compiling the model by calling `ml_train_model_compile()` strictly restricted.
Parameters:
[in]modelThe NNTrainer model handler from the given description.
[in]layer_nameName of the already created layer.
[out]layerThe NNTrainer Layer handler 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.

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_destory()
Parameters:
[in]modelThe NNTrainer model handle.
[out]infoThe tensors information 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.
ML_ERROR_OUT_OF_MEMORYFailed 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]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_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]modelThe NNTrainer model handle to load.
[in]file_pathFile path to load the file.
[in]formatFormat flag to determine which format should be used to load.
Returns:
0 on success, Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_PERMISSION_DENIEDPermission denied.
ML_ERROR_INVALID_PARAMETERThe 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]modelThe NNTrainer model handle.
[in]...Hyperparameters 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.
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]modelThe NNTrainer model handle to save.
[in]file_pathFile path to save the file.
[in]formatFormat flag to determine which format should be used to save.
Returns:
0 on success, Otherwise a negative error value.
Return values:
ML_ERROR_NONESuccessful.
ML_ERROR_NOT_SUPPORTEDNot supported.
ML_ERROR_PERMISSION_DENIEDPermission denied.
ML_ERROR_INVALID_PARAMETERThe 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.

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.