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=None, edges=None, name=None)

Model base class.

Parameters:

• nodes (list of Node, optional) – Nodes to include in the Model.

• edges (list of (Node, Node), optional) – Edges between Nodes in the graph. An edge between a Node A and a Node B is created as a tuple (A, B).

• name (str, optional) – Name of the Model.

Methods

call(x[, forced_feedback, from_state, ...])	Call the Model forward function on a single step of data.
fit(X, Y[, warmup, force_teachers, ...])	Fit all offline Nodes in the Model using their offline learning rule.
get_node(name)	Get Node in Model, by name.
initialize([x, y])	Call the Model initializers on some data points.
initialize_buffers()	Call all Nodes buffer initializers.
reset([to_state])	Reset the last state saved to zero for all Nodes in the Model or to other state values.
run(X[, forced_feedbacks, from_state, ...])	Run the Model forward function on a sequence of data.
train(X[, Y, force_teachers, learn_every, ...])	Train all online Nodes in the Model using their online learning rule.
update_graph(new_nodes, new_edges)	Update current Model's with new nodes and edges, inplace (a copy is not performed).
with_feedback([feedback, stateful, reset])	Modify the feedback received or sent by Nodes in the Model using a context manager.
with_state([state, stateful, reset])	Modify the state of one or several Nodes in the Model using a context manager.

Attributes

data_dispatcher	DataDispatcher object of the Model.
edges	All edges between Nodes, in the form (sender, receiver).
feedback_nodes	Returns all Nodes equipped with a feedback connection in the Model.
fitted	Returns True if all nodes are fitted.
hypers	Hyperparameters of the Node or Model.
input_dim	Input dimension of the Model; input dimensions of all input Nodes.
input_nodes	First Nodes in the graph held by the Model.
is_empty	Returns True if the Model contains no Nodes.
is_initialized
is_trainable	Returns True if at least one Node in the Model is trainable.
is_trained_offline	Returns True if all nodes are offline learners.
is_trained_online	Returns True if all nodes are online learners.
name	Name of the Node or Model.
node_names	Names of all the Nodes in the Model.
nodes	Nodes in the Model, in topological order.
output_dim	Output dimension of the Model; output dimensions of all output Nodes.
output_nodes	Last Nodes in the graph held by the Model.
params	Parameters of the Node or Model.
trainable_nodes	Returns all offline and online trainable Nodes in the Model.

call(x, forced_feedback=None, from_state=None, stateful=True, reset=False, return_states=None)

Call the Model forward function on a single step of data. Model forward function is a composition of all its Nodes forward functions.

Can update the state its Nodes.

Parameters:

• x (dict or array-like of shape ([n_inputs], 1, input_dim)) – One single step of input data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are single steps of input data.

