reservoirpy.nodes.Reservoir#

class reservoirpy.nodes.Reservoir( units: int | None = None, lr: float | ~numpy.ndarray = 1.0, sr: float = 1.0, input_scaling: float | ~typing.Sequence = 1.0, input_connectivity: float = 0.1, rc_connectivity: float = 0.1, Win: ~numpy.ndarray | ~scipy.sparse._base.sparray | ~typing.Callable = _bernoulli(), W: ~numpy.ndarray | ~scipy.sparse._base.sparray | ~typing.Callable = _normal(), bias: ~numpy.ndarray | ~scipy.sparse._base.sparray | ~typing.Callable | float = 0.0, activation: str | ~typing.Callable = <function tanh>, input_dim: int | None = None, dtype: type = <class 'numpy.float64'>, seed: int | ~numpy.random._generator.Generator | None = None, name: str | None = None, )[source]#

Pool of leaky-integrator neurons with random recurrent connexions.

Reservoir neurons states, gathered in a vector \(\mathbf{x}\), follow the update rule below:

\[\mathbf{x}[t+1] = (1 - \mathrm{lr}) * \mathbf{x}[t] + \mathrm{lr} * f(\mathbf{W}_{in} \cdot (\mathbf{u}[t+1]) + \mathbf{W} \cdot \mathbf{x}[t])\]

where:

\(\mathbf{x}\) is the output activation vector of the reservoir;
\(\mathbf{u}\) is the input timeseries;
\(f\) is the activation function.

Parameters:

units (int, optional) – Number of reservoir units. If None, the number of units will be inferred from the W matrix shape.
lr (float or array-like of shape (units,), default to 1.0) – Neurons leak rate. Must be in \([0, 1]\).
sr (float, optional) – Spectral radius of recurrent weight matrix.
input_scaling (float or array-like of shape (features,), default to 1.0.) – Input gain. An array of the same dimension as the inputs can be used to set up different input scaling for each feature.
input_connectivity (float, default to 0.1) – Connectivity of input neurons, i.e. ratio of input neurons connected to reservoir neurons. Must be in \(]0, 1]\).
rc_connectivity (float, default to 0.1) – Connectivity of recurrent weight matrix, i.e. ratio of reservoir neurons connected to other reservoir neurons, including themselves. Must be in \(]0, 1]\).
Win (callable or array-like of shape (units, features), default to bernoulli()) – Input weights matrix or initializer. If a callable (like a function) is used, then this function should accept any keywords parameters and at least two parameters that will be used to define the shape of the returned weight matrix.
W (callable or array-like of shape (units, units), default to normal()) – Recurrent weights matrix or initializer. If a callable (like a function) is used, then this function should accept any keywords parameters and at least two parameters that will be used to define the shape of the returned weight matrix.
bias (callable or array-like of shape (units, 1), default to bernoulli()) – Bias weights vector or initializer. If a callable (like a function) is used, then this function should accept any keywords parameters and at least two parameters that will be used to define the shape of the returned weight matrix.
activation (str or callable, default to tanh()) – Reservoir units activation function. - If a str, should be a activationsfunc function name. - If a callable, should be an element-wise operator on arrays.
input_dim (int, optional) – Input dimension. Can be inferred at first call.
dtype (Numpy dtype, default to np.float64) – Numerical type for node parameters.
seed (int or numpy.random.Generator, optional) – A random state seed, for noise generation.
name (str, optional) – Node name.

Note

If W, Win, bias or Wfb are initialized with an array-like matrix, then all initializers parameters such as spectral radius (sr) or input scaling (input_scaling) are ignored. See mat_gen for more information.

Example

>>> from reservoirpy.nodes import Reservoir
>>> reservoir = Reservoir(100, lr=0.2, sr=0.8) # a 100 neurons reservoir

Using the mackey_glass() timeseries:

>>> from reservoirpy.datasets import mackey_glass
>>> x = mackey_glass(200)
>>> states = reservoir.run(x)

../../_images/reservoirpy-nodes-Reservoir-1.png

Methods

