FORCE Model

Base FORCE Model

class tension.base.FORCEModel(*args, **kwargs)

Base class for FORCE model per Sussillo and Abbott.

Input to the model during FORCEModel’s fit, predict, or evaluate methods should be of shape timesteps x input dimension or batch size x timesteps x input dimension. If the latter is used, the batches are stacked.

Target to the model during fit or evaluate should be of shape timesteps x output dimension or batch size x timesteps x output dimension.

If validation data is to be passed to fit, input and target of the validation data should be of shape timesteps x input dimension and timesteps x output dimension respectively or batch size x timesteps x input dimensions and batch size x timesteps x output dimension respectively.

Input to the model when calling the model should be of shape 1 x timesteps x input dimensions.

If the recurrent kernel is to be trained, then the target must be one dimensional.

Use self.force_layer.states to access the states of self.force_layer.

Parameters:

force_layer (class[FORCELayer] or equiv.) – A FORCE Layer object or one of its subclasses.
alpha_P (float) – Constant parameter for initializing the P matrix. (Default: 1.0)
return_sequences (bool) – If True, target is returned as a sequence of the same length as the number of time steps in the input. (Default: True) Note: must be True for compatibility with existing layers of this package.

build(input_shape)

Inherited from tensorflow.keras.Model.build, also calls method that performs the initialization of variables the model requires for training. Typically called implicitly.

Parameters:: input_shape (tuple) – Shape of the input tensor.

call(x, training=False, reset_states=False, **kwargs)

Inherited and serves the same function as from tensorflow.keras.Model.call.

Note: By default, reset_states=False and therefore, the self.force_layer’s states are not reset at the end of the execution.

Parameters:

x (Tensor[3D float]) – Input tensor of shape (1, timestep, input dimension).
training (bool) – Whether the model is being called during training or inference. (Default: False)
reset_states (bool) – Whether to reset the state of self.force_layer after the model is called. (Default: False)
kwargs – Other key word arguments as needed.

coerce_input_data(x, y, method, **kwargs)

Coerces the input data to a desired shape based on method used (fit, predict, evaluate).

Parameters:

x (Tensor[3D float]) – Tensor of shape timestep x 1 x input dimensions
y (Tensor[3D float]) – Tensor of shape timestep x 1 x target dimensions
method (str) – One of fit, validation, predict, or evaluate
kwargs – Other arguments as needed.

compile(metrics, **kwargs)

A wrapper around tensorflow.keras.Model.compile.

Note: The optimizer and loss parameters are not supported.

Parameters:: metrics (list[str]) – Same as in tensorflow.keras.Model.compile.

evaluate(x, y, **kwargs)

A wrapper around tensorflow.keras.Model.evaluate. Note: the batch_size and steps parameter are not supported.

Parameters:

x (Tensor[2D or 3D float]) – Tensor of input signal of shape timesteps x input dimensions or batch size x timesteps x input dimensions.
y (Tensor[2D or 3D float]) – Tensor of target signal of shape timesteps x output dimensions or batch size x timesteps x input dimensions.

Returns:

(List[float]) - List of error / metrics evaluated on the input

fit(x, y=None, epochs=1, verbose='auto', **kwargs)

A wrapper around tensorflow.keras.Model.fit. Note: the batch_size, validation_batch_size, shuffle, steps_per_epoch, and validation_steps parameters are not supported.

Parameters:

x (Tensor[2D or 3D float]) – Tensor of input signal of shape timesteps x input dimensions or batch size x timesteps x input dimensions.
y (Tensor[2D or 3D float]) – Tensor of target signal of shape timesteps x output dimensions or batch size x timesteps x input dimensions.
epoch (int) – Number of epochs to train.
verbose (str) – Same as from tensorflow.keras.Model.fit.
kwargs – Other key word arguments as needed.

force_layer_call(x, training, **kwargs)

Calls self.force_layer; to be customized via sub-classing.

Parameters:

