lstmProjectedLayer
Long shortterm memory (LSTM) projected layer for recurrent neural network (RNN)
Since R2022b
Description
An LSTM projected layer is an RNN layer that learns longterm dependencies between time steps in time series and sequence data using projected learnable weights.
To compress a deep learning network, you can use projected layers. A projected layer is a type of deep learning layer that enables compression by reducing the number of stored learnable parameters. The layer introduces learnable projector matrices Q, replaces multiplications of the form $$Wx$$, where W is a learnable matrix, with the multiplication $$WQ{Q}^{\top}x$$, and stores Q and $$W\prime =WQ$$ instead of storing W. Projecting x into a lowerdimensional space using Q typically requires less memory to store the learnable parameters and can have similarly strong prediction accuracy.
Reducing the number of learnable parameters by projecting an LSTM layer rather than reducing the number of hidden units of the LSTM layer maintains the output size of the layer and, in turn, the sizes of the downstream layers, which can result in better prediction accuracy.
Creation
Syntax
Description
creates an LSTM projected layer and sets the layer
= lstmProjectedLayer(numHiddenUnits
,outputProjectorSize
,inputProjectorSize
)NumHiddenUnits
, OutputProjectorSize
, and InputProjectorSize
properties.
sets the layer
= lstmProjectedLayer(___,Name=Value
)OutputMode
, HasStateInputs
, HasStateOutputs
, Activations, State, Parameters and Initialization, Learning Rate and Regularization, and Name
properties using one or more namevalue arguments.
Properties
Projected LSTM
NumHiddenUnits
— Number of hidden units
positive integer
This property is readonly.
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 might 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
trainNetwork
function, use the SequenceLength
training option.
The layer outputs data with NumHiddenUnits
channels.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
OutputProjectorSize
— Output projector size
positive integer
This property is readonly.
Output projector size, specified as a positive integer.
The LSTM layer operation uses four matrix multiplications of the form $$R{h}_{t1}$$, where R denotes the recurrent weights and h_{t} denotes the hidden state (or, equivalently, the layer output) at time step t.
The LSTM projected layer operation instead uses multiplications of the from $$R{Q}_{o}{Q}_{o}^{\top}{h}_{t1}$$, where Q_{o} is a
NumHiddenUnits
byOutputProjectorSize
matrix known
as the output projector. The layer uses the same projector
Q_{o} for each of the four
multiplications.
To perform the four multiplications of the form $$R{h}_{t1}$$, an LSTM layer stores four recurrent weights R, which
necessitates storing 4*NumHiddenUnits^2
learnable parameters. By instead
storing the 4*NumHiddenUnits
byOutputProjectorSize
matrix $$R\prime =R{Q}_{o}$$ and Q_{o}, an LSTM projected layer
can perform the multiplication $$R{Q}_{o}{Q}_{o}^{\top}{h}_{t1}$$ and store only 5*NumHiddenUnits*OutputProjectorSize
learnable parameters.
Tip
To ensure that $$R{Q}_{o}{Q}_{o}^{\top}{h}_{t1}$$ requires fewer learnable parameters, set the
OutputProjectorSize
property to a value less than
(4/5)*NumHiddenUnits
.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
InputProjectorSize
— Input projector size
positive integer
This property is readonly.
Input projector size, specified as a positive integer.
The LSTM layer operation uses four matrix multiplications of the form $$W{x}_{t}$$, where W denotes the input weights and x_{t} denotes the layer input at time step t.
The LSTM projected layer operation instead uses multiplications of the from $$W{Q}_{i}{Q}_{i}^{\top}{x}_{t}$$, where Q_{i} is an
InputSize
byInputProjectorSize
matrix known as
the input projector. The layer uses the same projector
Q_{i} for each of the four
multiplications.
To perform the four multiplications of the form $$W{x}_{t}$$, an LSTM layer stores four weight matrices W, which
necessitates storing 4*NumHiddenUnits*InputSize
learnable parameters. By
instead storing the
4*NumHiddenUnits
byInputProjectorSize
matrix $$W\prime =W{Q}_{i}$$ and Q_{i}, an LSTM projected layer
can perform the multiplication $$W{Q}_{i}{Q}_{i}^{\top}{x}_{t}$$ and store only
(4*NumHiddenUnits+InputSize)*InputProjectorSize
learnable
parameters.
Tip
To ensure that $$W{Q}_{i}{Q}_{i}^{\top}{x}_{t}$$ requires fewer learnable parameters, set the
InputProjectorSize
property to a value less than
(4*numHiddenUnits*inputSize)/(4*numHiddenUnits+inputSize)
.
Data Types: single
 double
 int8
 int16
 int32
 int64
 uint8
 uint16
 uint32
 uint64
