bat365 Homepage

lstmLayer

Long short-term memory (LSTM) layer for recurrent neural network (RNN)

expand all in page

Description

An LSTM layer is an RNN layer that learns long-term dependencies between time steps in time-series and sequence data.

The layer performs additive interactions, which can help improve gradient flow over long sequences during training.

Creation

Syntax

layer = lstmLayer(numHiddenUnits)

layer = lstmLayer(numHiddenUnits,Name,Value)

Description

example

layer = lstmLayer(numHiddenUnits) creates an LSTM layer and sets the NumHiddenUnits property.

example

layer = lstmLayer(numHiddenUnits,Name,Value) sets additional OutputMode, Activations, State, Parameters and Initialization, Learning Rate and Regularization, and Name properties using one or more name-value pair arguments. You can specify multiple name-value pair arguments. Enclose each property name in quotes.

Properties

expand all

LSTM

`NumHiddenUnits` — Number of hidden units
positive integer

Number of hidden units (also known as the hidden size), specified as a positive integer.

The number of hidden units corresponds to the amount of information that the layer remembers between time steps (the hidden state). The hidden state can contain information from all the previous time steps, regardless of the sequence length. If the number of hidden units is too large, then the layer can overfit to the training data.

The hidden state does not limit the number of time steps that the layer processes in an iteration. To split your sequences into smaller sequences for when you use the trainnet and trainNetwork functions, use the SequenceLength training option.

The layer outputs data with NumHiddenUnits channels.

To set this property, use the corresponding name-value argument when you create the LSTMLayer object. After you create a LSTMLayer object, this property is read-only.

`OutputMode` — Output mode
`"sequence"` (default) | `"last"`

Output mode, specified as one of these values:

"sequence" — Output the complete sequence.
"last" — Output the last time step of the sequence.

The LSTMLayer object stores this property as a character vector.

To set this property, use the corresponding name-value argument when you create the LSTMLayer object. After you create a LSTMLayer object, this property is read-only.

`HasStateInputs` — Flag for state inputs to layer
`0` (`false`) (default) | `1` (`true`)

This property is read-only.

Flag for state inputs to the layer, specified as 0 (false) or 1 (true).

If the HasStateInputs property is 0 (false), then the layer has one input with the name "in", which corresponds to the input data. In this case, the layer uses the HiddenState and CellState properties for the layer operation.

If the HasStateInputs property is 1 (true), then the layer has three inputs with the names "in", "hidden", and "cell", which correspond to the input data, hidden state, and cell state, respectively. In this case, the layer uses the values passed to these inputs for the layer operation. If HasStateInputs is 1 (true), then the HiddenState and CellState properties must be empty.

`HasStateOutputs` — Flag for state outputs from layer
`0` (`false`) (default) | `1` (`true`)

This property is read-only.

Flag for state outputs from the layer, specified as 0 (false) or 1 (true).

If the HasStateOutputs property is 0 (false), then the layer has one output with the name "out", which corresponds to the output data.

If the HasStateOutputs property is 1 (true), then the layer has three outputs with the names "out", "hidden", and "cell", which correspond to the output data, hidden state, and cell state, respectively. In this case, the layer also outputs the state values that it computes.

`InputSize` — Input size
`"auto"` (default) | positive integer

This property is read-only.

Input size, specified as a positive integer or "auto". If InputSize is "auto", then the software automatically assigns the input size at training time.

If InputSize is "auto", then the LSTMLayer object stores this property as a character vector.

Data Types: double | char | string

Activations

`StateActivationFunction` — Activation function to update cell and hidden state
`"tanh"` (default) | `"softsign"`

This property is read-only.

Activation function to update the cell and hidden state, specified as one of these values:

"tanh" — Use the hyperbolic tangent function (tanh).
"softsign" — Use the softsign function $softsign (x) = \frac{x}{1 + | x |}$ .

The layer uses this option as the function $σ_{c}$ in the calculations to update the cell and hidden state. For more information on how an LSTM layer uses activation functions, see Long Short-Term Memory Layer.

The LSTMLayer object stores this property as a character vector.

`GateActivationFunction` — Activation function to apply to gates
`"sigmoid"` (default) | `"hard-sigmoid"`

Activation function to apply to the gates, specified as one of these values:

"sigmoid" — Use the sigmoid function, $σ (x) = {(1 + e^{- x})}^{- 1}$ .
"hard-sigmoid" — Use the hard sigmoid function,

