# TrainingOptionsSGDM

Training options for stochastic gradient descent with momentum

## Description

Training options for stochastic gradient descent with momentum, including
learning rate information, L_{2} regularization factor, and
mini-batch size.

## Creation

Create a `TrainingOptionsSGDM`

object using `trainingOptions`

and specifying `'sgdm'`

as the
`solverName`

input argument.

## Properties

### Plots and Display

`Plots`

— Plots to display during network training

`'none'`

| `'training-progress'`

Plots to display during network training, specified as one of the following:

`'none'`

— Do not display plots during training.`'training-progress'`

— Plot training progress. The plot shows mini-batch loss and accuracy, validation loss and accuracy, and additional information on the training progress. The plot has a stop button in the top-right corner. Click the button to stop training and return the current state of the network.

`Verbose`

— Indicator to display training progress information

`1`

(true) (default) | `0`

(false)

Indicator to display training progress information in the command window, specified as
`1`

(true) or `0`

(false).

The verbose output displays the following information:

**Classification Networks**

Field | Description |
---|---|

`Epoch` | Epoch number. An epoch corresponds to a full pass of the data. |

`Iteration` | Iteration number. An iteration corresponds to a mini-batch. |

`Time Elapsed` | Time elapsed in hours, minutes, and seconds. |

`Mini-batch Accuracy` | Classification accuracy on the mini-batch. |

`Validation Accuracy` | Classification accuracy on the validation data. If you do not specify validation data, then the function does not display this field. |

`Mini-batch Loss` | Loss on the mini-batch. If the output layer is a
`ClassificationOutputLayer` object, then the loss
is the cross entropy loss for multi-class classification problems
with mutually exclusive classes. |

`Validation Loss` | Loss on the validation data. If the output layer is a
`ClassificationOutputLayer` object, then the loss
is the cross entropy loss for multi-class classification problems
with mutually exclusive classes. If you do not specify validation
data, then the function does not display this field. |

`Base Learning Rate` | Base learning rate. The software multiplies the learn rate factors of the layers by this value. |

**Regression Networks**

Field | Description |
---|---|

`Epoch` | Epoch number. An epoch corresponds to a full pass of the data. |

`Iteration` | Iteration number. An iteration corresponds to a mini-batch. |

`Time Elapsed` | Time elapsed in hours, minutes, and seconds. |

`Mini-batch RMSE` | Root-mean-squared-error (RMSE) on the mini-batch. |

`Validation RMSE` | RMSE on the validation data. If you do not specify validation data, then the software does not display this field. |

`Mini-batch Loss` | Loss on the mini-batch. If the output layer is a
`RegressionOutputLayer` object, then the loss is
the half-mean-squared-error. |

`Validation Loss` | Loss on the validation data. If the output layer is a
`RegressionOutputLayer` object, then the loss is
the half-mean-squared-error. If you do not specify validation data,
then the software does not display this field. |

`Base Learning Rate` | Base learning rate. The software multiplies the learn rate factors of the layers by this value. |

When training stops, the verbose output displays the reason for stopping.

To specify validation data, use the `ValidationData`

training option.

**Data Types: **`logical`

`VerboseFrequency`

— Frequency of verbose printing

positive integer

Frequency of verbose printing, which is the number of iterations between printing to the command window, specified as a positive integer. This property only has an effect when the `Verbose`

value equals `true`

.

If you validate the network during training, then `trainNetwork`

prints to the command window every time validation occurs.

### Mini-Batch Options

`MaxEpochs`

— Maximum number of epochs

positive integer

Maximum number of epochs to use for training, specified as a positive integer.

An iteration is one step taken in the gradient descent algorithm towards minimizing the loss function using a mini-batch. An epoch is the full pass of the training algorithm over the entire training set.

`MiniBatchSize`

— Size of mini-batch

positive integer

Size of the mini-batch to use for each training iteration, specified as a positive integer. A mini-batch is a subset of the training set that is used to evaluate the gradient of the loss function and update the weights.

`Shuffle`