OutputMode
— Output mode
'sequence'
(default)  'last'
This property is readonly.
Output mode, specified as one of these values:
'sequence'
— Output the complete sequence.'last'
— Output the last time step of the sequence.
HasStateInputs
— Flag for state inputs to layer
0
(false) (default)  1
(true)
This property is readonly.
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 readonly.
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 readonly.
Input size, specified as a positive integer or 'auto'
. If
InputSize
is 'auto'
, then the software
automatically assigns the input size at training time.
Data Types: double
 char
Activations
StateActivationFunction
— Activation function to update cell and hidden state
'tanh'
(default)  'softsign'
This property is readonly.
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 $$\text{softsign}(x)=\frac{x}{1+\leftx\right}$$.
The layer uses this option as the function $${\sigma}_{c}$$ in the calculations to update the cell and hidden state. For more information on how an LSTM layer uses activation functions, see Long ShortTerm Memory Layer.
GateActivationFunction
— Activation function to apply to gates
'sigmoid'
(default)  'hardsigmoid'
This property is readonly.
Activation function to apply to the gates, specified as one of these values:
'sigmoid'
— Use the sigmoid function $$\sigma (x)={(1+{e}^{x})}^{1}$$.'hardsigmoid'
— Use the hard sigmoid function$$\sigma (x)=\{\begin{array}{cc}\begin{array}{l}0\hfill \\ 0.2x+0.5\hfill \\ 1\hfill \end{array}& \begin{array}{l}\text{if}x2.5\hfill \\ \text{if}2.5\le x\le 2.5\hfill \\ \text{if}x2.5\hfill \end{array}\end{array}.$$
The layer uses this option as the function $${\sigma}_{g}$$ in the calculations for the layer gates.
State
CellState
— Cell state
[]
(default)  numeric vector
Cell state to use in the layer operation, specified as a NumHiddenUnits
by1 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
by1 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'
 'narrownormal'
 'zeros'
 'ones'
 function handle
Function to initialize the input weights, specified as one of these values:
'glorot'
— Initialize the input weights with the Glorot initializer [1] (also known as the Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and a variance of2/(InputProjectorSize + numOut)
, wherenumOut = 4*NumHiddenUnits
.'he'
— Initialize the input weights with the He initializer [2]. The He initializer samples from a normal distribution with zero mean and a variance of2/InputProjectorSize
.'orthogonal'
— Initialize the input weights with Q, the orthogonal matrix in the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution [3].'narrownormal'
— Initialize the input weights by independently sampling from a normal distribution with zero mean and a standard deviation of 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)
, wheresz
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'
 'narrownormal'
 '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 in the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution [3].'glorot'
— Initialize the recurrent weights with the Glorot initializer [1] (also known as the Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and a variance of2/(numIn + numOut)
, wherenumIn = OutputProjectorSize
andnumOut = 4*NumHiddenUnits
.'he'
— Initialize the recurrent weights with the He initializer [2]. The He initializer samples from a normal distribution with zero mean and a variance of2/OutputProjectorSize
.'narrownormal'
— Initialize the recurrent weights by independently sampling from a normal distribution with zero mean and a standard deviation of 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)
, wheresz
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
InputProjectorInitializer
— Function to initialize input projector
'orthogonal'
(default)  'glorot'
 'he'
 'narrownormal'
 'zeros'
 'ones'
 function handle
Function to initialize the input projector, specified as one of the following:
'orthogonal'
— Initialize the input projector with Q, the orthogonal matrix in the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution [3].'glorot'
— Initialize the input projector with the Glorot initializer [1] (also known as the Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and a variance of2/(InputSize + inputProjectorSize)
.'he'
— Initialize the input projector with the He initializer [2]. The He initializer samples from a normal distribution with zero mean and a variance of2/InputSize
.'narrownormal'
— Initialize the input projector by independently sampling from a normal distribution with zero mean and a standard deviation of 0.01.'zeros'
— Initialize the input weights with zeros.'ones'
— Initialize the input weights with ones.Function handle — Initialize the input projector with a custom function. If you specify a function handle, then the function must be of the form
weights = func(sz)
, wheresz
is the size of the input projector.
The layer only initializes the input projector when the InputProjector
property is empty.
Data Types: char
 string
 function_handle
OutputProjectorInitializer
— Function to initialize output projector
'orthogonal'
(default)  'glorot'
 'he'
 'narrownormal'
 'zeros'
 'ones'
 function handle
Function to initialize the output projector, specified as one of the following:
'orthogonal'
— Initialize the output projector with Q, the orthogonal matrix in the QR decomposition of Z = QR for a random matrix Z sampled from a unit normal distribution [3].'glorot'
— Initialize the output projector with the Glorot initializer [1] (also known as the Xavier initializer). The Glorot initializer independently samples from a uniform distribution with zero mean and a variance of2/(NumHiddenUnits + OutputProjectorSize)
.'he'
— Initialize the output projector with the He initializer [2]. The He initializer samples from a normal distribution with zero mean and a variance of2/NumHiddenUnits
.'narrownormal'
— Initialize the output projector by independently sampling from a normal distribution with zero mean and a standard deviation of 0.01.'zeros'
— Initialize the output projector with zeros.'ones'
— Initialize the output projector with ones.Function handle — Initialize the output projector with a custom function. If you specify a function handle, then the function must be of the form
weights = func(sz)
, wheresz
is the size of the output projector.
The layer only initializes the output projector when the OutputProjector
property is empty.
Data Types: char
 string
 function_handle
BiasInitializer
— Function to initialize bias
'unitforgetgate'
(default)  'narrownormal'
 'ones'
 function handle
Function to initialize the bias, specified as one of these values:
'unitforgetgate'
— Initialize the forget gate bias with ones and the remaining biases with zeros.'narrownormal'
— 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)
, wheresz
is the size of the bias.
The layer only initializes the bias when the Bias
property is
empty.
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 layer vertically concatenates the four matrices in this order:
Input gate
Forget gate
Cell candidate
Output gate
The input weights are learnable parameters. When you train a
neural network using the 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
byInputProjectorSize
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 layer vertically concatenates the four matrices in this order:
Input gate
Forget gate
Cell candidate
Output gate
The recurrent weights are learnable parameters. When you train
an RNN using the 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
byOutputProjectorSize
matrix.
InputProjector
— Input projector
[]
(default)  matrix
Input projector, specified as a matrix.
The input projector weights are learnable parameters. When you train a network
using the trainNetwork
function, if InputProjector
is nonempty, then the software uses the
InputProjector
property as the initial value. If
InputProjector
is empty, then the software uses
the initializer specified by InputProjectorInitializer
.
At training time, InputProjector
is a
InputSize
byInputProjectorSize
matrix.
Data Types: single
 double
OutputProjector
— Output projector
[]
(default)  matrix
Output projector, specified as a matrix.
The output projector weights are learnable parameters. When you train a network
using the trainNetwork
function, if OutputProjector
is nonempty, then the software uses the
OutputProjector
property as the initial value. If
OutputProjector
is empty, then the software uses
the initializer specified by OutputProjectorInitializer
.
At training time, OutputProjector
is a
NumHiddenUnits
byOutputProjectorSize
matrix.
Data Types: single
 double
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 trainNetwork
uses the Bias
property as the
initial value. If Bias
is empty, then
trainNetwork
uses the initializer specified by BiasInitializer
.
At training time, Bias
is a 4*NumHiddenUnits
by1 numeric vector.
Learning Rate and Regularization
InputWeightsLearnRateFactor
— Learning rate factor for input weights
1 (default)  nonnegative scalar  1by4 numeric vector
Learning rate factor for the input weights, specified as a nonnegative scalar or a 1by4 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 1by4 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  1by4 numeric vector
Learning rate factor for the recurrent weights, specified as a nonnegative scalar or a 1by4 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 1by4 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]
InputProjectorLearnRateFactor
— Learning rate factor for input projector
1 (default)  nonnegative scalar
Learning rate factor for the input projector, specified as a nonnegative scalar.
The software multiplies this factor by the global learning rate to determine the
learning rate factor for the input projector of the layer. For example, if
InputProjectorLearnRateFactor
is 2
, then the
learning rate factor for the input projector 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.
OutputProjectorLearnRateFactor
— Learning rate factor for output projector
1 (default)  nonnegative scalar
Learning rate factor for the output projector, specified as a nonnegative scalar.
The software multiplies this factor by the global learning rate to determine the
learning rate factor for the output projector of the layer. For example, if
OutputProjectorLearnRateFactor
is 2
, then
the learning rate factor for the output projector 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.
BiasLearnRateFactor
— Learning rate factor for biases
1 (default)  nonnegative scalar  1by4 numeric vector
Learning rate factor for the biases, specified as a nonnegative scalar or a 1by4 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 1by4 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_{2} regularization factor for input weights
1 (default)  nonnegative scalar  1by4 numeric vector
L_{2} regularization factor for the input weights, specified as a nonnegative scalar or a 1by4 numeric vector.
The software multiplies this factor by the global
L_{2} regularization factor to determine the
L_{2} regularization factor for the input weights
of the layer. For example, if InputWeightsL2Factor
is 2
,
then the L_{2} regularization factor for the input
weights of the layer is twice the current global L_{2}
regularization factor. The software determines the L_{2}
regularization factor based on the settings you specify using the trainingOptions
function.
To control the value of the L_{2}
regularization factor for the four individual matrices in
InputWeights
, specify a 1by4 vector. The
entries of InputWeightsL2Factor
correspond to the
L_{2} 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_{2} regularization factor for recurrent weights
1 (default)  nonnegative scalar  1by4 numeric vector
L_{2} regularization factor for the recurrent weights, specified as a nonnegative scalar or a 1by4 numeric vector.
The software multiplies this factor by the global
L_{2} regularization factor to determine the
L_{2} regularization factor for the recurrent
weights of the layer. For example, if RecurrentWeightsL2Factor
is
2
, then the L_{2} regularization
factor for the recurrent weights of the layer is twice the current global
L_{2} regularization factor. The software
determines the L_{2} regularization factor based on the
settings you specify using the trainingOptions
function.
To control the value of the L_{2}
regularization factor for the four individual matrices in
RecurrentWeights
, specify a 1by4 vector. The
entries of RecurrentWeightsL2Factor
correspond to the
L_{2} 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]
InputProjectorL2Factor
— L_{2} regularization factor for input projector
1 (default)  nonnegative scalar
L_{2} regularization factor for the input projector, specified as a nonnegative scalar.
The software multiplies this factor by the global
L_{2} regularization factor to determine
the L_{2} regularization factor for the input
projector of the layer. For example, if InputProjectorL2Factor
is
2
, then the L_{2}
regularization factor for the input projector of the layer is twice the current global
L_{2} regularization factor. The software
determines the global L_{2} regularization
factor based on the settings you specify using the trainingOptions
function.
OutputProjectorL2Factor
— L_{2} regularization factor for output projector
1 (default)  nonnegative scalar
L_{2} regularization factor for the output projector, specified as a nonnegative scalar.
The software multiplies this factor by the global
L_{2} regularization factor to determine
the L_{2} regularization factor for the output
projector of the layer. For example, if OutputProjectorL2Factor
is 2
, then the L_{2}
regularization factor for the output projector of the layer is twice the current
global L_{2} regularization factor. The
software determines the global L_{2}
regularization factor based on the settings you specify using the trainingOptions
function.
BiasL2Factor
— L_{2} regularization factor for biases
0 (default)  nonnegative scalar  1by4 numeric vector
L_{2} regularization factor for the biases, specified as a nonnegative scalar or a 1by4 numeric vector.
The software multiplies this factor by the global
L_{2} regularization factor to
determine the L_{2} regularization for the biases in
this layer. For example, if BiasL2Factor
is 2
, then
the L_{2} regularization for the biases in this layer
is twice the global L_{2} regularization factor. The
software determines the global L_{2} regularization
factor based on the settings you specify using the trainingOptions
function.
To control the value of the L_{2}
regularization factor for the four individual vectors in Bias
,
specify a 1by4 vector. The entries of BiasL2Factor
correspond to
the L_{2} 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 trainNetwork
, assembleNetwork
, layerGraph
, and
dlnetwork
functions automatically assign
names to layers with the name ''
.
Data Types: char
 string
