TrainingOptionsSGDM
Training options for stochastic gradient descent with momentum
Description
Use a TrainingOptionsSGDM
object to set training options for
the stochastic gradient descent with momentum optimizer, including learning rate
information, L_{2} regularization factor, and minibatch
size.
Creation
Create a TrainingOptionsSGDM
object using trainingOptions
and specifying "sgdm"
as the first
input argument.
Properties
SGDM
MaxEpochs
— Maximum number of epochs
30
(default)  positive integer
Maximum number of epochs (full passes of the data) to use for training, specified as a positive integer.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
MiniBatchSize
— Size of minibatch
128
(default)  positive integer
Size of the minibatch to use for each training iteration, specified as a positive integer. A minibatch is a subset of the training set that is used to evaluate the gradient of the loss function and update the weights.
If the minibatch size does not evenly divide the number of training samples, then the software discards the training data that does not fit into the final complete minibatch of each epoch. If the minibatch size is smaller than the number of training samples, then the software does not discard any data.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
Shuffle
— Option for data shuffling
"once"
(default)  "never"
 "everyepoch"
Option for data shuffling, specified as one of these values:
"once"
— Shuffle the training and validation data once before training."never"
— Do not shuffle the data."everyepoch"
— Shuffle the training data before each training epoch, and shuffle the validation data before each neural network validation. If the minibatch size does not evenly divide the number of training samples, then the software discards the training data that does not fit into the final complete minibatch of each epoch. To avoid discarding the same data every epoch, set theShuffle
training option to"everyepoch"
.
InitialLearnRate
— Initial learning rate
0.01
(default)  positive scalar
Initial learning rate used for training, specified as a positive scalar.
If the learning rate is too low, then training can take a long time. If the learning rate is too high, then training might reach a suboptimal result or diverge.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
LearnRateSchedule
— Learning rate schedule
"none"
(default)  character vector  string array  builtin or custom learning rate schedule object  function handle  cell array
Learning rate schedule, specified as a character vector or string scalar of a builtin learning rate schedule name, a string array of names, a builtin or custom learning rate schedule object, a function handle, or a cell array of names, metric objects, and function handles.
BuiltIn Learning Rate Schedule Names
Specify learning rate schedules as a string scalar, character vector, or a string or cell array of one or more of these names:
Name  Description  Plot 

"none"  No learning rate schedule. This schedule keeps the learning rate constant. 

"piecewise"  Piecewise learning rate schedule. Every 10 epochs, this schedule drops the learn rate by a factor of 10. 

"warmup" (since R2024b)  Warmup learning rate schedule. For 5 iterations, this schedule ramps up the learning rate to the base learning rate. 

"polynomial" (since R2024b)  Polynomial learning rate schedule. Every epoch, this schedule drops the learning rate using a power law with a unitary exponent. 

"exponential" (since R2024b)  Exponential learning rate schedule. Every epoch, this schedule decays
the learning rate by a factor of 10 . 

"cosine" (since R2024b)  Cosine learning rate schedule. Every epoch, this schedule drops the learn rate using a cosine formula. 

"cyclical" (since R2024b)  Cyclical learning rate schedule. For periods of 10 epochs, this schedule increases the learning rate from the base learning rate for 5 epochs and then decreases the learning rate for 5 epochs. 