$σ (x) = {\begin{matrix} \begin{array}{l} 0 \\ 0.2 x + 0.5 \\ 1 \end{array} & \begin{array}{l} if x < - 2.5 \\ if - 2.5 \leq x \leq 2.5 \\ if x > 2.5 \end{array} \end{matrix} .$

The layer uses this option as the function $σ_{g}$ in the calculations for the layer gates.

The LSTMLayer object stores this property as a character vector.

To set this property, use the corresponding name-value argument when you create the LSTMLayer object. After you create a LSTMLayer object, this property is read-only.

State

`CellState` — Cell state
`[]` (default) | numeric vector

Cell state to use in the layer operation, specified as a NumHiddenUnits-by-1 numeric vector. This value corresponds to the initial cell state when data is passed to the layer.

After you set this property manually, calls to the resetState function set the cell state to this value.

If HasStateInputs is 1 (true), then the CellState property must be empty.

Data Types: single | double

`HiddenState` — Hidden state
`[]` (default) | numeric vector

Hidden state to use in the layer operation, specified as a NumHiddenUnits-by-1 numeric vector. This value corresponds to the initial hidden state when data is passed to the layer.

After you set this property manually, calls to the resetState function set the hidden state to this value.

If HasStateInputs is 1 (true), then the HiddenState property must be empty.

Data Types: single | double

Parameters and Initialization

`InputWeightsInitializer` — Function to initialize input weights
`'glorot'` (default) | `'he'` | `'orthogonal'` | `'narrow-normal'` | `'zeros'` | `'ones'` | function handle

Function to initialize the input weights, specified as one of the following:

'glorot' – Initialize the input weights with the Glorot initializer [2] (also known as Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and variance 2/(InputSize + numOut), where numOut = 4*NumHiddenUnits.
'he' – Initialize the input weights with the He initializer [3]. The He initializer samples from a normal distribution with zero mean and variance 2/InputSize.
'orthogonal' – Initialize the input weights with Q, the orthogonal matrix given by the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution. [4]
'narrow-normal' – Initialize the input weights by independently sampling from a normal distribution with zero mean and standard deviation 0.01.
'zeros' – Initialize the input weights with zeros.
'ones' – Initialize the input weights with ones.
Function handle – Initialize the input weights with a custom function. If you specify a function handle, then the function must be of the form weights = func(sz), where sz is the size of the input weights.

The layer only initializes the input weights when the InputWeights property is empty.

Data Types: char | string | function_handle

`RecurrentWeightsInitializer` — Function to initialize recurrent weights
`'orthogonal'` (default) | `'glorot'` | `'he'` | `'narrow-normal'` | `'zeros'` | `'ones'` | function handle

Function to initialize the recurrent weights, specified as one of the following:

'orthogonal' – Initialize the recurrent weights with Q, the orthogonal matrix given by the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution. [4]
'glorot' – Initialize the recurrent weights with the Glorot initializer [2] (also known as Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and variance 2/(numIn + numOut), where numIn = NumHiddenUnits and numOut = 4*NumHiddenUnits.
'he' – Initialize the recurrent weights with the He initializer [3]. The He initializer samples from a normal distribution with zero mean and variance 2/NumHiddenUnits.
'narrow-normal' – Initialize the recurrent weights by independently sampling from a normal distribution with zero mean and standard deviation 0.01.
'zeros' – Initialize the recurrent weights with zeros.
'ones' – Initialize the recurrent weights with ones.
Function handle – Initialize the recurrent weights with a custom function. If you specify a function handle, then the function must be of the form weights = func(sz), where sz is the size of the recurrent weights.

The layer only initializes the recurrent weights when the RecurrentWeights property is empty.

Data Types: char | string | function_handle

`BiasInitializer` — Function to initialize bias
`"unit-forget-gate"` (default) | `"narrow-normal"` | `"ones"` | function handle

Function to initialize the bias, specified as one of these values:

"unit-forget-gate" — Initialize the forget gate bias with ones and the remaining biases with zeros.
"narrow-normal" — Initialize the bias by independently sampling from a normal distribution with zero mean and a standard deviation of 0.01.
"ones" — Initialize the bias with ones.
Function handle — Initialize the bias with a custom function. If you specify a function handle, then the function must be of the form bias = func(sz), where sz is the size of the bias.

The layer only initializes the bias when the Bias property is empty.

The LSTMLayer object stores this property as a character vector or a function handle.

Data Types: char | string | function_handle

`InputWeights` — Input weights
`[]` (default) | matrix

Input weights, specified as a matrix.

The input weight matrix is a concatenation of the four input weight matrices for the components (gates) in the LSTM layer. The four matrices are concatenated vertically in the following order:

Input gate
Forget gate
Cell candidate
Output gate

The input weights are learnable parameters. When you train a neural network using the trainnet or trainNetwork function, if InputWeights is nonempty, then the software uses the InputWeights property as the initial value. If InputWeights is empty, then the software uses the initializer specified by InputWeightsInitializer.

At training time, InputWeights is a 4*NumHiddenUnits-by-InputSize matrix.

`RecurrentWeights` — Recurrent weights
`[]` (default) | matrix

Recurrent weights, specified as a matrix.

The recurrent weight matrix is a concatenation of the four recurrent weight matrices for the components (gates) in the LSTM layer. The four matrices are vertically concatenated in the following order:

Input gate
Forget gate
Cell candidate
Output gate

The recurrent weights are learnable parameters. When you train an RNN using the trainnet or trainNetwork function, if RecurrentWeights is nonempty, then the software uses the RecurrentWeights property as the initial value. If RecurrentWeights is empty, then the software uses the initializer specified by RecurrentWeightsInitializer.

At training time RecurrentWeights is a 4*NumHiddenUnits-by-NumHiddenUnits matrix.

`Bias` — Layer biases
`[]` (default) | numeric vector

Layer biases, specified as a numeric vector.

The bias vector is a concatenation of the four bias vectors for the components (gates) in the layer. The layer vertically concatenates the four vectors in this order:

Input gate
Forget gate
Cell candidate
Output gate

The layer biases are learnable parameters. When you train a neural network, if Bias is nonempty, then the trainnet and trainNetwork functions use the Bias property as the initial value. If Bias is empty, then software uses the initializer specified by BiasInitializer.

At training time, Bias is a 4*NumHiddenUnits-by-1 numeric vector.

Learning Rate and Regularization

`InputWeightsLearnRateFactor` — Learning rate factor for input weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

Learning rate factor for the input weights, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global learning rate to determine the learning rate factor for the input weights of the layer. For example, if InputWeightsLearnRateFactor is 2, then the learning rate factor for the input weights of the layer is twice the current global learning rate. The software determines the global learning rate based on the settings you specify with the trainingOptions function.

To control the value of the learning rate factor for the four individual matrices in InputWeights, specify a 1-by-4 vector. The entries of InputWeightsLearnRateFactor correspond to the learning rate factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the matrices, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

`RecurrentWeightsLearnRateFactor` — Learning rate factor for recurrent weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

Learning rate factor for the recurrent weights, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global learning rate to determine the learning rate for the recurrent weights of the layer. For example, if RecurrentWeightsLearnRateFactor is 2, then the learning rate for the recurrent weights of the layer is twice the current global learning rate. The software determines the global learning rate based on the settings you specify using the trainingOptions function.

To control the value of the learning rate factor for the four individual matrices in RecurrentWeights, specify a 1-by-4 vector. The entries of RecurrentWeightsLearnRateFactor correspond to the learning rate factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the matrices, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

`BiasLearnRateFactor` — Learning rate factor for biases
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

Learning rate factor for the biases, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global learning rate to determine the learning rate for the biases in this layer. For example, if BiasLearnRateFactor is 2, then the learning rate for the biases in the layer is twice the current global learning rate. The software determines the global learning rate based on the settings you specify using the trainingOptions function.

To control the value of the learning rate factor for the four individual vectors in Bias, specify a 1-by-4 vector. The entries of BiasLearnRateFactor correspond to the learning rate factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the vectors, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

`InputWeightsL2Factor` — L₂ regularization factor for input weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

L₂ regularization factor for the input weights, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global L₂ regularization factor to determine the L₂ regularization factor for the input weights of the layer. For example, if InputWeightsL2Factor is 2, then the L₂ regularization factor for the input weights of the layer is twice the current global L₂ regularization factor. The software determines the L₂ regularization factor based on the settings you specify using the trainingOptions function.

To control the value of the L₂ regularization factor for the four individual matrices in InputWeights, specify a 1-by-4 vector. The entries of InputWeightsL2Factor correspond to the L₂ regularization factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the matrices, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

`RecurrentWeightsL2Factor` — L₂ regularization factor for recurrent weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

L₂ regularization factor for the recurrent weights, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global L₂ regularization factor to determine the L₂ regularization factor for the recurrent weights of the layer. For example, if RecurrentWeightsL2Factor is 2, then the L₂ regularization factor for the recurrent weights of the layer is twice the current global L₂ regularization factor. The software determines the L₂ regularization factor based on the settings you specify using the trainingOptions function.

To control the value of the L₂ regularization factor for the four individual matrices in RecurrentWeights, specify a 1-by-4 vector. The entries of RecurrentWeightsL2Factor correspond to the L₂ regularization factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the matrices, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

`BiasL2Factor` — L₂ regularization factor for biases
`0` (default) | nonnegative scalar | 1-by-4 numeric vector

L₂ regularization factor for the biases, specified as a nonnegative scalar or a 1-by-4 numeric vector.

The software multiplies this factor by the global L₂ regularization factor to determine the L₂ regularization for the biases in this layer. For example, if BiasL2Factor is 2, then the L₂ regularization for the biases in this layer is twice the global L₂ regularization factor. The software determines the global L₂ regularization factor based on the settings you specify using the trainingOptions function.

To control the value of the L₂ regularization factor for the four individual vectors in Bias, specify a 1-by-4 vector. The entries of BiasL2Factor correspond to the L₂ regularization factor of these components:

Input gate
Forget gate
Cell candidate
Output gate

To specify the same value for all the vectors, specify a nonnegative scalar.

Example: 2

Example: [1 2 1 1]

Layer

`Name` — Layer name
`""` (default) | character vector | string scalar

Layer name, specified as a character vector or a string scalar. For Layer array input, the trainnet, trainNetwork, assembleNetwork, layerGraph, and dlnetwork functions automatically assign names to layers with the name "".

The LSTMLayer object stores this property as a character vector.

Data Types: char | string

`NumInputs` — Number of inputs
`1` | `3`

This property is read-only.

Number of inputs to the layer.

Data Types: double

`InputNames` — Input names
`"in"` | `["in" "hidden" "cell"]`

This property is read-only.

Input names of the layer.

The LSTMLayer object stores this property as a cell array of character vectors.

`NumOutputs` — Number of outputs
`1` | `3`

This property is read-only.

Number of outputs to the layer.

If the HasStateOutputs property is 0 (false), then the layer has one output with the name "out", which corresponds to the output data.

Data Types: double

`OutputNames` — Output names
`"out"` | `["out" "hidden" "cell"]`

This property is read-only.

Output names of the layer.

If the HasStateOutputs property is 0 (false), then the layer has one output with the name "out", which corresponds to the output data.

The LSTMLayer object stores this property as a cell array of character vectors.

Examples

collapse all

Create LSTM Layer

Open Live Script

Create an LSTM layer with the name 'lstm1' and 100 hidden units.

layer = lstmLayer(100,'Name','lstm1')

layer = 
  LSTMLayer with properties:

                       Name: 'lstm1'
                 InputNames: {'in'}
                OutputNames: {'out'}
                  NumInputs: 1
                 NumOutputs: 1
             HasStateInputs: 0
            HasStateOutputs: 0

   Hyperparameters
                  InputSize: 'auto'
             NumHiddenUnits: 100
                 OutputMode: 'sequence'
    StateActivationFunction: 'tanh'
     GateActivationFunction: 'sigmoid'

   Learnable Parameters
               InputWeights: []
           RecurrentWeights: []
                       Bias: []

   State Parameters
                HiddenState: []
                  CellState: []

Use properties method to see a list of all properties.

Include an LSTM layer in a Layer array.

inputSize = 12;
numHiddenUnits = 100;
numClasses = 9;

layers = [ ...
    sequenceInputLayer(inputSize)
    lstmLayer(numHiddenUnits)
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer]

layers = 
  5x1 Layer array with layers:

     1   ''   Sequence Input          Sequence input with 12 dimensions
     2   ''   LSTM                    LSTM with 100 hidden units
     3   ''   Fully Connected         9 fully connected layer
     4   ''   Softmax                 softmax
     5   ''   Classification Output   crossentropyex

Train Network for Sequence Classification

Open Live Script

Train a deep learning LSTM network for sequence-to-label classification.

Load the example data from WaveformData.mat. The data is a numObservations-by-1 cell array of sequences, where numObservations is the number of sequences. Each sequence is a numChannels-by-numTimeSteps numeric array, where numChannels is the number of channels of the sequence and numTimeSteps is the number of time steps of the sequence.

load WaveformData

Visualize some of the sequences in a plot.

numChannels = size(data{1},1);

idx = [3 4 5 12];
figure
tiledlayout(2,2)
for i = 1:4
    nexttile
    stackedplot(data{idx(i)}',DisplayLabels="Channel "+string(1:numChannels))
    
    xlabel("Time Step")
    title("Class: " + string(labels(idx(i))))
end

Set aside data for testing. Partition the data into a training set containing 90% of the data and a test set containing the remaining 10% of the data. To partition the data, use the trainingPartitions function, attached to this example as a supporting file. To access this file, open the example as a live script.

numObservations = numel(data);
[idxTrain,idxTest] = trainingPartitions(numObservations, [0.9 0.1]);
XTrain = data(idxTrain);
TTrain = labels(idxTrain);

XTest = data(idxTest);
TTest = labels(idxTest);

Define the LSTM network architecture. Specify the input size as the number of channels of the input data. Specify an LSTM layer to have 120 hidden units and to output the last element of the sequence. Finally, include a fully connected with an output size that matches the number of classes, followed by a softmax layer and a classification layer.

numHiddenUnits = 120;
numClasses = numel(categories(TTrain));

layers = [ ...
    sequenceInputLayer(numChannels)
    lstmLayer(numHiddenUnits,OutputMode="last")
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer]

layers = 
  5×1 Layer array with layers:

     1   ''   Sequence Input          Sequence input with 3 dimensions
     2   ''   LSTM                    LSTM with 120 hidden units
     3   ''   Fully Connected         4 fully connected layer
     4   ''   Softmax                 softmax
     5   ''   Classification Output   crossentropyex

Specify the training options. Train using the Adam solver with a learn rate of 0.01 and a gradient threshold of 1. Set the maximum number of epochs to 150 and shuffle every epoch. The software, by default, trains on a GPU if one is available. Using a GPU requires Parallel Computing Toolbox and a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).

options = trainingOptions("adam", ...
    MaxEpochs=150, ...
    InitialLearnRate=0.01,...
    Shuffle="every-epoch", ...
    GradientThreshold=1, ...
    Verbose=false, ...
    Plots="training-progress");

Train the LSTM network with the specified training options.

net = trainNetwork(XTrain,TTrain,layers,options);

Classify the test data. Specify the same mini-batch size used for training.

YTest = classify(net,XTest);

Calculate the classification accuracy of the predictions.

acc = mean(YTest == TTest)

acc = 0.8400

Display the classification results in a confusion chart.

figure
confusionchart(TTest,YTest)

Classification LSTM Networks

Open Live Script

To create an LSTM network for sequence-to-label classification, create a layer array containing a sequence input layer, an LSTM layer, a fully connected layer, a softmax layer, and a classification output layer.

Set the size of the sequence input layer to the number of features of the input data. Set the size of the fully connected layer to the number of classes. You do not need to specify the sequence length.

For the LSTM layer, specify the number of hidden units and the output mode 'last'.

numFeatures = 12;
numHiddenUnits = 100;
numClasses = 9;
layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits,'OutputMode','last')
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer];

For an example showing how to train an LSTM network for sequence-to-label classification and classify new data, see Sequence Classification Using Deep Learning.

To create an LSTM network for sequence-to-sequence classification, use the same architecture as for sequence-to-label classification, but set the output mode of the LSTM layer to 'sequence'.

numFeatures = 12;
numHiddenUnits = 100;
numClasses = 9;
layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits,'OutputMode','sequence')
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer];