NumInputs
— Number of inputs
1
 3
This property is readonly.
Number of inputs to the layer.
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.
Data Types: double
InputNames
— Input names
{'in'}
 {'in','hidden','cell'}
This property is readonly.
Input names of the layer.
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.
NumOutputs
— Number of outputs
1
 3
This property is readonly.
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.
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.
Data Types: double
OutputNames
— Output names
{'out'}
 {'out','hidden','cell'}
This property is readonly.
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.
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.
Examples
Create LSTM Projected Layer
Create an LSTM projected layer with 100 hidden units, an output projector size of 30, an input projector size of 16, and the name "lstmp"
.
layer = lstmProjectedLayer(100,30,16,Name="lstmp")
layer = LSTMProjectedLayer with properties: Name: 'lstmp' InputNames: {'in'} OutputNames: {'out'} NumInputs: 1 NumOutputs: 1 HasStateInputs: 0 HasStateOutputs: 0 Hyperparameters InputSize: 'auto' NumHiddenUnits: 100 InputProjectorSize: 16 OutputProjectorSize: 30 OutputMode: 'sequence' StateActivationFunction: 'tanh' GateActivationFunction: 'sigmoid' Learnable Parameters InputWeights: [] RecurrentWeights: [] Bias: [] InputProjector: [] OutputProjector: [] State Parameters HiddenState: [] CellState: [] Show all properties
Include an LSTM projected layer in a layer array.
inputSize = 12; numHiddenUnits = 100; outputProjectorSize = max(1,floor(0.75*numHiddenUnits)); inputProjectorSize = max(1,floor(0.25*inputSize)); layers = [ sequenceInputLayer(inputSize) lstmProjectedLayer(numHiddenUnits,outputProjectorSize,inputProjectorSize) fullyConnectedLayer(10) softmaxLayer classificationLayer];
Compare Network Projection Sizes
Compare the sizes of networks that do and do not contain projected layers.
Define an LSTM network architecture. Specify the input size as 12, which corresponds to the number of features of the input data. Configure an LSTM layer with 100 hidden units that outputs the last element of the sequence. Finally, specify nine classes by including a fully connected layer of size 9, followed by a softmax layer and a classification layer.
inputSize = 12; numHiddenUnits = 100; numClasses = 9; layers = [ ... sequenceInputLayer(inputSize) lstmLayer(numHiddenUnits,OutputMode="last") 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
Analyze the network using the analyzeNetwork
function. The network has approximately 46,100 learnable parameters.
analyzeNetwork(layers)
Create an identical network with an LSTM projected layer in place of the LSTM layer.
For the LSTM projected layer:
Specify the same number of hidden units as the LSTM layer
Specify an output projector size of 25% of the number of hidden units.
Specify an input projector size of 75% of the input size.
Ensure that the output and input projector sizes are positive by taking the maximum of the sizes and 1.
outputProjectorSize = max(1,floor(0.25*numHiddenUnits)); inputProjectorSize = max(1,floor(0.75*inputSize)); layersProjected = [ ... sequenceInputLayer(inputSize) lstmProjectedLayer(numHiddenUnits,outputProjectorSize,inputProjectorSize,OutputMode="last") fullyConnectedLayer(numClasses) softmaxLayer classificationLayer];
Analyze the network using the analyzeNetwork
function. The network has approximately 17,500 learnable parameters, which is a reduction of more than half. The sizes of the learnable parameters of the layers following the projected layer have the same sizes as the network without the LSTM projected layer. Reducing the number of learnable parameters by projecting an LSTM layer rather than reducing the number of hidden units of the LSTM layer maintains the output size of the layer and, in turn, the sizes of the downstream layers, which can result in better prediction accuracy.
analyzeNetwork(layersProjected)
Algorithms
Long ShortTerm Memory Layer
An LSTM layer is an RNN layer that learns longterm 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=\left[\begin{array}{c}{W}_{i}\\ {W}_{f}\\ {W}_{g}\\ {W}_{o}\end{array}\right],\text{\hspace{1em}\hspace{1em}}R=\left[\begin{array}{c}{R}_{i}\\ {R}_{f}\\ {R}_{g}\\ {R}_{o}\end{array}\right],\text{\hspace{1em}\hspace{1em}}b=\left[\begin{array}{c}{b}_{i}\\ {b}_{f}\\ {b}_{g}\\ {b}_{o}\end{array}\right],$$
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}\odot {c}_{t1}+{i}_{t}\odot {g}_{t},$$
where $$\odot $$ denotes the Hadamard product (elementwise multiplication of vectors).
The hidden state at time step t is given by
$${h}_{t}={o}_{t}\odot {\sigma}_{c}({c}_{t}),$$
where $${\sigma}_{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}={\sigma}_{g}({W}_{i}{x}_{t}+\text{}{\text{R}}_{i}{h}_{t1}+{b}_{i})$$ 
Forget gate  $${f}_{t}={\sigma}_{g}({W}_{f}{x}_{t}+\text{}{\text{R}}_{f}{h}_{t1}+{b}_{f})$$ 
Cell candidate  $${g}_{t}={\sigma}_{c}({W}_{g}{x}_{t}+\text{}{\text{R}}_{g}{h}_{t1}+{b}_{g})$$ 
Output gate  $${o}_{t}={\sigma}_{g}({W}_{o}{x}_{t}+\text{}{\text{R}}_{o}{h}_{t1}+{b}_{o})$$ 
In these calculations, $${\sigma}_{g}$$ denotes the gate activation function. By default, the
lstmLayer
function, uses the sigmoid function, given by $$\sigma (x)={(1+{e}^{x})}^{1}$$, to compute the gate activation function.
LSTM Projected Layer
An LSTM projected layer is an RNN layer that learns longterm dependencies between time steps in time series and sequence data using projected learnable weights.
To compress a deep learning network, you can use projected layers. A projected layer is a type of deep learning layer that enables compression by reducing the number of stored learnable parameters. The layer introduces learnable projector matrices Q, replaces multiplications of the form $$Wx$$, where W is a learnable matrix, with the multiplication $$WQ{Q}^{\top}x$$, and stores Q and $$W\prime =WQ$$ instead of storing W. Projecting x into a lowerdimensional space using Q typically requires less memory to store the learnable parameters and can have similarly strong prediction accuracy.
Reducing the number of learnable parameters by projecting an LSTM layer rather than reducing the number of hidden units of the LSTM layer maintains the output size of the layer and, in turn, the sizes of the downstream layers, which can result in better prediction accuracy.
The LSTM layer operation uses four matrix multiplications of the form $$R{h}_{t1}$$, where R denotes the recurrent weights and h_{t} denotes the hidden state (or, equivalently, the layer output) at time step t.
The LSTM projected layer operation instead uses multiplications of the from $$R{Q}_{o}{Q}_{o}^{\top}{h}_{t1}$$, where Q_{o} is a
NumHiddenUnits
byOutputProjectorSize
matrix known
as the output projector. The layer uses the same projector
Q_{o} for each of the four
multiplications.
To perform the four multiplications of the form $$R{h}_{t1}$$, an LSTM layer stores four recurrent weights R, which
necessitates storing 4*NumHiddenUnits^2
learnable parameters. By instead
storing the 4*NumHiddenUnits
byOutputProjectorSize
matrix $$R\prime =R{Q}_{o}$$ and Q_{o}, an LSTM projected layer
can perform the multiplication $$R{Q}_{o}{Q}_{o}^{\top}{h}_{t1}$$ and store only 5*NumHiddenUnits*OutputProjectorSize
learnable parameters.
The LSTM layer operation uses four matrix multiplications of the form $$W{x}_{t}$$, where W denotes the input weights and x_{t} denotes the layer input at time step t.
The LSTM projected layer operation instead uses multiplications of the from $$W{Q}_{i}{Q}_{i}^{\top}{x}_{t}$$, where Q_{i} is an
InputSize
byInputProjectorSize
matrix known as
the input projector. The layer uses the same projector
Q_{i} for each of the four
multiplications.
To perform the four multiplications of the form $$W{x}_{t}$$, an LSTM layer stores four weight matrices W, which
necessitates storing 4*NumHiddenUnits*InputSize
learnable parameters. By
instead storing the
4*NumHiddenUnits
byInputProjectorSize
matrix $$W\prime =W{Q}_{i}$$ and Q_{i}, an LSTM projected layer
can perform the multiplication $$W{Q}_{i}{Q}_{i}^{\top}{x}_{t}$$ and store only
(4*NumHiddenUnits+InputSize)*InputProjectorSize
learnable
parameters.
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, 2D image data represented as a 4D 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 LSTMProjectedLayer
objects and the corresponding output format. If the output of the layer is passed 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.
Input Format  OutputMode  Output Format 

 "sequence" 