BuiltIn Learning Rate Schedule Object (since R2024b)
If you need more flexibility than what the string options provide, you can use builtin learning rate schedule objects:
piecewiseLearnRate
— A piecewise learning rate schedule object drops the learning rate periodically by multiplying it by a specified factor. Use this object to customize the drop factor and period of the piecewise schedule.Before R2024b: Customize the piecewise drop factor and period using the
LearnRateDropFactor
andLearnRateDropPeriod
training options, respectively.warmupLearnRate
— A warmup learning rate schedule object ramps up the learning for a specified number of iterations. Use this object to customize the initial and final learning rate factors and the number of steps of the warm up schedule.polynomialLearnRate
— A polynomial learning rate schedule drops the learning rate using a power law. Use this object to customize the initial and final learning rate factors, the exponent, and the number of steps of the polynomial schedule.exponentialLearnRate
— An exponential learning rate schedule decays the learning rate by a specified factor. Use this object to customize the drop factor and period of the exponential schedule.cosineLearnRate
— A cosine learning rate schedule object drops the learning rate using a cosine curve and incorporates warm restarts. Use this object to customize the initial and final learning rate factors, the period, and the period growth factor of the cosine schedule.cyclicalLearnRate
— A cyclical learning rate schedule periodically increases and decreases the learning rate. Use this option to customize the maximum factor, period, and step ratio of the cyclical schedule.
Custom Learning Rate Schedule (since R2024b)
For additional flexibility, you can define a custom learning rate schedule as a function handle or custom class that inherits from deep.LearnRateSchedule
.
Custom learning rate schedule function handle — If the learning rate schedule you need is not a builtin learning rate schedule, then you can specify custom learning rate schedules using a function handle. To specify a custom schedule, use a function handle with the syntax
learningRate = f(baseLearningRate,epoch)
, wherebaseLearningRate
is the base learning rate, andepoch
is the epoch number.Custom learn rate schedule object — If you need more flexibility that what function handles provide, then you can define a custom learning rate schedule class that inherits from
deep.LearnRateSchedule
.
Multiple Learning Rate Schedules (since R2024b)
You can combine multiple learning rate schedules by specifying multiple schedules as a string
or cell array and then the software applies the schedules in order, starting with the first
element. At most one of the schedules can be infinite (schedules than continue indefinitely,
such as "cyclical"
and objects with the NumSteps
property set to Inf
) and the infinite schedule must be the last element
of the array.
LearnRateDropPeriod
— Number of epochs for dropping the learning rate
10
(default)  positive integer
Number of epochs for dropping the learning rate, specified as a positive integer. This option is valid only when the LearnRateSchedule
training option is "piecewise"
.
The software multiplies the global learning rate with the drop factor every time the specified number of epochs passes. Specify the drop factor using the LearnRateDropFactor
training option.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
LearnRateDropFactor
— Factor for dropping the learning rate
0.1
(default)  scalar from 0
to 1
Factor for dropping the learning rate, specified as a scalar from 0
to 1
. This option is valid only when the LearnRateSchedule
training option is "piecewise"
.
LearnRateDropFactor
is a multiplicative factor to apply to the learning rate every time a certain number of epochs passes. Specify the number of epochs using the LearnRateDropPeriod
training option.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
Momentum
— Contribution of previous step
0.9
(default)  scalar from 0
to 1
Contribution of the parameter update step of the previous iteration to the current iteration of stochastic gradient descent with momentum, specified as a scalar from 0
to 1
.
A value of 0
means no contribution from the previous step, whereas a value of 1
means maximal contribution from the previous step. The default value works well for most tasks.
For more information, see Stochastic Gradient Descent with Momentum.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
Data Formats
InputDataFormats
— Description of input data dimensions
"auto"
(default)  string array  cell array of character vectors  character vector
Since R2023b
Description of the input data dimensions, specified as a string array, character vector, or cell array of character vectors.
If InputDataFormats
is "auto"
, then the software uses
the formats expected by the network input. Otherwise, the software uses the specified
formats for the corresponding network input.
A data format is a string of characters, where each character describes the type of the corresponding data dimension.
The characters are:
"S"
— Spatial"C"
— Channel"B"
— Batch"T"
— Time"U"
— Unspecified
For example, consider an array containing a batch of sequences where the first, second,
and third dimensions correspond to channels, observations, and time steps, respectively. You
can specify that this array has the format "CBT"
(channel, batch,
time).
You can specify multiple dimensions labeled "S"
or "U"
.
You can use the labels "C"
, "B"
, and
"T"
once each, at most. The software ignores singleton trailing
"U"
dimensions after the second dimension.
For a neural networks with multiple inputs net
, specify an array of
input data formats, where InputDataFormats(i)
corresponds to the
input net.InputNames(i)
.
For more information, see Deep Learning Data Formats.
Data Types: char
 string
 cell
TargetDataFormats
— Description of target data dimensions
"auto"
(default)  string array  cell array of character vectors  character vector
Since R2023b
Description of the target data dimensions, specified as one of these values:
"auto"
— If the target data has the same number of dimensions as the input data, then thetrainnet
function uses the format specified byInputDataFormats
. If the target data has a different number of dimensions to the input data, then thetrainnet
function uses the format expected by the loss function.String array, character vector, or cell array of character vectors — The
trainnet
function uses the data formats you specify.
A data format is a string of characters, where each character describes the type of the corresponding data dimension.
The characters are:
"S"
— Spatial"C"
— Channel"B"
— Batch"T"
— Time"U"
— Unspecified
For example, consider an array containing a batch of sequences where the first, second,
and third dimensions correspond to channels, observations, and time steps, respectively. You
can specify that this array has the format "CBT"
(channel, batch,
time).
You can specify multiple dimensions labeled "S"
or "U"
.
You can use the labels "C"
, "B"
, and
"T"
once each, at most. The software ignores singleton trailing
"U"
dimensions after the second dimension.
For more information, see Deep Learning Data Formats.
Data Types: char
 string
 cell
Monitoring
Plots
— Plots to display during neural network training
"none"
(default)  "trainingprogress"
Plots to display during neural network training, specified as one of these values:
"none"
— Do not display plots during training."trainingprogress"
— Plot training progress.
The plot shows the minibatch loss, validation loss, training minibatch and
validation metrics as specified by the Metrics
property, and additional information about the training
progress.
To programmatically open and close the training progress plot after training, use the show
and close
functions with the second output of the trainnet
function. You can use the show
function to view the training progress even if the Plots
training option is specified as "none"
.
To switch the yaxis scale to logarithmic, use the axes toolbar.
For more information about the plot, see Monitor Deep Learning Training Progress.
Metrics
— Metrics to monitor
[]
(default)  character vector  string array  function handle  deep.DifferentiableFunction
object (since R2024a)
 cell array  metric object