— Option for data shuffling

`'once'`

| `'never'`

| `'every-epoch'`

Option for data shuffling, specified as one of the following:

`'once'`

— Shuffle the training and validation data once before training.`'never'`

— Do not shuffle the data.`'every-epoch'`

— Shuffle the training data before each training epoch, and shuffle the validation data before each network validation. If the mini-batch size does not evenly divide the number of training samples, then`trainNetwork`

discards the training data that does not fit into the final complete mini-batch of each epoch. Set the`Shuffle`

value to`'every-epoch'`

to avoid discarding the same data every epoch.

### Validation

`ValidationData`

— Data to use for validation during training

datastore | table | cell array

Data to use for validation during training, specified as a datastore, a table, or a cell array containing the validation predictors and responses.

You can specify validation predictors and responses using the same formats supported
by the `trainNetwork`

function. You can specify the
validation data as a datastore, table, or the cell array
`{predictors,responses}`

, where `predictors`

contains the validation predictors and `responses`

contains the
validation responses.

For more information, see the `images`

,
`sequences`

,
and `features`

input arguments of the `trainNetwork`

function.

During training, `trainNetwork`

calculates the validation accuracy
and validation loss on the validation data. To specify the validation frequency, use the
`ValidationFrequency`

training option. You can also use the validation
data to stop training automatically when the validation loss stops decreasing. To turn
on automatic validation stopping, use the `ValidationPatience`

training option.

If your network has layers that behave differently during prediction than during training (for example, dropout layers), then the validation accuracy can be higher than the training (mini-batch) accuracy.

The validation data is shuffled according to the `Shuffle`

training option. If
`Shuffle`

is `'every-epoch'`

, then the
validation data is shuffled before each network validation.

`ValidationFrequency`

— Frequency of network validation

positive integer

Frequency of network validation in number of iterations, specified as a positive integer.

The `ValidationFrequency`

value is the number of iterations between evaluations of validation metrics.

`ValidationPatience`

— Patience of validation stopping

`Inf`

(default) | positive integer

Patience of validation stopping of network training, specified as a positive integer
or `Inf`

.

`ValidationPatience`

specifies the number of times that the loss on
the validation set can be larger than or equal to the previously smallest loss before
network training stops. If `ValidationPatience`

is
`Inf`

, then the values of the validation loss do not cause training
to stop early.

The returned network depends on the `OutputNetwork`

training option. To return the network with the lowest
validation loss, set the `OutputNetwork`

training option to
`"best-validation-loss"`

.

`OutputNetwork`

— Network to return when training completes

`'last-iteration'`

(default) | `'best-validation-loss'`

Network to return when training completes, specified as one of the following:

`'last-iteration'`

– Return the network corresponding to the last training iteration.`'best-validation-loss'`

– Return the network corresponding to the training iteration with the lowest validation loss. To use this option, you must specify`'ValidationData'`

.

### Solver Options

`InitialLearnRate`

— Initial learning rate

positive scalar

Initial learning rate used for training, specified as a positive scalar. If the learning rate is too low, then training takes a long time. If the learning rate is too high, then training can reach a suboptimal result.

`LearnRateScheduleSettings`

— Settings for learning rate schedule

structure

Settings for the learning rate schedule, specified as a structure. `LearnRateScheduleSettings`

has the field `Method`

, which specifies the type of method for adjusting the learning rate. The possible methods are:

`'none'`

— The learning rate is constant throughout training.`'piecewise'`

— The learning rate drops periodically during training.

If `Method`

is `'piecewise'`

, then `LearnRateScheduleSettings`

contains two more fields:

`DropRateFactor`

— The multiplicative factor by which the learning rate drops during training`DropPeriod`

— The number of epochs that passes between adjustments to the learning rate during training

Specify the settings for the learning schedule rate using `trainingOptions`

.

**Data Types: **`struct`

`L2Regularization`

— Factor for L_{2} regularizer

nonnegative scalar

Factor for L_{2} regularizer (weight decay), specified as a nonnegative scalar.

