org.deeplearning4j.nn.layers.recurrent

Class LSTM

java.lang.Object

org.deeplearning4j.nn.layers.AbstractLayer<LayerConfT>

org.deeplearning4j.nn.layers.BaseLayer<LayerConfT>

org.deeplearning4j.nn.layers.recurrent.BaseRecurrentLayer<LSTM>

org.deeplearning4j.nn.layers.recurrent.LSTM

All Implemented Interfaces:

Serializable, Cloneable, Layer, RecurrentLayer, Model

public class LSTM
extends BaseRecurrentLayer<LSTM>

LSTM layer implementation. See also for full/vectorized equations (and a comparison to other LSTM variants): Greff et al. 2015, "LSTM: A Search Space Odyssey", pg11. This is the "no peephole" variant in said paper http://arxiv.org/pdf/1503.04069.pdf

Author:

Alex Black

See Also:

GravesLSTM class, for the version with peephole connections, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface org.deeplearning4j.nn.api.Layer

Layer.TrainingMode, Layer.Type

Field Summary

Fields

Modifier and Type	Field and Description
protected FwdPassReturn	cachedFwdPass
protected LSTMHelper	helper
static String	STATE_KEY_PREV_ACTIVATION
static String	STATE_KEY_PREV_MEMCELL

Fields inherited from class org.deeplearning4j.nn.layers.recurrent.BaseRecurrentLayer

stateMap, tBpttStateMap

Fields inherited from class org.deeplearning4j.nn.layers.BaseLayer

gradient, gradientsFlattened, gradientViews, optimizer, params, paramsFlattened, score, solver

Fields inherited from class org.deeplearning4j.nn.layers.AbstractLayer

cacheMode, conf, dropoutApplied, dropoutMask, index, input, iterationListeners, maskArray, maskState, preOutput

Constructor Summary

Constructors

Constructor and Description
LSTM(NeuralNetConfiguration conf)
LSTM(NeuralNetConfiguration conf, org.nd4j.linalg.api.ndarray.INDArray input)

Method Summary

Modifier and Type	Method and Description
org.nd4j.linalg.api.ndarray.INDArray	activate() Trigger an activation with the last specified input
org.nd4j.linalg.api.ndarray.INDArray	activate(boolean training) Trigger an activation with the last specified input
org.nd4j.linalg.api.ndarray.INDArray	activate(org.nd4j.linalg.api.ndarray.INDArray input) Initialize the layer with the given input and return the activation for this layer given this input
org.nd4j.linalg.api.ndarray.INDArray	activate(org.nd4j.linalg.api.ndarray.INDArray input, boolean training) Initialize the layer with the given input and return the activation for this layer given this input
org.nd4j.linalg.api.ndarray.INDArray	activationMean() Calculate the mean representation for the activation for this layer
org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray>	backpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon) Calculate the gradient relative to the error in the next layer
Gradient	calcGradient(Gradient layerError, org.nd4j.linalg.api.ndarray.INDArray activation) Calculate the gradient
double	calcL1(boolean backpropParamsOnly) Calculate the l1 regularization term 0.0 if regularization is not used.
double	calcL2(boolean backpropParamsOnly) Calculate the l2 regularization term 0.0 if regularization is not used.
org.nd4j.linalg.primitives.Pair<org.nd4j.linalg.api.ndarray.INDArray,MaskState>	feedForwardMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray, MaskState currentMaskState, int minibatchSize) Feed forward the input mask array, setting in in the layer as appropriate.
Gradient	gradient() Calculate a gradient
boolean	isPretrainLayer() Returns true if the layer can be trained in an unsupervised/pretrain manner (VAE, RBMs etc)
org.nd4j.linalg.api.ndarray.INDArray	preOutput(org.nd4j.linalg.api.ndarray.INDArray x) Classify input
org.nd4j.linalg.api.ndarray.INDArray	preOutput(org.nd4j.linalg.api.ndarray.INDArray x, boolean training) Raw activations
org.nd4j.linalg.api.ndarray.INDArray	rnnActivateUsingStoredState(org.nd4j.linalg.api.ndarray.INDArray input, boolean training, boolean storeLastForTBPTT) Similar to rnnTimeStep, this method is used for activations using the state stored in the stateMap as the initialization.
org.nd4j.linalg.api.ndarray.INDArray	rnnTimeStep(org.nd4j.linalg.api.ndarray.INDArray input) Do one or more time steps using the previous time step state stored in stateMap. Can be used to efficiently do forward pass one or n-steps at a time (instead of doing forward pass always from t=0) If stateMap is empty, default initialization (usually zeros) is used Implementations also update stateMap at the end of this method
org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray>	tbpttBackpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon, int tbpttBackwardLength) Truncated BPTT equivalent of Layer.backpropGradient().
Layer	transpose() Return a transposed copy of the weights/bias (this means reverse the number of inputs and outputs on the weights)
Layer.Type	type() Returns the layer type