Since R2023b
Metrics to monitor, specified as one of these values:
Builtin metric or loss function name — Specify metrics as a string scalar, character vector, or a cell array or string array of one or more of these names:
Metrics:
"accuracy"
— Accuracy (also known as top1 accuracy)"auc"
— Area under ROC curve (AUC)"fscore"
— Fscore (also known as F_{1}score)"precision"
— Precision"recall"
— Recall"rmse"
— Root mean squared error"mape"
— Mean absolute percentage error (MAPE) (since R2024b)
Loss functions:
"crossentropy"
— Crossentropy loss for classification tasks. (since R2024b)"indexcrossentropy"
— Index crossentropy loss for classification tasks. (since R2024b)"binarycrossentropy"
— Binary crossentropy loss for binary and multilabel classification tasks. (since R2024b)"mae"
/"meanabsoluteerror"
/"l1loss"
— Mean absolute error for regression tasks. (since R2024b)"mse"
/"meansquarederror"
/"l2loss"
— Mean squared error for regression tasks. (since R2024b)"huber"
— Huber loss for regression tasks (since R2024b)
Note that setting the loss function as
"crossentropy"
and specifying"indexcrossentropy"
as a metric or setting the loss function as"indexcrossentropy"
and specifying"crossentropy"
as a metric is not supported.
Builtin metric object — If you need more flexibility, you can use builtin metric objects. The software supports these builtin metric objects:
When you create a builtin metric object, you can specify additional options such as the averaging type and whether the task is singlelabel or multilabel.
Custom metric function handle — If the metric you need is not a builtin metric, then you can specify custom metrics using a function handle. The function must have the syntax
metric = metricFunction(Y,T)
, whereY
corresponds to the network predictions andT
corresponds to the target responses. For networks with multiple outputs, the syntax must bemetric = metricFunction(Y1,…,YN,T1,…TM)
, whereN
is the number of outputs andM
is the number of targets. For more information, see Define Custom Metric Function.Note
When you have data in minibatches, the software computes the metric for each minibatch and then returns the average of those values. For some metrics, this behavior can result in a different metric value than if you compute the metric using the whole data set at once. In most cases, the values are similar. To use a custom metric that is not batchaveraged for the data, you must create a custom metric object. For more information, see Define Custom Deep Learning Metric Object.
deep.DifferentiableFunction
object (since R2024a) — Function object with custom backward function. For categorical targets, the software automatically converts the categorical values to onehot encoded vectors and passes them to the metric function. For more information, see Define Custom Deep Learning Operations.Custom metric object — If you need greater customization, then you can define your own custom metric object. For an example that shows how to create a custom metric, see Define Custom Metric Object. For general information about creating custom metrics, see Define Custom Deep Learning Metric Object.
If you specify a metric as a function handle, a deep.DifferentiableFunction
object, or a custom metric object and train the neural network using the
trainnet
function, then the layout of the targets that the software
passes to the metric depends on the data type of the targets, and the loss function that you
specify in the trainnet
function and the other metrics that you specify:
If the targets are numeric arrays, then the software passes the targets to the metric directly.
If the loss function is
"indexcrossentropy"
and the targets are categorical arrays, then the software automatically converts the targets to numeric class indices and passes them to the metric.For other loss functions, if the targets are categorical arrays, then the software automatically converts the targets to onehot encoded vectors and then passes them to the metric.
This option supports the trainnet
and
trainBERTDocumentClassifier
(Text Analytics Toolbox) functions only.
Example: Metrics=["accuracy","fscore"]
Example: Metrics={"accuracy",@myFunction,precisionObj}
ObjectiveMetricName
— Name of objective metric
"loss"
(default)  string scalar  character vector
Since R2024a
Name of objective metric to use for early stopping and returning the best network, specified as a string scalar or character vector.
The metric name must be "loss"
or match the name of a metric specified by
the Metrics
argument. Metrics specified using function handles are not
supported. To specify the ObjectiveMetricName
value as the name of a
custom metric, the value of the Maximize
property of the custom metric
object must be nonempty. For more information, see Define Custom Deep Learning Metric Object.
For more information about specifying the objective metric for early stopping, see ValidationPatience
. For more information about returning the best network using the objective metric, see OutputNetwork
.
Data Types: char
 string
Verbose
— Flag to display training progress information
1
(true
) (default)  0
(false
)
Flag to display training progress information in the command window, specified as
1
(true
) or 0
(false
).
When you use the trainnet
function, the verbose output displays a
table with these variables:
Variable  Description 

Iteration  Iteration number. 
Epoch  Epoch number. 
TimeElapsed  Time elapsed in hours, minutes, and seconds. 
LearnRate  Learning rate. 
TrainingLoss  Training loss. 
ValidationLoss  Validation loss. If you do not specify validation data, then the software does not display this information. 
If you specify additional metrics in the training options, then
they also appear in the verbose output. For example, if you set the Metrics
training option to "accuracy"
, then the information includes the
TrainingAccuracy
and ValidationAccuracy
variables.
When training stops, the verbose output displays the reason for stopping.
To specify validation data, use the ValidationData
training option.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
 logical