Regression LSTM Networks

Open Live Script

To create an LSTM network for sequence-to-one regression, create a layer array containing a sequence input layer, an LSTM layer, a fully connected layer, and a regression output layer.

Set the size of the sequence input layer to the number of features of the input data. Set the size of the fully connected layer to the number of responses. You do not need to specify the sequence length.

For the LSTM layer, specify the number of hidden units and the output mode 'last'.

numFeatures = 12;
numHiddenUnits = 125;
numResponses = 1;

layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits,'OutputMode','last')
    fullyConnectedLayer(numResponses)
    regressionLayer];

To create an LSTM network for sequence-to-sequence regression, use the same architecture as for sequence-to-one regression, but set the output mode of the LSTM layer to 'sequence'.

numFeatures = 12;
numHiddenUnits = 125;
numResponses = 1;

layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits,'OutputMode','sequence')
    fullyConnectedLayer(numResponses)
    regressionLayer];

For an example showing how to train an LSTM network for sequence-to-sequence regression and predict on new data, see Sequence-to-Sequence Regression Using Deep Learning.

Deeper LSTM Networks

Open Live Script

You can make LSTM networks deeper by inserting extra LSTM layers with the output mode 'sequence' before the LSTM layer. To prevent overfitting, you can insert dropout layers after the LSTM layers.