• forced_feedback (dict of arrays of shape ([n_feedbacks], 1, feedback_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are feedback vectors to force into the nodes.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

An output vector or pairs of keys and values where keys are output nodes names and values are corresponding output vectors.

Return type:

dict or array-like of shape ([n_outputs], 1, output_dim)

property data_dispatcher

DataDispatcher object of the Model. Used to distribute data to Nodes when calling/running/fitting the Model.

property edges

All edges between Nodes, in the form (sender, receiver).

property feedback_nodes

Returns all Nodes equipped with a feedback connection in the Model.

fit(X, Y, warmup=0, force_teachers=True, from_state=None, stateful=True, reset=False)

Fit all offline Nodes in the Model using their offline learning rule.

Parameters:

• X (dict or array-like of shape ([n_inputs], [series], timesteps, input_dim)) – Input sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• Y (dict or array-like of shape ([offlines], [series], timesteps, offlines.output_dim)) – Target sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of target data.

• warmup (int, default to 0) – Number of timesteps to consider as warmup and discard at the beginning of each timeseries before training.

• force_teachers (bool, default to True) – If True, this Model will broadcast the available ground truth signal to all online nodes sending feedback to other nodes. Otherwise, the real state of these nodes will be sent to the feedback receivers during training.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

Returns:

Model trained offline.

Return type:

Model

property fitted

Returns True if all nodes are fitted.

get_node(name)

Get Node in Model, by name.

Parameters:

name (str) – Node name.

Returns:

The requested Node.

Return type:

Node

Raises:

KeyError – Node not found.

property hypers

Hyperparameters of the Node or Model.

initialize(x=None, y=None)

Call the Model initializers on some data points. Model will be virtually run to infer shapes of all nodes given inputs and targets vectors.

Parameters:

• x (dict or array-like of shape ([n_inputs], 1, input_dim)) – Input data.

• y (dict or array-like of shape ([n_outputs], 1, output_dim)) – Ground truth data. Used to infer output dimension of trainable nodes.

Returns:

Initialized Model.

Return type:

Model

initialize_buffers()

Call all Nodes buffer initializers. Buffer initializers will create buffer arrays on demand to store transient values of the parameters, typically during training.

Returns:

Initialized Model.

Return type:

Model

property input_dim

Input dimension of the Model; input dimensions of all input Nodes.

property input_nodes

First Nodes in the graph held by the Model.

property is_empty

Returns True if the Model contains no Nodes.

property is_trainable

Returns True if at least one Node in the Model is trainable.

property is_trained_offline

Returns True if all nodes are offline learners.

property is_trained_online

Returns True if all nodes are online learners.

property name

Name of the Node or Model.

property node_names

Names of all the Nodes in the Model.

property nodes

Nodes in the Model, in topological order.

property output_dim

Output dimension of the Model; output dimensions of all output Nodes.

property output_nodes

Last Nodes in the graph held by the Model.

property params

Parameters of the Node or Model.

reset(to_state=None)

Reset the last state saved to zero for all Nodes in the Model or to other state values.

Parameters:

to_state (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

run(X, forced_feedbacks=None, from_state=None, stateful=True, reset=False, shift_fb=True, return_states=None)

Run the Model forward function on a sequence of data. Model forward function is a composition of all its Nodes forward functions. Can update the state of the Nodes several times.

Parameters:

• X (dict or array-like of shape ([n_inputs], timesteps, input_dim)) – A sequence of input data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• forced_feedbacks (dict of array-like of shape ([n_feedbacks], timesteps, feedback_dim)) – Pairs of keys and values, where keys are Model nodes names and value are sequences of feedback vectors to force into the nodes.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• shift_fb (bool, defaults to True) – If True, then forced feedbacks are fed to nodes with a one timestep delay. If forced feedbacks are a sequence of target vectors matching the sequence of input vectors, then this parameter should be set to True.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

A sequence of output vectors or pairs of keys and values where keys are output nodes names and values are corresponding sequences of output vectors.

Return type:

dict or array-like of shape ([n_outputs], timesteps, output_dim)

train(X, Y=None, force_teachers=True, learn_every=1, from_state=None, stateful=True, reset=False, return_states=None)

Train all online Nodes in the Model using their online learning rule.

Parameters:

• X (dict or array-like of shape ([n_inputs], timesteps, input_dim)) – Input sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• Y (dict or array-like of shape ([onlines], timesteps, onlines.output_dim), optional.) – Target sequence of data. If dict, then pairs of keys and values, where keys are Model online trainable nodes names values are sequences of target data. If None, the Nodes will search a feedback signal, or train in an unsupervised way, if possible.

• force_teachers (bool, default to True) – If True, this Model will broadcast the available ground truth signal to all online nodes sending feedback to other nodes. Otherwise, the real state of these nodes will be sent to the feedback receivers during training.

• learn_every (int, default to 1) – Time interval at which training must occur, when dealing with a sequence of input data. By default, the training method is called every time the Model receive an input.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

All outputs computed during the training or pairs of keys and values where keys are output nodes names and values are corresponding outputs computed. If call is False, outputs will be null vectors.

Return type:

dict or array-like of shape ([n_outputs], timesteps, output_dim)

property trainable_nodes

Returns all offline and online trainable Nodes in the Model.

update_graph(new_nodes, new_edges)

Update current Model’s with new nodes and edges, inplace (a copy is not performed).

Parameters:

• new_nodes (list of Node) – New nodes.

• new_edges (list of (Node, Node)) – New edges between nodes.

Returns:

The updated Model.

Return type:

Model

with_feedback(feedback=None, stateful=False, reset=False)

Modify the feedback received or sent by Nodes in the Model using a context manager. The modification will have effect only within the context defined, before the feedbacks return to their previous states.

If the Nodes are receiving feedback, then this function will alter the states of the Nodes connected to it through feedback connections.

If the Nodes are sending feedback, then this function will alter the states (or state proxies, see Node.state_proxy()) of the Nodes.

Parameters:

• feedback (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray feedback vectors.

• stateful (bool, default to False) – If set to True, then all modifications made in the context manager will remain after leaving the context.

• reset (bool, default to False) – If True, all feedbacks will be reset to zero.

Returns:

Modified Model.

Return type:

Model

with_state(state=None, stateful=False, reset=False)

Modify the state of one or several Nodes in the Model using a context manager. The modification will have effect only within the context defined, before all states return to their previous value.

Parameters:

• state (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to False) – If set to True, then all modifications made in the context manager will remain after leaving the context.

• reset (bool, default to False) – If True, all Nodes will be reset using their Node.reset() method.

Returns:

Modified Model.

Return type:

Model

class reservoirpy.model.FrozenModel(*args, **kwargs)

A FrozenModel is a Model that can not be linked to other nodes or models.

call(x, forced_feedback=None, from_state=None, stateful=True, reset=False, return_states=None)

Call the Model forward function on a single step of data. Model forward function is a composition of all its Nodes forward functions.

Can update the state its Nodes.

Parameters:

• x (dict or array-like of shape ([n_inputs], 1, input_dim)) – One single step of input data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are single steps of input data.

• forced_feedback (dict of arrays of shape ([n_feedbacks], 1, feedback_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are feedback vectors to force into the nodes.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

An output vector or pairs of keys and values where keys are output nodes names and values are corresponding output vectors.

Return type:

dict or array-like of shape ([n_outputs], 1, output_dim)

property data_dispatcher

DataDispatcher object of the Model. Used to distribute data to Nodes when calling/running/fitting the Model.

property edges

All edges between Nodes, in the form (sender, receiver).

property feedback_nodes

Returns all Nodes equipped with a feedback connection in the Model.

fit(X, Y, warmup=0, force_teachers=True, from_state=None, stateful=True, reset=False)

Fit all offline Nodes in the Model using their offline learning rule.

Parameters:

• X (dict or array-like of shape ([n_inputs], [series], timesteps, input_dim)) – Input sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• Y (dict or array-like of shape ([offlines], [series], timesteps, offlines.output_dim)) – Target sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of target data.

• warmup (int, default to 0) – Number of timesteps to consider as warmup and discard at the beginning of each timeseries before training.

• force_teachers (bool, default to True) – If True, this Model will broadcast the available ground truth signal to all online nodes sending feedback to other nodes. Otherwise, the real state of these nodes will be sent to the feedback receivers during training.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

Returns:

Model trained offline.

Return type:

Model

property fitted

Returns True if all nodes are fitted.

get_node(name)

Get Node in Model, by name.

Parameters:

name (str) – Node name.

Returns:

The requested Node.

Return type:

Node

Raises:

KeyError – Node not found.

property hypers

Hyperparameters of the Node or Model.

initialize(x=None, y=None)

Call the Model initializers on some data points. Model will be virtually run to infer shapes of all nodes given inputs and targets vectors.

Parameters:

• x (dict or array-like of shape ([n_inputs], 1, input_dim)) – Input data.

• y (dict or array-like of shape ([n_outputs], 1, output_dim)) – Ground truth data. Used to infer output dimension of trainable nodes.

Returns:

Initialized Model.

Return type:

Model

initialize_buffers()

Call all Nodes buffer initializers. Buffer initializers will create buffer arrays on demand to store transient values of the parameters, typically during training.

Returns:

Initialized Model.

Return type:

Model

property input_dim

Input dimension of the Model; input dimensions of all input Nodes.

property input_nodes

First Nodes in the graph held by the Model.

property is_empty

Returns True if the Model contains no Nodes.

property is_trainable

Returns True if at least one Node in the Model is trainable.

property is_trained_offline

Returns True if all nodes are offline learners.

property is_trained_online

Returns True if all nodes are online learners.

property name

Name of the Node or Model.

property node_names

Names of all the Nodes in the Model.

property nodes

Nodes in the Model, in topological order.

property output_dim

Output dimension of the Model; output dimensions of all output Nodes.

property output_nodes

Last Nodes in the graph held by the Model.

property params

Parameters of the Node or Model.

reset(to_state=None)

Reset the last state saved to zero for all Nodes in the Model or to other state values.

Parameters:

to_state (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

run(X, forced_feedbacks=None, from_state=None, stateful=True, reset=False, shift_fb=True, return_states=None)

Run the Model forward function on a sequence of data. Model forward function is a composition of all its Nodes forward functions. Can update the state of the Nodes several times.

Parameters:

• X (dict or array-like of shape ([n_inputs], timesteps, input_dim)) – A sequence of input data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• forced_feedbacks (dict of array-like of shape ([n_feedbacks], timesteps, feedback_dim)) – Pairs of keys and values, where keys are Model nodes names and value are sequences of feedback vectors to force into the nodes.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• shift_fb (bool, defaults to True) – If True, then forced feedbacks are fed to nodes with a one timestep delay. If forced feedbacks are a sequence of target vectors matching the sequence of input vectors, then this parameter should be set to True.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

A sequence of output vectors or pairs of keys and values where keys are output nodes names and values are corresponding sequences of output vectors.

Return type:

dict or array-like of shape ([n_outputs], timesteps, output_dim)

train(X, Y=None, force_teachers=True, learn_every=1, from_state=None, stateful=True, reset=False, return_states=None)

Train all online Nodes in the Model using their online learning rule.

Parameters:

• X (dict or array-like of shape ([n_inputs], timesteps, input_dim)) – Input sequence of data. If dict, then pairs of keys and values, where keys are Model input nodes names and values are sequence of input data.

• Y (dict or array-like of shape ([onlines], timesteps, onlines.output_dim), optional.) – Target sequence of data. If dict, then pairs of keys and values, where keys are Model online trainable nodes names values are sequences of target data. If None, the Nodes will search a feedback signal, or train in an unsupervised way, if possible.

• force_teachers (bool, default to True) – If True, this Model will broadcast the available ground truth signal to all online nodes sending feedback to other nodes. Otherwise, the real state of these nodes will be sent to the feedback receivers during training.

• learn_every (int, default to 1) – Time interval at which training must occur, when dealing with a sequence of input data. By default, the training method is called every time the Model receive an input.

• from_state (dict of arrays of shape ([nodes], 1, nodes.output_dim)) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to True) – If True, Node state will be updated by this operation.

• reset (bool, default to False) – If True, Nodes states will be reset to zero before this operation.

• return_states (list of str, optional) – Names of Nodes from which to return states as output.

Returns:

All outputs computed during the training or pairs of keys and values where keys are output nodes names and values are corresponding outputs computed. If call is False, outputs will be null vectors.

Return type:

dict or array-like of shape ([n_outputs], timesteps, output_dim)

property trainable_nodes

Returns all offline and online trainable Nodes in the Model.

update_graph(new_nodes, new_edges)

Update current Model’s with new nodes and edges, inplace (a copy is not performed).

Parameters:

• new_nodes (list of Node) – New nodes.

• new_edges (list of (Node, Node)) – New edges between nodes.

Returns:

The updated Model.

Return type:

Model

with_feedback(feedback=None, stateful=False, reset=False)

Modify the feedback received or sent by Nodes in the Model using a context manager. The modification will have effect only within the context defined, before the feedbacks return to their previous states.

If the Nodes are receiving feedback, then this function will alter the states of the Nodes connected to it through feedback connections.

If the Nodes are sending feedback, then this function will alter the states (or state proxies, see Node.state_proxy()) of the Nodes.

Parameters:

• feedback (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray feedback vectors.

• stateful (bool, default to False) – If set to True, then all modifications made in the context manager will remain after leaving the context.

• reset (bool, default to False) – If True, all feedbacks will be reset to zero.

Returns:

Modified Model.

Return type:

Model

with_state(state=None, stateful=False, reset=False)

Modify the state of one or several Nodes in the Model using a context manager. The modification will have effect only within the context defined, before all states return to their previous value.

Parameters:

• state (dict of arrays of shape (1, output_dim), optional) – Pairs of keys and values, where keys are Model nodes names and value are new ndarray state vectors.

• stateful (bool, default to False) – If set to True, then all modifications made in the context manager will remain after leaving the context.

• reset (bool, default to False) – If True, all Nodes will be reset using their Node.reset() method.

Returns:

Modified Model.

Return type:

Model