x (Tensor[3D float]) – Input tensor.
training (bool) – If True, indicates that this function is being called during training.
kwargs – Other key word arguments as needed.

Returns:

(tuple[Tensor[2D float]]) - Output of self.force_layer’s call method.

initialize_P(): Initializes the P matrices corresponding to the output and recurrent kernel necessary for FORCE.

initialize_train_idx(): Finds the indices inside self.trainable_variables corresponding to the relevant kernel and P tensors.

predict(x, **kwargs)

A wrapper around tensorflow.keras.Model.predict. Note: the batch_size and steps parameter are not supported.

Parameters:: x (Tensor[2D or 3D float]) – Tensor of input signal of shape timesteps x input dimensions or batch size x timesteps x input dimensions.
Returns:: (Array[2D or 3D float]) - Numpy array of predictions

pseudogradient_P(P, h)

Returns pseudogradient for the P tensor. Can be customized as needed if different update rule is required.

Example array shapes:

h : 1 x self.units
P : self.units x self.units
k : self.units x 1 
hPht : 1 x 1
dP : self.units x self.units

Parameters:

P (Tensor[2D float]) – The FORCE P tensor.
h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron.

Returns:

dP (Tensor[2D float]) - A self.units x self.units pseudogradient of the FORCE P tensor.
Pht (Tensor[2D float]) - self.units x 1 intermediate tensor from pseudogradient computation.
hPht (Tensor[2D float]) - 1 x 1 intermediate tensor from pseudogradient computation.

pseudogradient_P_Gx(P_Gx, h)

Returns pseudogradient for P corresponding to recurrent kernel

Parameters:

P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel.
h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron

Returns:

dP_Gx (Tensor[3D float]) - A self.units x self.units x self.units tensor that is the pseudogradient of the FORCE P tensor corresponding to the recurrent kernel.
Ph (Tensor[2D float]) - Intermediate tensor from pseudogradient computation.
hPh (Tensor[3D float]) - Intermediate tensor from pseudogradient computation.

pseudogradient_wO(P, h, z, y, Pht, hPht)

Return pseudogradient for wO. Can be customized as needed if different update rule is required.

Example array shapes:

P : self.units x self.units
h : 1 x self.units
z, y : 1 x output dimension

Parameters:

P (Tensor[2D float]) – The FORCE P tensor corresponding to output kernel.
h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron.
z (Tensor[2D float]) – An 1 x output dimensions tensor of predictions.
y (Tensor[2D float]) – An 1 x output dimensions tensor of ground truth target.
Pht (Tensor[2D float]) – self.units x 1 intermediate tensor from pseudogradient computation in the pseudogradient_P method (unused by default).
hPht (Tensor[2D float]) – 1 x 1 intermediate tensor from pseudogradient computation in the pseudogradient_P method (unused by default).

Returns:

dwO (Tensor[2D float]) - Weight updates for the output kernel.

pseudogradient_wR(P_Gx, h, z, y, Ph, hPh)

Return pseudogradient for wR

Parameters:

P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel.
h (Tensor[2D float]) – A 1 x self.units tensor of firing ratings for each recurrent neuron.
z (Tensor[2D float]) – A 1 x 1 tensor of predictions.
y (Tensor[2D float]) – A 1 x 1 tensor of ground truth target.
Ph (Tensor[2D float]) – Intended to match output from the pseudogradient_P_Gx method (unused by default).
hPh (Tensor[3D float]) – Intended to match output from pseudogradient_P_Gx method (unused by default).

Returns:

dwR (Tensor[2D float]) - Weight updates for the recurrent kernel.

train_step(data)

Inherited and serves the same function as from tensorflow.keras.Model.train_step. Performs weight updates for the output and recurrent kernels.

Intended to be customized via Keras style sub-classing. For more details see: https://keras.io/guides/customizing_what_happens_in_fit/

update_output_kernel(h, z, y, trainable_vars_P_output, trainable_vars_output_kernel)

