engine.network

Networks are graph representations of neuron ensembles connected by synapses.

class engine.network.Network(identifier: str = None, device: str = 'cpu', configuration: dict = None, roots: list[str] = None)

Generalized spiking neural network instance. Maintains and orchestrates the processing of multiple ensembles connected by synapses.

Networks may be constructed from a configuration dictionary (read from a YAML or defined programmatically) by applying build(). User may also initialize an empty network and apply add_ensembles() and add_synapses() to build the network graph directly. One or more root nodes may be specified in the YAML/dictionary or passed to the Network constructor.

Parameters:

identifier (str, optional) – String identifier for file I/O and visualization operations.
configuration (dict, optional) – Configuration dictionary containing model specification and simulation parameters. Used to construct the graph and initialize the root instance attributes if provided.
roots (list of str, optional) – List of one or more ensemble identifiers corresponding to root nodes, i.e. the starting point of each forward pass. Can be passed to the constructor, configured in a YAML (model/roots), or automatically detected by checking for nodes with in-degree=0 (the latter is a fallback strategy and does not override user configuration). In cases where multiple external data tensors are passed to forward() or fit(), they are routed to these ensembles (the i-th tensor to the i-th root by convention).
device (str) – Specifies a hardware device on which to process this object’s tensors, e.g. “cuda:0”. Must be a valid torch.device() string value. Defaults to “cpu”.

Note

Synapse objects know their source and destination ensemble references; they are 2D objects capable of connecting two ensembles in a unidirectional fashion with heterogeneous parameters. Lateral connections from an ensemble to itself are supported by design and warrant no special treatment.

On forward() calls, the nodes of the graph are traversed in breadth-first search (BFS) order. The ensemble referenced by the current node is processed first, followed by its outgoing synapses. If multiple source nodes exist, the networkX multi-source BFS implementation is used.

add_data_hook(data_dir: str, steps: int, *args: Component) → list

Attach a data accumulator forward hook to some or all network components.

Parameters:

data_dir (str) – Path to directory in which to save intermediate simulation output.
steps (int) – Total number of simulation steps in the experiment to be logged. Required for HDF5 sizing and chunk management.
args (Component, optional) – Components to attach data hooks to. If not provided, data will be logged for all components.

add_ensembles(*args: Neuron | dict | str)

Adds ensemble nodes to the network graph from paths to YAML, from pre-initialized engine.neuron.Neuron objects or children thereof (e.g., any Ensemble), or from configuration dictionaries. User may mix and match if necessary.

Raises:: TypeError – If user attempts to pass an argument that is not a string path, a dictionary, or an instance derived from neuron.Neuron.

Warning

The component identifier field is used to reference nodes and edge sources or destinations when constructing the network graph.

add_synapses(*args: Synapse | dict | str)

Adds synapse edges to the network graph from paths to YAML, from pre-initialized engine.synapse.Synapse objects or children thereof (e.g.,`STDPSynapse`), or from configuration dictionaries. User may mix and match if necessary.

Raises:: TypeError – If user attempts to pass an argument that is not a string path, a dictionary, or an instance derived from synapse.Synapse.

backward() → None

Processes a backward sweep for this network object.

This is not required for SNNs that learn with STDP and can be implemented by child classes that might require a backward pass.

forward(data: tensor) → dict

Processes current simulation step for this network object.

In this generic implementation, forward call order is determined by a BFS traversal starting from the edges fanning out of the root nodes. Every node is visited once; for each node, every outgoing synapse is forwarded. That way, we are guaranteed to forward any component exactly once on every simulation step.

Parameters:: data (torch.tensor) – External input to be processed by this generic network.
Returns:: Dictionary containing the loggable properties of this network’s ensembles and synapses in this simulation step.
Return type:: dict

Warning

Networks now support multiple root nodes and external input streams. In those cases, the graph is traversed layer-wise, using multi-source BFS.