For sequence-to-label classification networks, the output mode of the last LSTM layer must be 'last'.

numFeatures = 12;
numHiddenUnits1 = 125;
numHiddenUnits2 = 100;
numClasses = 9;
layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits1,'OutputMode','sequence')
    dropoutLayer(0.2)
    lstmLayer(numHiddenUnits2,'OutputMode','last')
    dropoutLayer(0.2)
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer];

For sequence-to-sequence classification networks, the output mode of the last LSTM layer must be 'sequence'.

numFeatures = 12;
numHiddenUnits1 = 125;
numHiddenUnits2 = 100;
numClasses = 9;
layers = [ ...
    sequenceInputLayer(numFeatures)
    lstmLayer(numHiddenUnits1,'OutputMode','sequence')
    dropoutLayer(0.2)
    lstmLayer(numHiddenUnits2,'OutputMode','sequence')
    dropoutLayer(0.2)
    fullyConnectedLayer(numClasses)
    softmaxLayer
    classificationLayer];

Algorithms

expand all

Long Short-Term Memory Layer

An LSTM layer is an RNN layer that learns long-term dependencies between time steps in time-series and sequence data.

The state of the layer consists of the hidden state (also known as the output state) and the cell state. The hidden state at time step t contains the output of the LSTM layer for this time step. The cell state contains information learned from the previous time steps. At each time step, the layer adds information to or removes information from the cell state. The layer controls these updates using gates.