VerboseFrequency
— Frequency of verbose printing
50
(default)  positive integer
Frequency of verbose printing, which is the number of iterations between printing to the Command Window, specified as a positive integer.
If you validate the neural network during training, then the software also prints to the command window every time validation occurs.
To enable this property, set the Verbose
training option to
1
(true
).
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
Validation
ValidationData
— Data to use for validation during training
[]
(default)  datastore  table  cell array  minibatchqueue
object (since R2024a)
Data to use for validation during training, specified as []
, a
datastore, a table, a cell array, or a minibatchqueue
object that
contains the validation predictors and targets.
During training, the software uses the validation data to calculate the validation loss and
metric values. To specify the validation frequency, use the ValidationFrequency
training option. You can also use the validation data to
stop training automatically when the validation objective metric stops improving. By
default, the objective metric is set to the loss. To turn on automatic validation stopping,
use the ValidationPatience
training option.
If ValidationData
is []
, then the software does
not validate the neural network during training.
If your neural network has layers that behave differently during prediction than during training (for example, dropout layers), then the validation loss can be lower than the training loss.
The software shuffles the validation data according to the Shuffle
training option. If
Shuffle
is "everyepoch"
, then the software
shuffles the validation data before each neural network validation.
The supported formats depend on the training function that you use.
trainnet
Function
Specify the validation data as a datastore, minibatchqueue
object, or the
cell array {predictors,targets}
, where predictors
contains the validation predictors and targets
contains the validation
targets. Specify the validation predictors and targets using any of the formats supported by
the trainnet
function.
For more information, see the input arguments of the trainnet
function.
trainBERTDocumentClassifier
Function (Text Analytics Toolbox)
Specify the validation data as one of these values:
Cell array
{documents,targets}
, wheredocuments
contains the input documents, andtargets
contains the document labels.Table, where the first variable contains the input documents and the second variable contains the document labels.
For more information, see the input arguments of the trainBERTDocumentClassifier
(Text Analytics Toolbox) function.
ValidationFrequency
— Frequency of neural network validation
50
(default)  positive integer
Frequency of neural network validation in number of iterations, specified as a positive integer.
The ValidationFrequency
value is the number of iterations between
evaluations of validation metrics. To specify validation data, use the ValidationData
training option.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
ValidationPatience
— Patience of validation stopping
Inf
(default)  positive integer
Patience of validation stopping of neural network training, specified as a positive integer or Inf
.
ValidationPatience
specifies the number of times that the objective metric on the validation set can be worse than or equal to the previous best value before neural network training stops. If ValidationPatience
is Inf
, then the values of the validation metric do not cause training to stop early. The software aims to maximize or minimize the metric, as specified by the Maximize
property of the metric. When the objective metric is "loss"
, the software aims to minimize the loss value.
The returned neural network depends on the OutputNetwork
training option. To return the neural network with the best validation metric value, set the OutputNetwork
training option to "bestvalidation"
.
Before R2024a: The software computes the validation patience using the validation loss value.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
OutputNetwork
— Neural network to return when training completes
"auto"
(default)  "lastiteration"
 "bestvalidation"
Neural network to return when training completes, specified as one of the following:
"auto"
– Use"bestvalidation"
ifValidationData
is specified. Otherwise, use"lastiteration"
."bestvalidation"
– Return the neural network corresponding to the training iteration with the best validation metric value, where the metric to optimize is specified by theObjectiveMetricName
option. To use this option, you must specify theValidationData
training option."lastiteration"
– Return the neural network corresponding to the last training iteration.
Regularization and Normalization
L2Regularization
— Factor for L_{2} regularization
0.0001
(default)  nonnegative scalar
Factor for L_{2} regularization (weight decay), specified as a nonnegative scalar. For more information, see L2 Regularization.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
ResetInputNormalization
— Option to reset input layer normalization
1
(true
) (default)  0
(false
)
Option to reset input layer normalization, specified as one of the following:
1
(true
) — Reset the input layer normalization statistics and recalculate them at training time.0
(false
) — Calculate normalization statistics at training time when they are empty.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
 logical
BatchNormalizationStatistics
— Mode to evaluate statistics in batch normalization layers
"auto"
(default)  "population"
 "moving"
Mode to evaluate the statistics in batch normalization layers, specified as one of the following:
"population"
— Use the population statistics. After training, the software finalizes the statistics by passing through the training data once more and uses the resulting mean and variance."moving"
— Approximate the statistics during training using a running estimate given by update steps$$\begin{array}{l}{\mu}^{*}={\lambda}_{\mu}\widehat{\mu}+(1{\lambda}_{\mu})\mu \\ {\sigma}^{2}{}^{*}={\lambda}_{{\sigma}^{2}}\widehat{{\sigma}^{2}}\text{}\text{+}\text{}\text{(1}{\lambda}_{{\sigma}^{2}})\text{}{\sigma}^{2}\end{array}$$
where $${\mu}^{*}$$ and $${\sigma}^{2}{}^{*}$$ denote the updated mean and variance, respectively, $${\lambda}_{\mu}$$ and $${\lambda}_{{\sigma}^{2}}$$ denote the mean and variance decay values, respectively, $$\widehat{\mu}$$ and $$\widehat{{\sigma}^{2}}$$ denote the mean and variance of the layer input, respectively, and $$\mu $$ and $${\sigma}^{2}$$ denote the latest values of the moving mean and variance values, respectively. After training, the software uses the most recent value of the moving mean and variance statistics. This option supports CPU and single GPU training only.
"auto"
— Use the"moving"
option.
Gradient Clipping
GradientThreshold
— Gradient threshold
Inf
(default)  positive scalar
Gradient threshold, specified as Inf
or a positive scalar. If the gradient exceeds the value of GradientThreshold
, then the gradient is clipped according to the GradientThresholdMethod
training option.
For more information, see Gradient Clipping.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
GradientThresholdMethod
— Gradient threshold method
"l2norm"
(default)  "globall2norm"
 "absolutevalue"
Gradient threshold method used to clip gradient values that exceed the gradient threshold, specified as one of the following:
"l2norm"
— If the L_{2} norm of the gradient of a learnable parameter is larger thanGradientThreshold
, then scale the gradient so that the L_{2} norm equalsGradientThreshold
."globall2norm"
— If the global L_{2} norm, L, is larger thanGradientThreshold
, then scale all gradients by a factor ofGradientThreshold/
L. The global L_{2} norm considers all learnable parameters."absolutevalue"
— If the absolute value of an individual partial derivative in the gradient of a learnable parameter is larger thanGradientThreshold
, then scale the partial derivative to have magnitude equal toGradientThreshold
and retain the sign of the partial derivative.
For more information, see Gradient Clipping.
Sequence
SequenceLength
— Option to pad or truncate sequences
"longest"
(default)  "shortest"
 positive integer
