RecurrentSerial

class RecurrentSerial(feedfwd_connection: Connection, lateral_connection: Connection, feedback_connection: Connection, feedfwd_neuron: Neuron, feedback_neuron: Neuron, *, feedfwd_out_transform: OneToOne[Tensor] | None = None, lateral_out_transform: OneToOne[Tensor] | None = None, feedback_out_transform: OneToOne[Tensor] | None = None, lateral_in_transform: OneToMany[Tensor] | None = None, feedback_in_transform: OneToMany[Tensor] | None = None, feedfwd_connection_name: str = 'feedfwd', lateral_connection_name: str = 'lateral', feedback_connection_name: str = 'feedback', feedfwd_neuron_name: str = 'feedfwd', feedback_neuron_name: str = 'feedback', trainable_feedback: bool = False)[source]

Bases: Layer

Layer with a single feedforward connection and neuron group, and two feedback connections with a neuron group in-between.

\[\begin{split}\begin{align*} \texttt{inputs} &\rightarrow \texttt{feedfwd_connection} \\ \texttt{feedfwd_connection} + \texttt{feedback_connection} &\rightarrow \texttt{feedfwd_neuron} \\ \texttt{feedfwd_neuron} &\rightarrow \texttt{lateral_connection} \\ \texttt{lateral_connection} &\rightarrow \texttt{feedback_neuron} \\ \texttt{feedback_neuron} &\rightarrow \texttt{feedback_connection} \end{align*}\end{split}\]

This wraps Layer to provide simplified accessors and a simplified forward() method for layers with one feedforward connection, two feedback connections, and two neuron groups.

Parameters:

  • feedfwd_connection (Connection) – module which receives input to the layer.

  • lateral_connection (Connection) – module which receives input from the feedforward neurons.

  • feedback_connection (Connection) – module which receives input from the feedback neurons and applies it to the feedforward neurons.

  • feedfwd_neuron (Neuron) – module which generates output from the layer.

  • feedback_neuron (Neuron) – module which generates feedback spikes.

  • feedfwd_out_transform (OneToOne[torch.Tensor] | None, optional) – function to apply to feedforward connection output. Defaults to None.

  • lateral_out_transform (OneToOne[torch.Tensor] | None, optional) – function to apply to lateral connection output. Defaults to None.

  • feedback_out_transform (OneToOne[torch.Tensor] | None, optional) – function to apply to feedback connection output. Defaults to None.

  • lateral_in_transform (OneToMany[torch.Tensor] | None, optional) – function to apply to lateral connection input. Defaults to None.

  • feedback_in_transform (OneToMany[torch.Tensor] | None, optional) – function to apply to feedback connection input. Defaults to None.

  • feedfwd_connection_name (str, optional) – name for the feedforward connection in the layer. Defaults to "feedfwd".

  • lateral_connection_name (str, optional) – name for the lateral connection in the layer. Defaults to "lateral".

  • feedback_connection_name (str, optional) – name for the feedback connection in the layer. Defaults to "feedback".

  • feedfwd_neuron_name (str, optional) – name for the neuron in the layer. Defaults to "feedfwd".

  • feedback_neuron_name (str, optional) – name for the neuron in the layer. Defaults to "feedback".

  • trainable_feedback (bool, optional) – if feedback connections should be trainable. Defaults to False.

Note

When any of feedfwd_out_transform, lateral_out_transform, feedback_out_transform, or feedback_in_transform is not specified, the identity function is used. Keyword arguments passed into __call__, other than those captured in forward() will be passed in.

Important

When trainable_feedback is set to True, the feedback connection and neuron shapes need to be compatible for creating Cell objects.

Note

When any of feedfwd_out_transform, lateral_out_transform, feedback_out_transform, lateral_in_transform, or feedback_in_transform is not specified, the identity function is used (the latter two also wrapping the input in a tuple). Keyword arguments passed into __call__, other than those captured in forward() will be passed in. The lateral_in_transform and feedback_in_transform functions are only applied to the spiking input from the feedforward and feedback neurons respectively.

add_cell(*args, **kwargs) → None[source]

Creates and adds a cell if it doesn’t exist.

If a cell already exists with the given connection and neuron, this will return the existing cell rather than create a new one.

Parameters:

  • connection (str) – name of the connection for the cell to add.

  • neuron (str) – name of the neuron for the cell to add.

Raises:
Returns:

cell specified by the connection and neuron.

Return type:

Cell

add_connection(*args, **kwargs) → None[source]

Adds a new connection.

Parameters:

  • name (str) – name of the connection to add.

  • connection (Connection) – connection to add.

Raises:

RuntimeError – name already specifies a connection

Returns:

added connection.

Return type:

Connection

add_neuron(*args, **kwargs) → None[source]

Adds a new neuron.

Parameters:

  • name (str) – name of the neuron to add.

  • neuron (Neuron) – neuron to add.

Raises:

RuntimeError – name already specifies a neuron

Returns:

added neuron.

Return type:

Neuron

clear(clear_feedback: bool = True, submodules: bool = True, **kwargs) → None[source]

Clears the state of the layer.

Parameters:

  • clear_feedback (bool, optional) – if the feedback spikes should be cleared. Defaults to True.

  • submodules (bool, optional) – if the state of connections and neurons should also be cleared. Defaults to True.

  • **kwargs (Any) – keyword arguments passed to connection and neuron submodule clear methods, if submodules is True.

