`train_dl_model_batch`

— Train a deep learning model.

**train_dl_model_batch**( : : *DLModelHandle*, *DLSampleBatch* : *DLTrainResult*)

The operator `train_dl_model_batch`

performs a training step of the
deep-learning model contained in * DLModelHandle*.
The current loss values are returned in the dictionary

`DLTrainResult`

A training step means here to perform a single update of the weights,
based on the batch images given in * DLSampleBatch*.
The optimization algorithm used is explained further in the subsection
“Further Information on the Algorithms” below.
For more information on how to train a network, please see the subchapter
“The Network and the Training Process” in Deep Learning.

To successfully train the model, its applicable hyperparameters need to be
set and the training data handed over according to the model requirements.
For information to the hyperparameters, see the chapter of the corresponding
model and the general chapter Deep Learning.
The training data consists of images and corresponding information.
This operator expects one batch of training data,
handed over in the tuple of dictionaries * DLSampleBatch*.
Thus, the tuple

`DLSampleBatch`

`batch_size`

dictionaries `DLSample`

. Such a `DLSample`

is created
out of `DLDataset`

for every image sample, e.g., by the
procedure `gen_dl_samples`

.
See the chapter Deep Learning / Model for further information to
the used dictionaries and their keys.
In the output dictionary * DLTrainResult* you get the
current value of the total loss as the value for the key

`total_loss`

as well as the values for all other losses included
in your model.
During training, a nonlinear optimization algorithm is applied with the goal to minimize the value of the total loss function. The latter one is determined based on the prediction of the neural network for the current batch of images. The algorithm used for optimization is stochastic gradient descent (SGD). It updates the layers' weights of the previous iteration , , to the new values at iteration as follows:

Here, is the learning rate, the momentum, the total loss, and the gradient of the total loss with respect to the weights. The variable is used to include the influence of the momentum .

The different models may have several losses implemented, which are summed up. To this sum the regularization term is added, which generally penalizes large weights, and together they form the total loss.

The different types of losses are:

`Huber Loss`

(model of*'type'*=*'detection'*):-
The 'Huber Loss' is also known as 'Smooth L1 Loss'. The total 'Huber Loss' is the sum of the contributions from all bounding box variables of all found instances in the batch. For a single bounding box variable this contribution defined as follows: Thereby, denotes a bounding box variable and a parameter fixed to a value of 0.11.

`Focal Loss`

(model of*'type'*=*'detection'*):-
The total 'Focal Loss' is the sum of the contributions from all found instance in the batch. For a single sample, this contribution is defined as follows: where is a parameter fixed to a value of 2. stands for the 'class_weight' of the -th class and , are defined as Here, is a tuple of the model's estimated probabilities for each of the -many classes, and is a one-hot encoded target vector that encodes the class of the annotation.

`Multinomial Logistic Loss`

(model of*'type'*=*'segmentation'*):-
The 'Multinomial Logistic Loss' is also known as 'Cross Entropy Loss'. It is defined as follows:

Here, is the predicted result which depends on the network weights and the input batch . is a one-hot encoded target vector that encodes the label of the -th image of the batch containing -many images, and shall be understood to be a vector such that is applied on each component of .

The regularization term is a weighted
-norm involving all weights except for biases.
Its influence can be controlled through . Latter one is
the hyperparameter *'weight_prior'*, which can be set with
`set_dl_model_param`

.
Here the index runs over all weights of the network, except
for the biases which are not regularized. The regularization term
generally penalizes large weights, thus
pushing the weights towards zero, which effectively reduces the
complexity of the model.

To run this operator, cuDNN and cuBLAS are required when *'runtime'*
is set to *'gpu'*, see `set_dl_classifier_param`

.
For further details, please refer to the `“Installation Guide”`

,
paragraph “Requirements for Deep Learning”.

- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Automatically parallelized on internal data level.

`DLModelHandle`

`→`

(handle)
Deep learning model handle.

`DLSampleBatch`

`→`

(handle)
Tuple of Dictionaries with input images and corresponding information.

`DLTrainResult`

`→`

(handle)
Dictionary with the train result data.

If the parameters are valid, the operator `train_dl_model_batch`

returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

`read_dl_model`

,
`set_dl_model_param`

,
`get_dl_model_param`

Deep Learning Training