Performs pseudogradient updates for output kernel and its corresponding P tensor.

Parameters:

h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron.
z (Tensor[2D float]) – An 1 x output dimensions tensor of predictions.
y (Tensor[2D float]) – An 1 x output dimensions tensor of ground truth target.
trainable_vars_P_output (Tensor[2D float]) – The FORCE P tensor corresponding to the output kernel.
trainable_vars_output_kernel (Tensor[2D float]) – Output kernel of self.force_layer.

update_recurrent_kernel(h, z, y, trainable_vars_P_Gx, trainable_vars_recurrent_kernel)

Performs pseudogradient updates for recurrent kernel and its corresponding P tensor

Parameters:

h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron
z (Tensor[2D float]) – An 1 x output dimensions tensor of predictions
y (Tensor[2D float]) – An 1 x output dimensions tensor of ground truth target
trainable_vars_P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel
trainable_vars_recurrent_kernel (Tensor[2D float]) – A self.units x self.units tensor corresponding to the force layer’s recurrent kernel

Inherited FORCE Model

class tension.models.FullFORCEModel(*args, **kwargs)

Subclassed from FORCEModel, implements full FORCE learning by DePasquale et al..

Target to the model should be of shape timesteps x 1 or batch size x timesteps x 1. Presently this class does not support masking out recurrent weights during training (all recurrent weights must be trainable).

Note - Input shapes during training and inference differ: During training, input to the model should be of shape timesteps x input dimensions + hint dimensions or batch size x timesteps x input dimensions + hint dimensions. During inference, input to the model should be of shape timesteps x input dimensions or batch size x timesteps x input dimensions. During model call when training=True, input to the call should have shape 1 x timesteps x input dimensions + hint dimensions + output dimensions. During model call when training=False, input to the call should have shape 1 x timesteps x input dimensions.

Parameters:

hint_dim (int) – Dimension of the hint input
target_output_kernel_trainable (bool) – If True, train the target output kernel (Default: False)
kwargs – Other key word arguments as needed. See base.FORCEModel

build(input_shape)

Inherited from tensorflow.keras.Model.build, also calls method that performs the initialization of variables the model requires for training. Typically called implicitly.

Parameters:: input_shape (tuple) – Shape of the input tensor.

call(x, training=False, reset_states=False, **kwargs)

Inherited and serves the same function as from tensorflow.keras.Model.call.

Note: By default, reset_states=False and therefore, the self.force_layer’s states are not reset at the end of the execution.

Parameters:

x (Tensor[3D float]) – Input tensor of shape (1, timestep, input dimension).
training (bool) – Whether the model is being called during training or inference. (Default: False)
reset_states (bool) – Whether to reset the state of self.force_layer after the model is called. (Default: False)
kwargs – Other key word arguments as needed.

force_layer_call(x, training, **kwargs)

Calls self.force_layer; to be customized via sub-classing.

Parameters:

x (Tensor[3D float]) – Input tensor.
training (bool) – If True, indicates that this function is being called during training.
kwargs – Other key word arguments as needed.

Returns:

(tuple[Tensor[2D float]]) - Output of self.force_layer’s call method.

initialize_P(): Initializes the P matrices corresponding to the output kernel necessary for FORCE for the task and target generating network.

initialize_target_network(input_shape)

Initializes the target generating network.

Parameters:: input_shape (tuple) – Input shape

initialize_train_idx(): Finds the indices inside self.trainable_variables corresponding to the relevant kernel and P tensors.

pseudogradient_wR_task(P_task, wR_task, h_task, wR_target, h_target, fb_hint_sum)

Return pseudogradient for wR for the task network.

Parameters:

