Simple Echo State Network.

This class is provided as a wrapper for a simple reservoir connected to a readout.

Parameters:

units (int, optional) – Number of reservoir units. If None, the number of units will be inferred from the W matrix shape.
reservoir (Node, optional) – A Node instance to use as a reservoir, such as a Reservoir node.
readout (Node, optional) – A Node instance to use as a readout, such as a Ridge node (only this one is supported).
feedback (bool, defaults to False) – If True, the readout is connected to the reservoir through a feedback connection.
input_to_readout (bool, defaults to False) – If True, the input is directly fed to the readout. See Input-to-readout connections.
return_reservoir_activity (bool, defaults to False) – If True, the model outputs a dict with the reservoir activity in addition to the readout output.
**kwargs – Arguments passed to the reservoir and readout.

See also

Reservoir, Ridge

Example

>>> from reservoirpy import ESN
>>>
>>> model = ESN(units=100, sr=0.9, ridge=1e-6)  # reservoir and readout parameters at once
>>> model.fit(x_train, y_train)
>>>
>>> model = ESN(reservoir=Reservoir(100, sr=0.9), readout=Ridge(1e-5))  # passing nodes as parameters
>>>
>>> model = ESN(units=100, input_to_readout=True, feedback=True)  # more complex model

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

`reservoir`	A `Reservoir` or a `NVAR` instance.
`readout`	A `Ridge` instance.
`feedback`	Is readout connected to reservoir through feedback (False by default).
`input_to_readout`	Is the readout directly receiving the input (False by default).
`input_node`	Input node, if `input_to_readout` is set to True
`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: bool#: Is readout connected to reservoir through feedback (False by default).

feedback_buffers: FeedbackBuffers#: 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.

input_node: Input | None = None#: Input node, if input_to_readout is set to True

input_to_readout: bool#: Is the readout directly receiving the input (False by default).

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.

output_node: Output | None = None#: Output node for the reservoir, if return_reservoir_activity is set to True

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

readout: TrainableNode#: A Ridge instance.

reservoir: Node#: A Reservoir or a NVAR instance.

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.

return_reservoir_activity: bool#: Are the reservoir states returned by the model along the readout output (False by default).

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

Echo State Network reservoirpy.ESN#

Echo State Network `reservoirpy.ESN`#