Option to pad, truncate, or split input sequences, specified as one of the following:
"longest"
— Pad sequences in each minibatch to have the same length as the longest sequence. This option does not discard any data, though padding can introduce noise to the neural network."shortest"
— Truncate sequences in each minibatch to have the same length as the shortest sequence. This option ensures that no padding is added, at the cost of discarding data.
To learn more about the effect of padding, truncating, and splitting the input sequences, see Sequence Padding and Truncation.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
 char
 string
SequencePaddingDirection
— Direction of padding or truncation
"right"
(default)  "left"
Direction of padding or truncation, specified as one of these options:
"right"
— Pad or truncate sequences on the right. The sequences start at the same time step and the software truncates or adds padding to the end of each sequence."left"
— Pad or truncate sequences on the left. The software truncates or adds padding to the start of each sequence so that the sequences end at the same time step.
Because recurrent layers process sequence data one time step at a time, when the recurrent
layer OutputMode
property is "last"
, any padding in
the final time steps can negatively influence the layer output. To pad or truncate sequence
data on the left, set the SequencePaddingDirection
argument to "left"
.
For sequencetosequence neural networks (when the OutputMode
property is
"sequence"
for each recurrent layer), any padding in the first time
steps can negatively influence the predictions for the earlier time steps. To pad or
truncate sequence data on the right, set the SequencePaddingDirection
option to "right"
.
To learn more about the effects of padding and truncating sequences, see Sequence Padding and Truncation.
SequencePaddingValue
— Value by which to pad input sequences
0
(default)  scalar
Value by which to pad the input sequences, specified as a scalar.
Do not pad sequences with NaN
, because doing so can
propagate errors through the neural network.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
Hardware and Acceleration
ExecutionEnvironment
— Hardware resource for training neural network
"auto"
(default)  "cpu"
 "gpu"
 "multigpu"
 "parallelauto"
 "parallelcpu"
 "parallelgpu"
Hardware resource for training neural network, specified as one of these values:
"auto"
– Use a local GPU if one is available. Otherwise, use the local CPU."cpu"
– Use the local CPU."gpu"
– Use the local GPU."multigpu"
– Use multiple GPUs on one machine, using a local parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts a parallel pool with pool size equal to the number of available GPUs."parallelauto"
– Use a local or remote parallel pool. If there is no current parallel pool, the software starts one using the default cluster profile. If the pool has access to GPUs, then only workers with a unique GPU perform training computation and excess workers become idle. If the pool does not have GPUs, then training takes place on all available CPU workers instead. (since R2024a)Before R2024a: Use
"parallel"
instead."parallelcpu"
– Use CPU resources in a local or remote parallel pool, ignoring any GPUs. If there is no current parallel pool, the software starts one using the default cluster profile. (since R2023b)"parallelgpu"
– Use GPUs in a local or remote parallel pool. Excess workers become idle. If there is no current parallel pool, the software starts one using the default cluster profile. (since R2023b)
The "gpu"
, "multigpu"
,
"parallelauto"
, "parallelcpu"
, and
"parallelgpu"
options require Parallel Computing Toolbox™. To use a GPU for deep learning, you
must also have a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). If you
choose one of these options and Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.
For more information on when to use the different execution environments, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.
To see an improvement in performance when training in parallel, try scaling up the MiniBatchSize
and InitialLearnRate
training options by the number of GPUs.
PreprocessingEnvironment
— Environment for fetching and preprocessing data
"serial"
(default)  "background
 "parallel"
Since R2024a
Environment for fetching and preprocessing data from a datastore during training, specified as one of these values:
"serial"
– Fetch and preprocess data in serial."background"
– Fetch and preprocess data using the background pool."parallel"
– Fetch and preprocess data using parallel workers. The software opens a parallel pool using the default profile, if a local pool is not currently open. Nonlocal parallel pools are not supported. Using this option requires Parallel Computing Toolbox. This option is not supported when training in parallel (when theExecutionEnvironment
option is"parallelauto"
,"parallelcpu"
,"parallelgpu"
, or"multigpu"
).
To use the "background"
or "parallel"
options, the input datastore must be subsettable or partitionable. Custom datastores must implement the matlab.io.datastore.Subsettable
class.
The "background"
and "parallel"
options are not
supported when the Shuffle
option is "never"
.
If you use the "background"
and "parallel"
options,
then training is nondeterministic even if you use the deep.gpu.deterministicAlgorithms
function.
Use the "background"
option when your minibatches require significant
preprocessing. If your preprocessing is not supported on threads, or if you need to control
the number of workers, use the "parallel"
option. For more information
about the preprocessing environment, see Preprocess Data in the Background or in Parallel.
Before R2024a: To preprocess data in parallel,
set the DispatchInBackground
training option to
1 (true)
.
Acceleration
— Performance optimization
"auto"
(default)  "none"
Since R2024a
Performance optimization, specified as one of these values:
"auto"
– Automatically apply a number of optimizations suitable for the input network and hardware resources."none"
– Disable all optimizations.
Checkpoints
CheckpointPath
— Path for saving checkpoint neural networks
""
(default)  string scalar  character vector
Path for saving the checkpoint neural networks, specified as a string scalar or character vector.
If you do not specify a path (that is, you use the default
""
), then the software does not save any checkpoint neural networks.If you specify a path, then the software saves checkpoint neural networks to this path and assigns a unique name to each neural network. You can then load any checkpoint neural network and resume training from that neural network.
If the folder does not exist, then you must first create it before specifying the path for saving the checkpoint neural networks. If the path you specify does not exist, then the software throws an error.
Data Types: char
 string