Methods inherited from class org.deeplearning4j.nn.layers.recurrent.BaseRecurrentLayer

rnnClearPreviousState, rnnGetPreviousState, rnnGetTBPTTState, rnnSetPreviousState, rnnSetTBPTTState

Methods inherited from class org.deeplearning4j.nn.layers.BaseLayer

accumulateScore, activate, activate, applyLearningRateScoreDecay, clone, computeGradientAndScore, error, fit, fit, getGradientsViewArray, getOptimizer, getParam, initParams, iterate, layerConf, merge, numParams, params, paramTable, paramTable, preOutput, preOutput, score, setBackpropGradientsViewArray, setParam, setParams, setParams, setParamsViewArray, setParamTable, setScoreWithZ, toString, update, update

Methods inherited from class org.deeplearning4j.nn.layers.AbstractLayer

addListeners, applyDropOutIfNecessary, applyMask, batchSize, clear, conf, derivativeActivation, getIndex, getInput, getInputMiniBatchSize, getListeners, getMaskArray, gradientAndScore, init, input, layerId, numParams, setCacheMode, setConf, setIndex, setInput, setInputMiniBatchSize, setListeners, setListeners, setMaskArray, validateInput

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.deeplearning4j.nn.api.Layer

activate, activate, clone, derivativeActivation, error, getIndex, getInputMiniBatchSize, getListeners, getMaskArray, merge, preOutput, setCacheMode, setIndex, setInput, setInputMiniBatchSize, setListeners, setListeners, setMaskArray

Methods inherited from interface org.deeplearning4j.nn.api.Model

accumulateScore, addListeners, applyLearningRateScoreDecay, batchSize, clear, computeGradientAndScore, conf, fit, fit, getGradientsViewArray, getOptimizer, getParam, gradientAndScore, init, initParams, input, iterate, numParams, numParams, params, paramTable, paramTable, score, setBackpropGradientsViewArray, setConf, setParam, setParams, setParamsViewArray, setParamTable, update, update, validateInput

Field Detail

STATE_KEY_PREV_ACTIVATION

public static final String STATE_KEY_PREV_ACTIVATION

See Also:

Constant Field Values

STATE_KEY_PREV_MEMCELL

public static final String STATE_KEY_PREV_MEMCELL

See Also:

Constant Field Values

helper

protected LSTMHelper helper

cachedFwdPass

protected FwdPassReturn cachedFwdPass

Constructor Detail

LSTM

public LSTM(NeuralNetConfiguration conf)

LSTM

public LSTM(NeuralNetConfiguration conf,
            org.nd4j.linalg.api.ndarray.INDArray input)

Method Detail

gradient

public Gradient gradient()

Description copied from interface: Model

Calculate a gradient

Specified by:

gradient in interface Model

Overrides:

gradient in class BaseLayer<LSTM>

Returns:

the gradient for this model

calcGradient

public Gradient calcGradient(Gradient layerError,
                             org.nd4j.linalg.api.ndarray.INDArray activation)

Description copied from interface: Layer

Calculate the gradient

Specified by:

calcGradient in interface Layer

Overrides:

calcGradient in class BaseLayer<LSTM>

Parameters:

layerError - the layer error

Returns:

the gradient

backpropGradient

public org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray> backpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon)

Description copied from interface: Layer

Calculate the gradient relative to the error in the next layer