You can specify a multiplier for the L_{2} regularizer for network layers with learnable parameters.

`Momentum`

— Contribution of previous gradient step

scalar from 0 to 1

Contribution of the gradient step from the previous iteration to the current iteration of the training, specified as a scalar value 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. For more information about the different solvers, see Stochastic Gradient Descent.

`BatchNormalizationStatistics`

— Mode to evaluate statistics in batch normalization layers

`'population'`

(default) | `'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.

### Gradient Clipping

`GradientThreshold`

— Gradient threshold

positive scalar | `Inf`

Positive threshold for the gradient, specified as positive scalar or `Inf`

. When the gradient exceeds the value of `GradientThreshold`

, then the gradient is clipped according to `GradientThresholdMethod`

.

`GradientThresholdMethod`

— Gradient threshold method

`'l2norm'`

| `'global-l2norm'`

| `'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 than`GradientThreshold`

, then scale the gradient so that the L_{2}norm equals`GradientThreshold`

.`'global-l2norm'`

— If the global L_{2}norm,*L*, is larger than`GradientThreshold`

, then scale all gradients by a factor of`GradientThreshold/`

*L*. The global L_{2}norm considers all learnable parameters.`'absolute-value'`

— If the absolute value of an individual partial derivative in the gradient of a learnable parameter is larger than`GradientThreshold`

, then scale the partial derivative to have magnitude equal to`GradientThreshold`

and retain the sign of the partial derivative.

For more information, see Gradient Clipping.

`ResetInputNormalization`

— Option to reset input layer normalization

`true`

(default) | `false`

Option to reset input layer normalization, specified as one of the following:

`true`

– Reset the input layer normalization statistics and recalculate them at training time.`false`

– Calculate normalization statistics at training time when they are empty.

### Sequence Options

`SequenceLength`

— Option to pad or truncate sequences

`'longest'`

| `'shortest'`

| positive integer

Option to pad, truncate, or split input sequences, specified as one of the following:

`'longest'`

— Pad sequences in each mini-batch to have the same length as the longest sequence. This option does not discard any data, though padding can introduce noise to the network.`'shortest'`

— Truncate sequences in each mini-batch to have the same length as the shortest sequence. This option ensures that no padding is added, at the cost of discarding data.Positive integer — For each mini-batch, pad the sequences to the nearest multiple of the specified length that is greater than the longest sequence length in the mini-batch, and then split the sequences into smaller sequences of the specified length. If splitting occurs, then the software creates extra mini-batches. Use this option if the full sequences do not fit in memory. Alternatively, try reducing the number of sequences per mini-batch by setting the

`'MiniBatchSize'`

option to a lower value.

To learn more about the effect of padding, truncating, and splitting the input sequences, see Sequence Padding, Truncation, and Splitting.

`SequencePaddingDirection`

— Direction of padding or truncation

`'right'`

(default) | `'left'`

Direction of padding or truncation, specified as one of the following:

`'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 the sequences.`'left'`

— Pad or truncate sequences on the left. The software truncates or adds padding to the start of the sequences so that the sequences end at the same time step.

Because LSTM layers process sequence data one time step at a time, when the 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'`

option to `'left'`

.