del_cell(*args, **kwargs) → None[source]

Deletes a created cell if it exists.

Even if a cell hasn’t been created with the given pair, if the pair is valid, this will not raise an error.

Parameters:

  • connection (str) – name of the connection for the cell to delete.

  • neuron (str) – name of the neuron for the cell to delete.

Raises:
del_connection(*args, **kwargs) → None[source]

Deletes an existing connection.

Parameters:

name (str) – name of the connection to delete.

Raises:

AttributeError – name does not specify a connection.

del_neuron(*args, **kwargs) → None[source]

Deletes an existing neuron.

Parameters:

name (str) – name of the neuron to delete.

Raises:

ValueError – name does not specify a neuron.

property feedback_cell: Cell | None

Registered feedback cell.

Returns:

registered feedback cell, if constructed with trainable_feedback, otherwise None.

Return type:

Cell

property feedback_connection: Connection

Registered feedback connection.

Returns:

registered feedback connection.

Return type:

Connection

property feedback_neuron: Neuron

Registered feedback neuron.

Returns:

registered feedback neuron.

Return type:

Neuron

property feedback_synapse: Synapse

Registered feedback synapse.

Returns:

registered feedback connection’s synapse.

Return type:

Synapse

property feedback_updater: Updater | None

Registered feedback updater.

Returns:

registered feedback connection’s updater.

Return type:

Updater

property feedfwd_cell: Cell

Registered feedforward cell.

Returns:

registered feedforward cell.

Return type:

Cell

property feedfwd_connection: Connection

Registered feedforward connection.

Returns:

registered feedforward connection.

Return type:

Connection

property feedfwd_neuron: Neuron

Registered feedforward neuron.

Returns:

registered feedforward neuron.

Return type:

Neuron

property feedfwd_synapse: Synapse

Registered feedforward synapse.

Returns:

registered feedforward connection’s synapse.

Return type:

Synapse

property feedfwd_updater: Updater

Registered feedforward updater.

Returns:

registered feedforward connection’s updater.

Return type:

Updater

forward(*inputs: Tensor, lateral_connection_args: Sequence[Tensor] | None = None, feedback_connection_args: Sequence[Tensor] | None = None, feedfwd_connection_kwargs: dict[str, Any] | None = None, lateral_connection_kwargs: dict[str, Any] | None = None, feedback_connection_kwargs: dict[str, Any] | None = None, feedfwd_neuron_kwargs: dict[str, Any] | None = None, feedback_neuron_kwargs: dict[str, Any] | None = None, capture_intermediate: bool = False, **kwargs) → Tensor | tuple[Tensor, Tensor][source]

Computes a forward pass.

Parameters:

  • *inputs (torch.Tensor) – values passed to the connection.

  • lateral_connection_args (Sequence[torch.Tensor] | None, optional) – additional positional arguments for lateral connection’s forward call. Defaults to None.

  • feedback_connection_args (Sequence[torch.Tensor] | None, optional) – additional positional arguments for feedback connection’s forward call. Defaults to None.

  • feedfwd_connection_kwargs (dict[str, dict[str, Any]] | None, optional) – keyword arguments for the feedforward connection’s forward call. Defaults to None.

  • lateral_connection_kwargs (dict[str, dict[str, Any]] | None, optional) – keyword arguments for the lateral connection’s forward call. Defaults to None.

  • feedback_connection_kwargs (dict[str, dict[str, Any]] | None, optional) – keyword arguments for the feedback connection’s forward call. Defaults to None.

  • feedfwd_neuron_kwargs (dict[str, dict[str, Any]] | None, optional) – keyword arguments for the feedforward neuron’s forward call. Defaults to None.

  • feedback_neuron_kwargs (dict[str, dict[str, Any]] | None, optional) – keyword arguments for the feedback neuron’s forward call. Defaults to None.

  • capture_intermediate (bool, optional) – if output from the connections should also be returned. Defaults to False.

  • **kwargs (Any) – keyword arguments passed to wiring().

Returns:

tuple of output from the feedforward and feedback neurons, in that order. If capture_intermediate, this is the first element of a tuple, the second being the outputs from the connections, as a dictionary of connection names to their corresponding outputs.

Return type:

tuple[torch.Tensor, torch.Tensor] | tuple[tuple[torch.Tensor, torch.Tensor], dict[str, torch.Tensor]]

Note

On the first input, zero-valued tensors are given as input for calculating feedback.

property lateral_cell: Cell | None

Registered lateral cell.

Returns:

registered lateral cell, if constructed with trainable_feedback, otherwise None.

Return type:

Cell

property lateral_connection: Connection

Registered lateral connection.

Returns:

registered lateral connection.

Return type:

Connection

property lateral_synapse: Synapse

Registered lateral synapse.

Returns:

registered lateral connection’s synapse.

Return type:

Synapse

property lateral_updater: Updater | None

Registered lateral updater.

Returns:

registered lateral connection’s updater.

Return type:

Updater

wiring(inputs: dict[str, Tensor], forward_pass: bool, **kwargs) → dict[str, Tensor][source]

Connection logic between connection outputs and neuron inputs.

This implements the forward logic of the feedback serial topology. The transform is applied to the result of the connection before being passed to the neuron. If not specified, it is assumed to be identity.

Parameters:
Returns:

dictionary of output names to tensors.

Return type:

dict[str, torch.Tensor]