"last"  
 "sequence" 

"last" 
 
 "sequence" 

"last" 
In dlnetwork
objects, LSTMProjectedLayer
objects also support these
input and output format combinations.
Input Format  OutputMode  Output Format 

 "sequence" 

"last"  
 "sequence"  
"last"  
 "sequence"  
"last"  
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last"  
 "sequence"  
"last"  
 "sequence"  
"last"  
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last"  
 "sequence"  
"last"  
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last" 
 
 "sequence" 

"last" 

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] 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
[2] He, Kaiming, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. "Delving Deep into Rectifiers: Surpassing HumanLevel Performance on ImageNet Classification." In Proceedings of the 2015 IEEE International Conference on Computer Vision, 1026–1034. Washington, DC: IEEE Computer Vision Society, 2015. https://doi.org/10.1109/ICCV.2015.123
[3] Saxe, Andrew M., James L. McClelland, and Surya Ganguli. "Exact solutions to the nonlinear dynamics of learning in deep linear neural networks." arXiv preprint arXiv:1312.6120 (2013).
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
LSTM projected layer objects support generic C and C++ code generation only.
Version History
Introduced in R2022b
See Also
trainingOptions
 trainNetwork
 sequenceInputLayer
 lstmLayer
 bilstmLayer
 gruLayer
 convolution1dLayer
 neuronPCA
 compressNetworkUsingProjection
Topics
 Train Network with LSTM Projected Layer
 Compress Neural Network Using Projection
 Sequence Classification Using Deep Learning
 Sequence Classification Using 1D Convolutions
 Time Series Forecasting Using Deep Learning
 SequencetoSequence Classification Using Deep Learning
 SequencetoSequence Regression Using Deep Learning
 SequencetoOne Regression Using Deep Learning
 Classify Videos Using Deep Learning
 Long ShortTerm Memory Neural Networks
 List of Deep Learning Layers
 Deep Learning Tips and Tricks
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
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)