CheckpointFrequency
— Frequency of saving checkpoint neural networks
1
(default)  positive integer
Frequency of saving checkpoint neural networks, specified as a positive integer.
If CheckpointFrequencyUnit
is "epoch"
, then the software
saves checkpoint neural networks every CheckpointFrequency
epochs.
If CheckpointFrequencyUnit
is "iteration"
, then the
software saves checkpoint neural networks every
CheckpointFrequency
iterations.
This option only has an effect when CheckpointPath
is
nonempty.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
CheckpointFrequencyUnit
— Checkpoint frequency unit
"epoch"
(default)  "iteration"
Checkpoint frequency unit, specified as "epoch"
or "iteration"
.
If CheckpointFrequencyUnit
is "epoch"
, then the software
saves checkpoint neural networks every CheckpointFrequency
epochs.
If CheckpointFrequencyUnit
is "iteration"
, then the
software saves checkpoint neural networks every
CheckpointFrequency
iterations.
This option only has an effect when CheckpointPath
is nonempty.
OutputFcn
— Output functions
function handle  cell array of function handles
Output functions to call during training, specified as a function handle or cell array of function handles. The software calls the functions once before the start of training, after each iteration, and once when training is complete.
The functions must have the syntax stopFlag = f(info)
, where info
is a structure containing information about the training progress, and stopFlag
is a scalar that indicates to stop training early. If stopFlag
is 1
(true
), then the software stops training. Otherwise, the software continues training.
The trainnet
function passes the output function the structure
info
that contains these fields:
Field  Description 

Epoch  Epoch number 
Iteration  Iteration number 
TimeElapsed  Time since start of training 
LearnRate  Iteration learn rate 
TrainingLoss  Iteration training loss 
ValidationLoss  Validation loss, if specified and evaluated at iteration. 
State  Iteration training state, specified as "start" , "iteration" , or "done" . 
If you specify additional metrics in the training options, then
they also appear in the training information. For example, if you set the
Metrics
training option to "accuracy"
, then the
information includes the TrainingAccuracy
and
ValidationAccuracy
fields.
If a field is not calculated or relevant for a certain call to the output functions, then that field contains an empty array.
For an example showing how to use output functions, see Custom Stopping Criteria for Deep Learning Training.
Data Types: function_handle
 cell
