Models (`reservoirpy.Model`)#

Note

See the following guides to:

Learn more about how to work with ReservoirPy Nodes: Node functional API
Learn more about how to combine nodes within a Model: From Nodes to Models

Models are an extension of the Node API. They allow to combine nodes into complex computational graphs, to create complicated Reservoir Computing architecture like Deep Echo State Networks.

See From Nodes to Models to learn more about how to create and manipulate a Model.

class reservoirpy.model.Model( nodes: Sequence[Node], edges: Sequence[tuple[Node, int, Node]], )[source]#

Model base class.

Parameters:

nodes (list of Node, optional) – Nodes to include in the Model.
edges (list of (Node, int, Node), optional) – Edges between Nodes in the graph. An edge between a Node A and a Node B with a delay of \(d\) is created as a tuple (A, d, B).

Methods

`initialize`(x[, y])	Initializes a `Model` instance at runtime, using samples of data to infer all `Node` dimensions and instantiate the feedback buffers.
`step`([x])	Call the Model function on a single step of data and update its state.
`run`([x, iters, workers])	Run the Model on a sequence of data.
`predict`([x, iters, workers])	Alias for `run()`.
`fit`(x[, y, warmup, workers])	Offline fitting method of a Model.
`partial_fit`(x[, y])	Fit the Model in an online fashion.

Attributes

`nodes`	List of Nodes contained in the model, in insertion order.
`edges`	List of `(NodeA, d, NodeB)` edges, representing a connection from `NodeA` to `NodeB` with a delay of `d`.
`inputs`	List of Nodes that expects an input
`outputs`	List of Nodes expected to output their values
`named_nodes`	Dictionary that associates a name to a Node with that name in the model.
`trainable_nodes`	List of nodes that can be trained
`execution_order`	List of Nodes contained in the model, in the order they should be run.
`parents`	Dictionary that associates a list of all Nodes connected to the key Node.
`children`	Dictionary that associates a list of all Nodes to which the key node is connected.
`is_trainable`	If True, the model can be trained (with `fit()`).
`is_multi_input`	If True, the model has multiple Node inputs
`is_multi_output`	If True, the model has multiple outputs and returns a dictionary that associates a node name to a node output.
`is_parallel`	If True, the model can be trained in parallel (offline).
`initialized`	If True, the model and its Nodes has been initialized.

children: dict[Node, list[Node]]#: Dictionary that associates a list of all Nodes to which the key node is connected.

edges: list[tuple[Node, int, Node]]#: List of (NodeA, d, NodeB) edges, representing a connection from NodeA to NodeB with a delay of d.

execution_order: list[Node]#: List of Nodes contained in the model, in the order they should be run.

feedback_buffers: dict[tuple[Node, int, Node], ndarray[tuple[int, int], dtype[floating]]]#: Dictionary of edges -> np.ndarray where arrays contain the values to be sent to the receiving node.

Offline fitting method of a Model.

Parameters:

x (list or array-like of shape ([series, ] timesteps, input_dim) or a mapping of input, optional) – Input sequences dataset.
y (list or array-like of shape ([series], timesteps, output_dim), or a mapping of input optional) – Teacher signals dataset. If None, the method will try to fit the Node in an unsupervised way, if possible.
warmup (int, default to 0) – Number of timesteps to consider as warmup and discard at the beginning of each timeseries before training.
workers (int) –

Returns:

Node trained offline.

Return type:

Node

Initializes a Model instance at runtime, using samples of data to infer all Node dimensions and instantiate the feedback buffers.

Parameters:

x (numpy.ndarray or dict of numpy.ndarray) – A vector of shape (1, ndim) corresponding to a timestep of data, or a dictionary mapping node names to vector of shapes (1, ndim of corresponding node).
y (numpy.ndarray or dict of numpy.ndarray, optional) – A vector of shape (1, ndim) corresponding to a timestep of target data, or a dictionary mapping node names to vector of shapes (1, ndim of corresponding node).

initialized: bool#: If True, the model and its Nodes has been initialized.

inputs: list[Node]#: List of Nodes that expects an input

is_multi_input: bool#: If True, the model has multiple Node inputs

is_multi_output: bool#: If True, the model has multiple outputs and returns a dictionary that associates a node name to a node output.

is_online: bool#: If True, the model can be trained online (with partial_fit()).

is_parallel: bool#: If True, the model can be trained in parallel (offline).

is_trainable: bool#: If True, the model can be trained (with fit()).

named_nodes: dict[str, Node]#: Dictionary that associates a name to a Node with that name in the model.

nodes: list[Node]#: List of Nodes contained in the model, in insertion order.

outputs: list[Node]#: List of Nodes expected to output their values

parents: dict[Node, list[Node]]#: Dictionary that associates a list of all Nodes connected to the key Node.

Fit the Model in an online fashion.

This method both trains the Model parameters and produce predictions on the run. Calling partial_fit() updates the Model without resetting the parameters, unlike fit().

Parameters:

x (array-like of shape (timesteps, input_dim)) – Input sequence of data.
y (array-like of shape (timesteps, output_dim), optional.) – Target sequence of data. If None, the Node will train in an unsupervised way, if possible.

Returns:

All outputs computed during the training.

Return type:

array of shape (timesteps, output_dim) or mapping of arrays

Alias for run().

Parameters:

x (array ([s,] t, d), list of arrays (t, d) or a mapping of them, optional) – A timeseries, multiple timeseries, or a mapping of timeseries or multiple timeseries. Input of the Model.
iters (int, optional) – If x is None, a dimensionless timeseries of length iters is used instead.
workers (int, default to 1) – Number of workers used for parallelization. If set to -1, all available workers (threads or processes) are used.

Returns:

A sequence of output vectors. If the model has multiple outputs, a mapping is returned instead.

Return type:

array of shape ([n_inputs,] timesteps, output_dim) or list of arrays, or dict

reset() → tuple[dict[Node, dict[str, ndarray]], dict[tuple[Node, int, Node], ndarray[tuple[int, int], dtype[floating]]]][source]#

Reset all Node states and buffers in the Model.

Returns:: dict[str, np.array], dict[Edge, array]
Return type:: previous states of the Nodes and previous feedback buffer values.

Run the Model on a sequence of data.

Parameters:

x (array ([s,] t, d), list of arrays (t, d) or a mapping of them, optional) – A timeseries, multiple timeseries, or a mapping of timeseries or multiple timeseries. Input of the Model.
iters (int, optional) – If x is None, a dimensionless timeseries of length iters is used instead.
workers (int, default to 1) – Number of workers used for parallelization. If set to -1, all available workers (threads or processes) are used.

Returns:

A sequence of output vectors. If the model has multiple outputs, a mapping is returned instead.

Return type:

array of shape ([n_inputs,] timesteps, output_dim) or list of arrays, or dict

step( x: array(d) | dict[str, array(d)] | None = None, ) → array(d,) | dict[str, array(d,)][source]#

Call the Model function on a single step of data and update its state.

Parameters:: x (array of shape (input_dim,), optional) – One single step of input data. If None, an empty array is used instead and the Node is assumed to have an input_dim of 0
Returns:: An output vector. If the model has multiple outputs, a dictionary is returned instead.
Return type:: array of shape (output_dim,) or dict of 1D arrays.

trainable_nodes: list[Node]#: List of nodes that can be trained

Models (reservoirpy.Model)#

Models (`reservoirpy.Model`)#