`__init__`([units, lr, sr, input_scaling, ...])
`initialize`(x)	Define input and output dimensions, and instantiate variables.
`predict`([x, iters, workers])	Alias for `run()`
`reset`()	Reset all Node state
`run`([x, iters, workers])	Run the Node on a sequence of data.
`step`([x])	Call the Node function on a single step of data and update the state of the Node.

Attributes

`input_dim`	Expected dimension of the Node input.
`name`	Optional name of the Node.
`output_dim`	Expected dimension of the Node input.
`initialized`	True if the Node has been initialized
`state`	Current state of the Node.
`units`	Number of neuronal units in the reservoir.
`lr`	Leaking rate (1.0 by default) (\(\mathrm{lr}\)).
`sr`	Spectral radius of `W` (optional).
`input_scaling`	Input scaling (float or array) (1.0 by default).
`input_connectivity`	Connectivity (or density) of `Win` (0.1 by default).
`rc_connectivity`	Connectivity (or density) of `Wfb` (0.1 by default).
`Win`	Input weights matrix (\(\mathbf{W}_{in}\)).
`W`	Recurrent weights matrix (\(\mathbf{W}\)).
`bias`	Bias vector (\(\mathbf{b}\)).
`dtype`	Type of matrices elements.
`activation`	Activation of the reservoir units (tanh by default) (\(f\)).
`rng`	A random state generator.

W: ndarray | sparray | Callable#: Recurrent weights matrix (\(\mathbf{W}\)).

Win: ndarray | sparray | Callable#: Input weights matrix (\(\mathbf{W}_{in}\)).

activation: Callable#: Activation of the reservoir units (tanh by default) (\(f\)).

bias: ndarray | sparray | Callable | float#: Bias vector (\(\mathbf{b}\)).

dtype: type#: Type of matrices elements. By default, np.float64.

initialize( x: Array2D | Array3D | Sequence[Timeseries] | Array1D | None, )[source]#

Define input and output dimensions, and instantiate variables.

Only called once, before fitting or running the node.

Parameters:

x (array of shape (input_dim,) or (timestep, input_dim)) – Input data to the node.
y (None) – Training data to the node. As it is not a trainable node, y is expected to be None.

initialized: bool#: True if the Node has been initialized

input_connectivity: float#: Connectivity (or density) of Win (0.1 by default).

input_dim: int | None = None#: Expected dimension of the Node input. Can be None before initialization

input_scaling: float | Sequence#: Input scaling (float or array) (1.0 by default).

lr: float | ndarray#: Leaking rate (1.0 by default) (\(\mathrm{lr}\)).

name: str | None = None#: Optional name of the Node.

output_dim: int = None#: Expected dimension of the Node input. Can be None before initialization

Alias for run()

Run the Node on a sequence of data. Can update the state of the Node several times.

Parameters:

x (array-like of shape ([n_inputs,] timesteps, input_dim) or list of) – arrays of shape (timesteps, input_dim), optional A sequence of data of shape (timesteps, features).
iters (int, optional) – If x is None, a dimensionless timeseries of length iters is used instead.

Returns:

A sequence of output vectors.

Return type:

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

rc_connectivity: float#: Connectivity (or density) of Wfb (0.1 by default).

reset() → dict[str, ndarray][source]#

Reset all Node state

Returns:: dict[str, np.array]
Return type:: previous state of the Node.

rng: Generator#: A random state generator. Used for generating Win and W.

Run the Node on a sequence of data. Can update the state of the Node several times.

Parameters:

x (array-like of shape ([n_inputs,] timesteps, input_dim) or list of arrays of shape (timesteps, input_dim), optional) – A timeseries, array of shape (timesteps, features), or a sequence of timeseries. Input of the Node.
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.

Return type:

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

sr: float#: Spectral radius of W (optional).

state: dict[str, ndarray]#: Current state of the Node. Must have “out” as one of the keys.

step(x: array(d) | None = None)[source]#

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

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.
Return type:: array of shape (output_dim,)

units: int#: Number of neuronal units in the reservoir.