Examples
Specify Training Options
Create a set of options for training a network using stochastic gradient descent with momentum. Reduce the learning rate by a factor of 0.2 every 5 epochs. Set the maximum number of epochs for training to 20, and use a minibatch with 64 observations at each iteration. Turn on the training progress plot.
options = trainingOptions("sgdm", ... LearnRateSchedule="piecewise", ... LearnRateDropFactor=0.2, ... LearnRateDropPeriod=5, ... MaxEpochs=20, ... MiniBatchSize=64, ... Plots="trainingprogress")
options = TrainingOptionsSGDM with properties: Momentum: 0.9000 InitialLearnRate: 0.0100 MaxEpochs: 20 LearnRateSchedule: 'piecewise' LearnRateDropFactor: 0.2000 LearnRateDropPeriod: 5 MiniBatchSize: 64 Shuffle: 'once' CheckpointFrequency: 1 CheckpointFrequencyUnit: 'epoch' SequenceLength: 'longest' PreprocessingEnvironment: 'serial' L2Regularization: 1.0000e04 GradientThresholdMethod: 'l2norm' GradientThreshold: Inf Verbose: 1 VerboseFrequency: 50 ValidationData: [] ValidationFrequency: 50 ValidationPatience: Inf ObjectiveMetricName: 'loss' CheckpointPath: '' ExecutionEnvironment: 'auto' OutputFcn: [] Metrics: [] Plots: 'trainingprogress' SequencePaddingValue: 0 SequencePaddingDirection: 'right' InputDataFormats: "auto" TargetDataFormats: "auto" ResetInputNormalization: 1 BatchNormalizationStatistics: 'auto' OutputNetwork: 'auto' Acceleration: "auto"
Algorithms
Stochastic Gradient Descent
The standard gradient descent algorithm updates the network parameters (weights and biases) to minimize the loss function by taking small steps at each iteration in the direction of the negative gradient of the loss,
$${\theta}_{\ell +1}={\theta}_{\ell}\alpha \nabla E\left({\theta}_{\ell}\right),$$
where $$\ell $$is the iteration number, $$\alpha >0$$ is the learning rate, $$\theta $$ is the parameter vector, and $$E\left(\theta \right)$$ is the loss function. In the standard gradient descent algorithm, the gradient of the loss function, $$\nabla E\left(\theta \right)$$, is evaluated using the entire training set, and the standard gradient descent algorithm uses the entire data set at once.
By contrast, at each iteration the stochastic gradient descent algorithm evaluates the gradient and updates the parameters using a subset of the training data. A different subset, called a minibatch, is used at each iteration. The full pass of the training algorithm over the entire training set using minibatches is one epoch. Stochastic gradient descent is stochastic because the parameter updates computed using a minibatch is a noisy estimate of the parameter update that would result from using the full data set.
Stochastic Gradient Descent with Momentum
The stochastic gradient descent algorithm can oscillate along the path of steepest descent towards the optimum. Adding a momentum term to the parameter update is one way to reduce this oscillation [2]. The stochastic gradient descent with momentum (SGDM) update is
$${\theta}_{\ell +1}={\theta}_{\ell}\alpha \nabla E\left({\theta}_{\ell}\right)+\gamma \left({\theta}_{\ell}{\theta}_{\ell 1}\right),$$
where the learning rate α and the momentum value $$\gamma $$ determine the contribution of the previous gradient step to the current iteration.
L_{2} Regularization
Adding a regularization term for the weights to the loss function $$E\left(\theta \right)$$ is one way to reduce overfitting [1], [2]. The regularization term is also called weight decay. The loss function with the regularization term takes the form
$${E}_{R}\left(\theta \right)=E\left(\theta \right)+\lambda \Omega \left(w\right),$$
where $$w$$ is the weight vector, $$\lambda $$ is the regularization factor (coefficient), and the regularization function $$\Omega \left(w\right)$$ is
$$\Omega \left(w\right)=\frac{1}{2}{w}^{T}w.$$
Note that the biases are not regularized [2]. You can specify the regularization factor $$\lambda $$ by using the L2Regularization
training option. You can also specify different
regularization factors for different layers and parameters.
The loss function that the software uses for network training includes the regularization term. However, the loss value displayed in the command window and training progress plot during training is the loss on the data only and does not include the regularization term.
Gradient Clipping
If the gradients increase in magnitude exponentially, then the training is unstable and can diverge within a few iterations. This "gradient explosion" is indicated by a training loss that goes to NaN
or Inf
. Gradient clipping helps prevent gradient explosion by stabilizing the training at higher learning rates and in the presence of outliers [3]. Gradient clipping enables networks to be trained faster, and does not usually impact the accuracy of the learned task.
There are two types of gradient clipping.
Normbased gradient clipping rescales the gradient based on a threshold, and does not change the direction of the gradient. The
"l2norm"
and"globall2norm"
values ofGradientThresholdMethod
are normbased gradient clipping methods.Valuebased gradient clipping clips any partial derivative greater than the threshold, which can result in the gradient arbitrarily changing direction. Valuebased gradient clipping can have unpredictable behavior, but sufficiently small changes do not cause the network to diverge. The
"absolutevalue"
value ofGradientThresholdMethod
is a valuebased gradient clipping method.
References
[1] Bishop, C. M. Pattern Recognition and Machine Learning. Springer, New York, NY, 2006.
[2] Murphy, K. P. Machine Learning: A Probabilistic Perspective. The MIT Press, Cambridge, Massachusetts, 2012.
[3] Pascanu, R., T. Mikolov, and Y. Bengio. "On the difficulty of training recurrent neural networks". Proceedings of the 30th International Conference on Machine Learning. Vol. 28(3), 2013, pp. 1310–1318.
Version History
Introduced in R2016aR2024b: Train neural networks using more learning rate schedules
Train neural networks using these learning rate schedules by specifying them as the LearnRateSchedule
argument of the trainingOptions
function:
"warmup"
— Warmup learning rate schedule"polynomial"
— Polynomial learning rate schedule"exponential"
— Exponential learning rate schedule"cosine"
— Cosine learning rate schedule"cyclical"
— Cyclical learning rate schedule
To customize these learning rate schedules, use these objects:
warmupLearnRate
— Warmup learning rate schedule objectpolynomialLearnRate
— Polynomial learning rate scheduleexponentialLearnRate
— Exponential learning rate schedulecosineLearnRate
— Cosine learning rate schedulecyclicalLearnRate
— Cyclical learning rate schedule
In previous versions, you could train using a piecewise learning rate schedule or no learning rate schedule.
To customize the existing piecewise learning rate schedule, use a piecewiseLearnRate
object.
To specify a custom schedule, use a function handle with the syntax learnRate = f(initialLearnRate,epoch)
, or define your own custom learn rate schedule object by defining a class that inherits from deep.LearnRateSchedule
.
R2024b: Monitor and plot more metrics during training
Use new and updated metric objects during training and testing.
MAPEMetric
— Mean absolute percentage error (MAPE)AccuracyMetric
with newNumTopKClasses
option — Topk accuracyFScoreMetric
with newBeta
option — F_{β}score
You can also directly specify these new builtin metric and loss names:
"mape"
— Mean absolute percentage error (MAPE)"crossentropy"
— Crossentropy loss"indexcrossentropy"
— Index crossentropy loss"binarycrossentropy"
— Binary crossentropy loss"mse"
/"meansquarederror"
/"l2loss"
— Mean squared error"mae"
/"meanabsoluteerror"
/"l1loss"
— Mean absolute error"huber"
— Huber loss
R2024a: Specify validation data using minibatchqueue
object
Specify validation data as a minibatchqueue
object using the ValidationData
argument.
R2024a: Automatic performance optimization
Accelerate training with automatic performance optimization. When you train a network
using the trainnet
function, automatic performance optimization is
enabled by default. You can disable performance optimization by setting the
Acceleration
option to "none"
using the
trainingOptions
function.
R2024a: Specify metrics as deep.DifferentiableFunction
object
Specify the metrics as deep.DifferentiableFunction
object.
R2024a: DispatchInBackground
training option is not recommended
The DispatchInBackground
training option is not recommended. Use the
PreprocessingEnvironment
option instead.
The PreprocessingEnvironment
option provides the same functionality and also allows you to use the backgroundPool
for preprocessing when you set PreprocessingEnvironment
to "background"
.
This table shows how to update your code:
Not recommended  Recommended 