For sequence-to-sequence networks (when the `OutputMode`

property is `'sequence'`

for each LSTM 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 effect of padding, truncating, and splitting the input sequences, see Sequence Padding, Truncation, and Splitting.

`SequencePaddingValue`

— Value to pad sequences

scalar

Value by which to pad input sequences, specified as a scalar. The option is valid only when
`SequenceLength`

is `'longest'`

or a positive
integer. Do not pad sequences with `NaN`

, because doing so can
propagate errors throughout the network.

### Hardware Options

`ExecutionEnvironment`

— Hardware resource for training network

`'auto'`

| `'cpu'`

| `'gpu'`

| `'multi-gpu'`

| `'parallel'`

Hardware resource for training network, specified as one of the following:

`'auto'`

— Use a GPU if one is available. Otherwise, use the CPU.`'cpu'`

— Use the CPU.`'gpu'`

— Use the GPU.`'multi-gpu'`

— 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.`'parallel'`

— Use a local or remote parallel pool based on your default cluster profile. 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. If the pool does not have GPUs, then training takes place on all available CPU workers instead.

For more information on when to use the different execution environments, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.

`'gpu'`

,
`'multi-gpu'`

, and `'parallel'`

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 Support by Release (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.

To see an improvement in performance when training
in parallel, try scaling up the `MiniBatchSize`

and
`InitialLearnRate`

training options by the number of GPUs.

Training long short-term memory networks supports single CPU or single GPU training only.

Specify the execution environment using `trainingOptions`

.

**Data Types: **`char`

| `string`

`WorkerLoad`

— Parallel worker load division

scalar from 0 to 1 | positive integer | numeric vector

Worker load division for GPUs or CPUs, specified as a scalar from 0 to 1, a positive
integer, or a numeric vector. This property has an effect only when the
`ExecutionEnvironment`

value equals `'multi-gpu'`

or `'parallel'`

.

### Checkpoints

`CheckpointPath`

— Path for saving checkpoint networks

character vector

Path where checkpoint networks are saved, specified as a character vector.

**Data Types: **`char`

`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. `trainNetwork`

calls the specified functions once before the start of training, after each iteration, and once after training has finished. `trainNetwork`

passes a structure containing information in the following fields:

Field | Description |
---|---|

`Epoch` | Current epoch number |

`Iteration` | Current iteration number |

`TimeSinceStart` | Time in seconds since the start of training |

`TrainingLoss` | Current mini-batch loss |

`ValidationLoss` | Loss on the validation data |

`BaseLearnRate` | Current base learning rate |

`TrainingAccuracy` | Accuracy on the current mini-batch (classification networks) |

`TrainingRMSE` | RMSE on the current mini-batch (regression networks) |

`ValidationAccuracy` | Accuracy on the validation data (classification networks) |

`ValidationRMSE` | RMSE on the validation data (regression networks) |

`State` | Current training state, with a possible value of `"start"` , `"iteration"` , or `"done"` . |

If a field is not calculated or relevant for a certain call to the output functions, then that field contains an empty array.

You can use output functions to display or plot progress information, or to stop training. To
stop training early, make your output function return `true`

. If any
output function returns `true`

, then training finishes and ```
trainNetwork
```

returns the latest network. For an example showing how to
use output functions, see Customize Output During Deep Learning Network 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 mini-batch 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','training-progress')

options = TrainingOptionsSGDM with properties: Momentum: 0.9000 InitialLearnRate: 0.0100 LearnRateSchedule: 'piecewise' LearnRateDropFactor: 0.2000 LearnRateDropPeriod: 5 L2Regularization: 1.0000e-04 GradientThresholdMethod: 'l2norm' GradientThreshold: Inf MaxEpochs: 20 MiniBatchSize: 64 Verbose: 1 VerboseFrequency: 50 ValidationData: [] ValidationFrequency: 50 ValidationPatience: Inf Shuffle: 'once' CheckpointPath: '' ExecutionEnvironment: 'auto' WorkerLoad: [] OutputFcn: [] Plots: 'training-progress' SequenceLength: 'longest' SequencePaddingValue: 0 SequencePaddingDirection: 'right' DispatchInBackground: 0 ResetInputNormalization: 1 BatchNormalizationStatistics: 'population' OutputNetwork: 'last-iteration'

## See Also

`trainNetwork`

| `trainingOptions`

### Topics

- Create Simple Deep Learning Network for Classification
- Transfer Learning Using Pretrained Network
- Resume Training from Checkpoint Network
- Deep Learning with Big Data on CPUs, GPUs, in Parallel, and on the Cloud
- Specify Layers of Convolutional Neural Network
- Set Up Parameters and Train Convolutional Neural Network

**Introduced in R2016a**

## MATLAB 命令

您点击的链接对应于以下 MATLAB 命令：

请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。

# 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)