These components control the cell state and hidden state of the layer.

Component	Purpose
Input gate (i)	Control level of cell state update
Forget gate (f)	Control level of cell state reset (forget)
Cell candidate (g)	Add information to cell state
Output gate (o)	Control level of cell state added to hidden state

This diagram illustrates the flow of data at time step t. This diagram shows how the gates forget, update, and output the cell and hidden states.

The learnable weights of an LSTM layer are the input weights W (InputWeights), the recurrent weights R (RecurrentWeights), and the bias b (Bias). The matrices W, R, and b are concatenations of the input weights, the recurrent weights, and the bias of each component, respectively. The layer concatenates the matrices according to these equations:

$W = [\begin{matrix} W_{i} \\ W_{f} \\ W_{g} \\ W_{o} \end{matrix}], R = [\begin{matrix} R_{i} \\ R_{f} \\ R_{g} \\ R_{o} \end{matrix}], b = [\begin{matrix} b_{i} \\ b_{f} \\ b_{g} \\ b_{o} \end{matrix}],$

where i, f, g, and o denote the input gate, forget gate, cell candidate, and output gate, respectively.

The cell state at time step t is given by

$c_{t} = f_{t} ⊙ c_{t - 1} + i_{t} ⊙ g_{t},$

where $⊙$ denotes the Hadamard product (element-wise multiplication of vectors).

