reservoirpy.nodes.ES2N#

class reservoirpy.nodes.ES2N( units: int | None = None, proximity: 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(), O: ~numpy.ndarray | ~scipy.sparse._base.sparray | ~typing.Callable = _orthogonal(), 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]#

Edge of Stability Echo State Network.

As first described in [1].

The Edge of Stability Echo State Network (\(ES^2N\)) model is similar to the reservoir equation, but adds an orthogonal transformation to the recurrent part of the equation.

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

\[\mathbf{x}[t+1] = (1 - \mathrm{\beta}) \mathbf{O} * \mathbf{x}[t] + \mathrm{\beta} * 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\) and \(g\) are activation functions.
\(\mathrm{\beta}\) is the proximity hyperparameter.
\(\mathbf{O}\) is a randomly generated orthogonal matrix.

Parameters:

units (int, optional) – Number of reservoir units. If None, the number of units will be inferred from the W matrix shape.
proximity (float or array-like of shape (units,), default to 1.0) – Proximity parameter. 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.
O (callable or array-like of shape (units, units), default to orthogonal()) – Orthogonal matrix. 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 ES2N, Ridge
>>> es2n = ES2N(100, proximity=0.2, sr=0.8) >> Ridge(ridge=1e-6)

Using the mackey_glass() timeseries:

>>> from reservoirpy.datasets import mackey_glass, to_forecasting
>>> x, y = to_forecasting(mackey_glass(200), forecast=10)
>>> states = es2n.fit(x, y)

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

References

Methods

`__init__`([units, proximity, sr, ...])
`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.
`proximity`	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}\)).
`O`	Orthogonal matrix (\(\mathbf{O}\)).
`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.

O: ndarray | sparray | Callable#: Orthogonal matrix (\(\mathbf{O}\)).

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).

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

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

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.