Specified by:

backpropGradient in interface Layer

Overrides:

backpropGradient in class BaseLayer<LSTM>

Parameters:

epsilon - w^(L+1)*delta^(L+1). Or, equiv: dC/da, i.e., (dC/dz)*(dz/da) = dC/da, where C is cost function a=sigma(z) is activation.

Returns:

Pair where Gradient is gradient for this layer, INDArray is epsilon needed by next layer, but before element-wise multiply by sigmaPrime(z). So for standard feed-forward layer, if this layer is L, then return.getSecond() == (w^(L)*(delta^(L))^T)^T

tbpttBackpropGradient

public org.nd4j.linalg.primitives.Pair<Gradient,org.nd4j.linalg.api.ndarray.INDArray> tbpttBackpropGradient(org.nd4j.linalg.api.ndarray.INDArray epsilon,
                                                                                                            int tbpttBackwardLength)

Description copied from interface: RecurrentLayer

Truncated BPTT equivalent of Layer.backpropGradient(). Primary difference here is that forward pass in the context of BPTT is that we do forward pass using stored state for truncated BPTT vs. from zero initialization for standard BPTT.

preOutput

public org.nd4j.linalg.api.ndarray.INDArray preOutput(org.nd4j.linalg.api.ndarray.INDArray x)

Description copied from class: AbstractLayer

Classify input

Specified by:

preOutput in interface Layer

Overrides:

preOutput in class AbstractLayer<LSTM>

Parameters:

x - the input (can either be a matrix or vector) If it's a matrix, each row is considered an example and associated rows are classified accordingly. Each row will be the likelihood of a label given that example

Returns:

a probability distribution for each row

preOutput

public org.nd4j.linalg.api.ndarray.INDArray preOutput(org.nd4j.linalg.api.ndarray.INDArray x,
                                                      boolean training)

Description copied from interface: Layer

Raw activations

Specified by:

preOutput in interface Layer

Overrides:

preOutput in class AbstractLayer<LSTM>

Parameters:

x - the input to transform

Returns:

the raw activation for this layer

activate

public org.nd4j.linalg.api.ndarray.INDArray activate(org.nd4j.linalg.api.ndarray.INDArray input,
                                                     boolean training)

Description copied from interface: Layer

Initialize the layer with the given input and return the activation for this layer given this input

Specified by:

activate in interface Layer

Overrides:

activate in class AbstractLayer<LSTM>

Parameters:

input - the input to use

training - train or test mode

Returns:

activate

public org.nd4j.linalg.api.ndarray.INDArray activate(org.nd4j.linalg.api.ndarray.INDArray input)

Description copied from interface: Layer

Initialize the layer with the given input and return the activation for this layer given this input

Specified by:

activate in interface Layer

Overrides:

activate in class AbstractLayer<LSTM>

Parameters:

input - the input to use

Returns:

activate

public org.nd4j.linalg.api.ndarray.INDArray activate(boolean training)

Description copied from interface: Layer

Trigger an activation with the last specified input

Specified by:

activate in interface Layer

Overrides:

activate in class BaseLayer<LSTM>

Parameters:

training - training or test mode

Returns:

the activation of the last specified input

activate

public org.nd4j.linalg.api.ndarray.INDArray activate()

Description copied from interface: Layer

Trigger an activation with the last specified input

Specified by:

activate in interface Layer

Overrides:

activate in class AbstractLayer<LSTM>

Returns:

the activation of the last specified input

activationMean

public org.nd4j.linalg.api.ndarray.INDArray activationMean()

Description copied from interface: Layer

Calculate the mean representation for the activation for this layer

Specified by:

activationMean in interface Layer

Overrides:

activationMean in class BaseLayer<LSTM>

Returns:

the activation mean for this layer

type

public Layer.Type type()

Description copied from interface: Layer

Returns the layer type

Specified by:

type in interface Layer

Overrides:

type in class AbstractLayer<LSTM>

Returns:

transpose

public Layer transpose()

Description copied from interface: Layer

Return a transposed copy of the weights/bias (this means reverse the number of inputs and outputs on the weights)

Specified by:

transpose in interface Layer