The hidden state at time step t is given by

$h_{t} = o_{t} ⊙ σ_{c} (c_{t}),$

where $σ_{c}$ denotes the state activation function. By default, the lstmLayer function uses the hyperbolic tangent function (tanh) to compute the state activation function.

These formulas describe the components at time step t.

Component	Formula
Input gate	$i_{t} = σ_{g} (W_{i} x_{t} + R_{i} h_{t - 1} + b_{i})$
Forget gate	$f_{t} = σ_{g} (W_{f} x_{t} + R_{f} h_{t - 1} + b_{f})$
Cell candidate	$g_{t} = σ_{c} (W_{g} x_{t} + R_{g} h_{t - 1} + b_{g})$
Output gate	$o_{t} = σ_{g} (W_{o} x_{t} + R_{o} h_{t - 1} + b_{o})$

In these calculations, $σ_{g}$ denotes the gate activation function. By default, the lstmLayer function, uses the sigmoid function, given by $σ (x) = {(1 + e^{- x})}^{- 1}$ , to compute the gate activation function.

Layer Input and Output Formats

Layers in a layer array or layer graph pass data to subsequent layers as formatted dlarray objects. The format of a dlarray object is a string of characters, in which each character describes the corresponding dimension of the data. The formats consists of one or more of these characters:

"S" — Spatial
"C" — Channel
"B" — Batch
"T" — Time
"U" — Unspecified

For example, 2-D image data represented as a 4-D array, where the first two dimensions correspond to the spatial dimensions of the images, the third dimension corresponds to the channels of the images, and the fourth dimension corresponds to the batch dimension, can be described as having the format "SSCB" (spatial, spatial, channel, batch).

You can interact with these dlarray objects in automatic differentiation workflows such as developing a custom layer, using a functionLayer object, or using the forward and predict functions with dlnetwork objects.

This table shows the supported input formats of LSTMLayer objects and the corresponding output format. If the software passes the output of the layer to a custom layer that does not inherit from the nnet.layer.Formattable class, or a FunctionLayer object with the Formattable property set to 0 (false), then the layer receives an unformatted dlarray object with dimensions ordered corresponding to the formats in this table. The formats listed here are only a subset. The layer may support additional formats such as formats with additional "S" (spatial) or "U" (unspecified) dimensions.