P_task (Tensor[2D floats]) – self.units x self.units P matrix of the task network
wR_task (Tensor[2D floats]) – self.units x self.units recurrent kernel of the task network
h_task (Tensor[2D floats]) – 1 x self.units tensor of neuron firing rates for task network
wR_target (Tensor[2D floats]) – self.units x self.units recurrent kernel of the target network
h_target (Tensor[2D floats]) – 1 x self.units tensor of neuron firing rates for target network
fb_hint_sum (Tensor[2D floats]) – 1 x self.units tensor of sum of inputs from feedback and hint components

update_recurrent_kernel(h_task, h_target, fb_hint_sum, trainable_vars)

Performs pseudogradient updates for recurrent kernel and its corresponding P tensor.

Parameters:

h_task (Tensor[2D float]) – 1 x self.units tensor of neuron firing rates for task network
h_target (Tensor[2D float]) – 1 x self.units tensor of neuron firing rates for target network
fb_hint_sum (Tensor[2D float]) – 1 x self.units tensor of sum of inputs from feedback and hint components
trainable_vars (list[Tensor[2D floats]]) – List of the model’s trainable variable

class tension.models.OptimizedFORCEModel(*args, **kwargs)

Optimized version of the FORCEModel class if all recurrent weights in the network is trainable.

If the recurrent kernel is to be trained, then the target must be one dimensional.

initialize_P(): Initializes the P matrices corresponding to the output and recurrent kernel necessary for FORCE.

pseudogradient_P_Gx(P_Gx, h)

Returns pseudogradient for P corresponding to recurrent kernel

Parameters:

P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel.
h (Tensor[2D float]) – An 1 x self.units tensor of firing ratings for each recurrent neuron

Returns:

dP_Gx (Tensor[3D float]) - A self.units x self.units x self.units tensor that is the pseudogradient of the FORCE P tensor corresponding to the recurrent kernel.
Ph (Tensor[2D float]) - Intermediate tensor from pseudogradient computation.
hPh (Tensor[3D float]) - Intermediate tensor from pseudogradient computation.

pseudogradient_wR(P_Gx, h, z, y, Ph, hPh)

Return pseudogradient for wR

Parameters:

P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel.
h (Tensor[2D float]) – A 1 x self.units tensor of firing ratings for each recurrent neuron.
z (Tensor[2D float]) – A 1 x 1 tensor of predictions.
y (Tensor[2D float]) – A 1 x 1 tensor of ground truth target.
Ph (Tensor[2D float]) – Intended to match output from the pseudogradient_P_Gx method (unused by default).
hPh (Tensor[3D float]) – Intended to match output from pseudogradient_P_Gx method (unused by default).

Returns:

dwR (Tensor[2D float]) - Weight updates for the recurrent kernel.

class tension.constrained.BioFORCEModel(*args, **kwargs)

Trains constrained ESN without feedback based on Hadjiabadi et al..

pseudogradient_wR(P_Gx, h, z, y, Ph, hPh)

Return pseudogradient for wR

Parameters:

P_Gx (Tensor[3D float]) – A self.units x self.units x self.units P tensor corresponding to the recurrent kernel.
h (Tensor[2D float]) – A 1 x self.units tensor of firing ratings for each recurrent neuron.
z (Tensor[2D float]) – A 1 x 1 tensor of predictions.
y (Tensor[2D float]) – A 1 x 1 tensor of ground truth target.
Ph (Tensor[2D float]) – Intended to match output from the pseudogradient_P_Gx method (unused by default).
hPh (Tensor[3D float]) – Intended to match output from pseudogradient_P_Gx method (unused by default).

Returns:

dwR (Tensor[2D float]) - Weight updates for the recurrent kernel.

class tension.spiking.SpikingNNModel(*args, **kwargs)

Implements FORCE training on spiking neural networks per Nicola and Clopath.

force_layer_call(x, training, **kwargs)

Calls self.force_layer; to be customized via sub-classing.

Parameters:

x (Tensor[3D float]) – Input tensor.
training (bool) – If True, indicates that this function is being called during training.
kwargs – Other key word arguments as needed.

Returns:

(tuple[Tensor[2D float]]) - Output of self.force_layer’s call method.