trainingOptions(solverName,DispatchInBackground=false) (default)  trainingOptions(solverName,PreprocessingEnvironment="serial")
(default) 
trainingOptions(solverName,DispatchInBackground=true)  trainingOptions(solverName,PreprocessingEnvironment="parallel") 
There are no plans to remove the DispatchInBackground
option.
R2024a: OutputNetwork
default is "auto"
Starting in R2024a, the OutputNetwork
training option default value is
"auto"
. If you have specified validation data, then the software
returns the network corresponding to the best validation metric value. If you have not
specified validation data, then the software returns the network corresponding to the last
training iteration. If you have validation data and want to replicate the previous default,
then set OutputNetwork
to "lastiteration"
.
This change applies when using the training options with trainnet
only. If you are using the training options with the trainNetwork
function, then there is no behavior change and by default the software returns the network
corresponding to the last training iteration.
R2024a: OutputNetwork
value "bestvalidationloss"
is not recommended
Specifying OutputNetwork
as "bestvalidationloss"
is
not recommended. If you have code that set OutputNetwork
to
"bestvalidationloss"
, then use "bestvalidation"
instead. The software returns the network corresponding to the best validation metric value
as specified by the ObjectiveMetricName
option. By default, the ObjectiveMetricName
value is set to
"loss"
. This behavior applies when using the training options with
the trainnet
function only.
When using the training options with the trainNetwork
function, if
you specify OutputNetwork
as "bestvalidation"
, then
software always returns the network with the best validation loss value.
R2024a: ExecutionEnvironment
value "parallel"
is not recommended
Starting in R2024a, specifying the ExecutionEnvironment
option as "parallel"
is not recommended. Use "parallelauto"
instead.
"parallelauto"
has these advantages over "parallel"
:
The name of the option more accurately describes the execution environment, as the software trains in parallel automatically using whatever hardware is available.
The name of the option is consistent with the serial equivalent,
"auto"
.
There are no plans to remove the "parallel"
option. "parallelauto"
supports the trainnet
function only. If you are using the training options with the trainNetwork
function, then continue to use "parallel"
R2024a: WorkerLoad
training option is not recommended
Starting in R2024a, specifying the WorkerLoad
training option is not recommended. Use spmd
(Parallel Computing Toolbox) or the CUDA_VISIBLE_DEVICES
environment variable instead.
There are no plans to remove support for WorkerLoad
for training networks using the trainNetwork
function. WorkerLoad
is not supported for training networks using the trainnet
function.
This table shows some typical usages of WorkerLoad
and how to update your code to use spmd
or the CUDA_VISIBLE_DEVICES
environment variable instead.
Not Recommended  Recommended 

options = trainingOptions(solver, ... ExecutionEnvironment="multigpu", ... WorkerLoad=[1 1 0 1]);  % Alternative 1 pool = parpool(3); spmd if spmdIndex == 3 gpuDevice(spmdIndex + 1); else gpuDevice(spmdIndex); end end options = trainingOptions(solver, ... ExecutionEnvironment="multigpu"); % Alternative 2 % Set this environment variable immediately after your start MATLAB. setenv("CUDA_VISIBLE_DEVICES","0,1,3"); options = trainingOptions(solver, ... ExecutionEnvironment="multigpu"); 
options = trainingOptions(solver, ... ExecutionEnvironment="parallel", ... WorkerLoad=[1 1 0 1]);  pool = parpool(3); spmd if spmdIndex == 3 gpuDevice(spmdIndex + 1); else gpuDevice(spmdIndex); end end options = trainingOptions(solver, ... ExecutionEnvironment="parallelauto"); 
If you were previously using the WorkerLoad
option to reserve a worker
to preprocess your data, consider also preprocessing you data in the background by
specifying the PreprocessingEnvironment
option as
"background"
.
R2023b: Specify input and target data formats
Specify the input and target data formats using the InputDataFormats
and TargetDataFormats
options, respectively.
This option supports the trainnet
function only.
R2023b: Train neural network in parallel using only CPU or only GPU resources
Train a neural network in parallel using specific hardware resources by specifying the
ExecutionEnvironment
as "parallelcpu"
or
"parallelgpu"
.
This option supports the trainnet
function only.
R2023b: BatchNormalizationStatistics
default is "auto"
Starting in R2023b, the BatchNormalizationStatistics
training option default
value is "auto"
.
This change does not affect the behavior of the function. If you have code that checks the BatchNormalizationStatistics
property, then update your code to account for the "auto"
option.
R2022b: trainNetwork
pads minibatches to length of longest sequence before splitting when you specify SequenceLength
training option as an integer
Starting in R2022b, when you train a neural network with sequence data using the trainNetwork
function and the SequenceLength
option is an integer, the software pads sequences to the
length of the longest sequence in each minibatch and then splits the sequences into
minibatches with the specified sequence length. If SequenceLength
does
not evenly divide the sequence length of the minibatch, then the last split minibatch has
a length shorter than SequenceLength
. This behavior prevents the neural
network training on time steps that contain only padding values.
In previous releases, the software pads minibatches of sequences to have a length matching the nearest multiple of SequenceLength
that is greater than or equal to the minibatch length and then splits the data. To reproduce this behavior, use a custom training loop and implement this behavior when you preprocess minibatches of data.
R2018b: ValidationPatience
training option default is Inf
Starting in R2018b, the default value of the ValidationPatience
training option is Inf
, which means that automatic stopping via validation is turned off. This behavior prevents the training from stopping before sufficiently learning from the data.
In previous versions, the default value is 5
. To reproduce this behavior, set the ValidationPatience
option to 5
.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)