Input Format	`OutputMode`	Output Format
`"CB"` (channel, batch)	`"sequence"`	`"CB"` (channel, batch)
`"CB"` (channel, batch)	`"last"`	`"CB"` (channel, batch)
`"CBT"` (channel, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"CBT"` (channel, batch, time)	`"last"`	`"CB"` (channel, batch)
`"SB"` (spatial, batch)	`"sequence"`	`"CB"` (channel, batch)
`"SB"` (spatial, batch)	`"last"`	`"CB"` (channel, batch)

In dlnetwork objects, LSTMLayer objects also support these input and output format combinations.

Input Format	`OutputMode`	Output Format
`"SCB"` (spatial, channel, batch)	`"sequence"`	`"CB"` (channel, batch)
`"SCB"` (spatial, channel, batch)	`"last"`
`"SSCB"` (spatial, spatial, channel, batch)	`"sequence"`
`"SSCB"` (spatial, spatial, channel, batch)	`"last"`
`"SSSCB"` (spatial, spatial, spatial, channel, batch)	`"sequence"`
`"SSSCB"` (spatial, spatial, spatial, channel, batch)	`"last"`
`"SCBT"` (spatial, channel, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"SCBT"` (spatial, channel, batch, time)	`"last"`	`"CB"` (channel, batch)
`"SSCBT"` (spatial, spatial, channel, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"SSCBT"` (spatial, spatial, channel, batch, time)	`"last"`	`"CB"` (channel, batch)
`"SSSCBT"` (spatial, spatial, spatial, channel, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
	`"last"`	`"CB"` (channel, batch)
`"SC"` (spatial, channel)	`"sequence"`	`"CU"` (channel, unspecified)
`"SC"` (spatial, channel)	`"last"`
`"SSC"` (spatial, spatial, channel)	`"sequence"`
`"SSC"` (spatial, spatial, channel)	`"last"`
`"SSSC"` (spatial, spatial, spatial, channel)	`"sequence"`
`"SSSC"` (spatial, spatial, spatial, channel)	`"last"`
`"CT"` (channel, time)	`"sequence"`	`"CT"` (channel, time)
`"CT"` (channel, time)	`"last"`	`"CU"` (channel, unspecified)
`"SCT"` (spatial, channel, time)	`"sequence"`	`"CT"` (channel, time)
`"SCT"` (spatial, channel, time)	`"last"`	`"CU"` (channel, unspecified)
`"SSCT"` (spatial, spatial, channel, time)	`"sequence"`	`"CT"` (channel, time)
`"SSCT"` (spatial, spatial, channel, time)	`"last"`	`"CU"` (channel, unspecified)
`"SSSCT"` (spatial, spatial, channel, time)	`"sequence"`	`"CT"` (channel, time)
`"SSSCT"` (spatial, spatial, channel, time)	`"last"`	`"CU"` (channel, unspecified)
`"SSB"` (spatial, spatial, batch)	`"sequence"`	`"CB"` (channel, batch)
`"SSB"` (spatial, spatial, batch)	`"last"`
`"SSSB"` (spatial, spatial, spatial, batch)	`"sequence"`
`"SSSB"` (spatial, spatial, spatial, batch)	`"last"`
`"BT"` (batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"BT"` (batch, time)	`"last"`	`"CB"` (channel, batch)
`"SBT"` (spatial, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"SBT"` (spatial, batch, time)	`"last"`	`"CB"` (channel, batch)
`"SSBT"` (spatial, spatial, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"SSBT"` (spatial, spatial, batch, time)	`"last"`	`"CB"` (channel, batch)
`"SSSBT"` (spatial, spatial, spatial, batch, time)	`"sequence"`	`"CBT"` (channel, batch, time)
`"SSSBT"` (spatial, spatial, spatial, batch, time)	`"last"`	`"CB"` (channel, batch)

To use these input formats in trainNetwork workflows, convert the data to "CB" (channel, batch) or "CBT" (channel, batch, time) format using flattenLayer.

If the HasStateInputs property is 1 (true), then the layer has two additional inputs with the names "hidden" and "cell", which correspond to the hidden state and cell state, respectively. These additional inputs expect input format "CB" (channel, batch).

If the HasStateOutputs property is 1 (true), then the layer has two additional outputs with names "hidden" and "cell", which correspond to the hidden state and cell state, respectively. These additional outputs have output format "CB" (channel, batch).

References

[1] Hochreiter, S, and J. Schmidhuber, 1997. Long short-term memory. Neural computation, 9(8), pp.1735–1780.

[2] Glorot, Xavier, and Yoshua Bengio. "Understanding the Difficulty of Training Deep Feedforward Neural Networks." In Proceedings of the Thirteenth International Conference on Artificial Intelligence and Statistics, 249–356. Sardinia, Italy: AISTATS, 2010. https://proceedings.mlr.press/v9/glorot10a/glorot10a.pdf

[3] He, Kaiming, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. "Delving Deep into Rectifiers: Surpassing Human-Level Performance on ImageNet Classification." In 2015 IEEE International Conference on Computer Vision (ICCV), 1026–34. Santiago, Chile: IEEE, 2015. https://doi.org/10.1109/ICCV.2015.123

[4] Saxe, Andrew M., James L. McClelland, and Surya Ganguli. "Exact Solutions to the Nonlinear Dynamics of Learning in Deep Linear Neural Networks.” Preprint, submitted February 19, 2014. https://arxiv.org/abs/1312.6120.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

For code generation in general, the HasStateInputs and HasStateOutputs properties must be set to 0 (false).

When generating code with Intel^® MKL-DNN or ARM^® Compute Library:

The StateActivationFunction property must be set to 'tanh'.
The GateActivationFunction property must be set to 'sigmoid'.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

For GPU code generation, the StateActivationFunction property must be set to 'tanh'.
For GPU code generation, the GateActivationFunction property must be set to 'sigmoid'.
The HasStateInputs and HasStateOutputs properties must be set to 0 (false).

Version History

Introduced in R2017b

expand all

R2019a: Default input weights initialization is Glorot

Starting in R2019a, the software, by default, initializes the layer input weights of this layer using the Glorot initializer. This behavior helps stabilize training and usually reduces the training time of deep neural networks.

In previous releases, the software, by default, initializes the layer input weights using the by sampling from a normal distribution with zero mean and variance 0.01. To reproduce this behavior, set the 'InputWeightsInitializer' option of the layer to 'narrow-normal'.

R2019a: Default recurrent weights initialization is orthogonal

Starting in R2019a, the software, by default, initializes the layer recurrent weights of this layer with Q, the orthogonal matrix given by the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution. This behavior helps stabilize training and usually reduces the training time of deep neural networks.

In previous releases, the software, by default, initializes the layer recurrent weights using the by sampling from a normal distribution with zero mean and variance 0.01. To reproduce this behavior, set the 'RecurrentWeightsInitializer' option of the layer to 'narrow-normal'.

lstmLayer

Description

Creation

Syntax

Description

Properties

LSTM

NumHiddenUnits — Number of hidden units positive integer

OutputMode — Output mode "sequence" (default) | "last"

HasStateInputs — Flag for state inputs to layer 0 (false) (default) | 1 (true)

HasStateOutputs — Flag for state outputs from layer 0 (false) (default) | 1 (true)

InputSize — Input size "auto" (default) | positive integer

Activations

StateActivationFunction — Activation function to update cell and hidden state "tanh" (default) | "softsign"

GateActivationFunction — Activation function to apply to gates "sigmoid" (default) | "hard-sigmoid"

State

CellState — Cell state [] (default) | numeric vector

HiddenState — Hidden state [] (default) | numeric vector

Parameters and Initialization

InputWeightsInitializer — Function to initialize input weights 'glorot' (default) | 'he' | 'orthogonal' | 'narrow-normal' | 'zeros' | 'ones' | function handle

RecurrentWeightsInitializer — Function to initialize recurrent weights 'orthogonal' (default) | 'glorot' | 'he' | 'narrow-normal' | 'zeros' | 'ones' | function handle

BiasInitializer — Function to initialize bias "unit-forget-gate" (default) | "narrow-normal" | "ones" | function handle

InputWeights — Input weights [] (default) | matrix

RecurrentWeights — Recurrent weights [] (default) | matrix

Bias — Layer biases [] (default) | numeric vector

Learning Rate and Regularization

InputWeightsLearnRateFactor — Learning rate factor for input weights 1 (default) | nonnegative scalar | 1-by-4 numeric vector

RecurrentWeightsLearnRateFactor — Learning rate factor for recurrent weights 1 (default) | nonnegative scalar | 1-by-4 numeric vector

BiasLearnRateFactor — Learning rate factor for biases 1 (default) | nonnegative scalar | 1-by-4 numeric vector

InputWeightsL2Factor — L2 regularization factor for input weights 1 (default) | nonnegative scalar | 1-by-4 numeric vector

RecurrentWeightsL2Factor — L2 regularization factor for recurrent weights 1 (default) | nonnegative scalar | 1-by-4 numeric vector

BiasL2Factor — L2 regularization factor for biases 0 (default) | nonnegative scalar | 1-by-4 numeric vector

Layer

Name — Layer name "" (default) | character vector | string scalar

NumInputs — Number of inputs 1 | 3

InputNames — Input names "in" | ["in" "hidden" "cell"]

NumOutputs — Number of outputs 1 | 3

OutputNames — Output names "out" | ["out" "hidden" "cell"]

Examples

Create LSTM Layer

Train Network for Sequence Classification

Classification LSTM Networks

Regression LSTM Networks

Deeper LSTM Networks

Algorithms

Long Short-Term Memory Layer

Layer Input and Output Formats

References

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

R2019a: Default input weights initialization is Glorot

R2019a: Default recurrent weights initialization is orthogonal

See Also

Topics

`NumHiddenUnits` — Number of hidden units
positive integer

`OutputMode` — Output mode
`"sequence"` (default) | `"last"`

`HasStateInputs` — Flag for state inputs to layer
`0` (`false`) (default) | `1` (`true`)

`HasStateOutputs` — Flag for state outputs from layer
`0` (`false`) (default) | `1` (`true`)

`InputSize` — Input size
`"auto"` (default) | positive integer

`StateActivationFunction` — Activation function to update cell and hidden state
`"tanh"` (default) | `"softsign"`

`GateActivationFunction` — Activation function to apply to gates
`"sigmoid"` (default) | `"hard-sigmoid"`

`CellState` — Cell state
`[]` (default) | numeric vector

`HiddenState` — Hidden state
`[]` (default) | numeric vector

`InputWeightsInitializer` — Function to initialize input weights
`'glorot'` (default) | `'he'` | `'orthogonal'` | `'narrow-normal'` | `'zeros'` | `'ones'` | function handle

`RecurrentWeightsInitializer` — Function to initialize recurrent weights
`'orthogonal'` (default) | `'glorot'` | `'he'` | `'narrow-normal'` | `'zeros'` | `'ones'` | function handle

`BiasInitializer` — Function to initialize bias
`"unit-forget-gate"` (default) | `"narrow-normal"` | `"ones"` | function handle

`InputWeights` — Input weights
`[]` (default) | matrix

`RecurrentWeights` — Recurrent weights
`[]` (default) | matrix

`Bias` — Layer biases
`[]` (default) | numeric vector

`InputWeightsLearnRateFactor` — Learning rate factor for input weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

`RecurrentWeightsLearnRateFactor` — Learning rate factor for recurrent weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

`BiasLearnRateFactor` — Learning rate factor for biases
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

`InputWeightsL2Factor` — L₂ regularization factor for input weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

`RecurrentWeightsL2Factor` — L₂ regularization factor for recurrent weights
`1` (default) | nonnegative scalar | 1-by-4 numeric vector

`BiasL2Factor` — L₂ regularization factor for biases
`0` (default) | nonnegative scalar | 1-by-4 numeric vector

`Name` — Layer name
`""` (default) | character vector | string scalar

`NumInputs` — Number of inputs
`1` | `3`

`InputNames` — Input names
`"in"` | `["in" "hidden" "cell"]`

`NumOutputs` — Number of outputs
`1` | `3`

`OutputNames` — Output names
`"out"` | `["out" "hidden" "cell"]`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.