Overrides:

transpose in class BaseLayer<LSTM>

Returns:

the transposed layer

isPretrainLayer

public boolean isPretrainLayer()

Description copied from interface: Layer

Returns true if the layer can be trained in an unsupervised/pretrain manner (VAE, RBMs etc)

Returns:

true if the layer can be pretrained (using fit(INDArray), false otherwise

feedForwardMaskArray

public org.nd4j.linalg.primitives.Pair<org.nd4j.linalg.api.ndarray.INDArray,MaskState> feedForwardMaskArray(org.nd4j.linalg.api.ndarray.INDArray maskArray,
                                                                                                            MaskState currentMaskState,
                                                                                                            int minibatchSize)

Description copied from interface: Layer

Feed forward the input mask array, setting in in the layer as appropriate. This allows different layers to handle masks differently - for example, bidirectional RNNs and normal RNNs operate differently with masks (the former sets activations to 0 outside of the data present region (and keeps the mask active for future layers like dense layers), whereas normal RNNs don't zero out the activations/errors )instead relying on backpropagated error arrays to handle the variable length case.
This is also used for example for networks that contain global pooling layers, arbitrary preprocessors, etc.

Specified by:

feedForwardMaskArray in interface Layer

Overrides:

feedForwardMaskArray in class AbstractLayer<LSTM>

Parameters:

maskArray - Mask array to set

currentMaskState - Current state of the mask - see MaskState

minibatchSize - Current minibatch size. Needs to be known as it cannot always be inferred from the activations array due to reshaping (such as a DenseLayer within a recurrent neural network)

Returns:

New mask array after this layer, along with the new mask state.

calcL2

public double calcL2(boolean backpropParamsOnly)

Description copied from interface: Layer

Calculate the l2 regularization term
0.0 if regularization is not used. Or 0.5 * l2Coeff * l2Magnitude otherwise.
Note that this does not divide by mini-batch size

Specified by:

calcL2 in interface Layer

Overrides:

calcL2 in class BaseLayer<LSTM>

Parameters:

backpropParamsOnly - If true: calculate L2 based on backprop params only. If false: calculate based on all params (including pretrain params, if any)

Returns:

the l2 regularization term for this layer.

calcL1

public double calcL1(boolean backpropParamsOnly)

Description copied from interface: Layer

Calculate the l1 regularization term
0.0 if regularization is not used. Or l1Coeff * l1Magnitude otherwise.
Note that this does not divide by mini-batch size

Specified by:

calcL1 in interface Layer

Overrides:

calcL1 in class BaseLayer<LSTM>

Parameters:

backpropParamsOnly - If true: calculate L1 based on backprop params only. If false: calculate based on all params (including pretrain params, if any)

Returns:

the l1 regularization term for this layer.

rnnTimeStep

public org.nd4j.linalg.api.ndarray.INDArray rnnTimeStep(org.nd4j.linalg.api.ndarray.INDArray input)

Description copied from interface: RecurrentLayer

Do one or more time steps using the previous time step state stored in stateMap.
Can be used to efficiently do forward pass one or n-steps at a time (instead of doing forward pass always from t=0)
If stateMap is empty, default initialization (usually zeros) is used
Implementations also update stateMap at the end of this method

Parameters:

input - Input to this layer

Returns:

activations

rnnActivateUsingStoredState

public org.nd4j.linalg.api.ndarray.INDArray rnnActivateUsingStoredState(org.nd4j.linalg.api.ndarray.INDArray input,
                                                                        boolean training,
                                                                        boolean storeLastForTBPTT)

Description copied from interface: RecurrentLayer

Similar to rnnTimeStep, this method is used for activations using the state stored in the stateMap as the initialization. However, unlike rnnTimeStep this method does not alter the stateMap; therefore, unlike rnnTimeStep, multiple calls to this method (with identical input) will:
(a) result in the same output
(b) leave the state maps (both stateMap and tBpttStateMap) in an identical state

Parameters:

input - Layer input

training - if true: training. Otherwise: test

storeLastForTBPTT - If true: store the final state in tBpttStateMap for use in truncated BPTT training

Returns:

Layer activations