brainmass.Network

class brainmass.Network(*args, **kwargs)

Wire a node model into a delay-coupled whole-brain network.

The network reads a single node (a Dynamics sized for N regions) and couples its regions through a structural-connectivity matrix, optionally with distance-dependent conduction delays. update computes the coupling current and feeds it back as the node’s first positional input – the same current = coupling(); node(current) idiom hand-written in the examples.

nodebrainstate.nn.Dynamics

The per-region dynamics, already sized for N regions (node.varshape[0] == N) and carrying any per-region noise. Exposed afterwards as node; its states are reachable as network.node.<coupled_var>.

connarray_like or brainstate.nn.Param

Structural connectivity. A plain (N, N) (or flattened (N * N,)) array has its diagonal zeroed unless self_connection is True; a Param / LaplacianConnParam is passed through untouched (the caller owns its structure) and may be trained.

distancearray_like, optional

Inter-region distance matrix (N, N). Combined with speed into conduction delays distance / speed. If either distance or speed is None the coupling is instantaneous (zero delays).

speedfloat or brainunit.Quantity, optional

Conduction speed. If distance carries length units and speed carries length / time units the delay is unit-correct; if both are plain numbers the quotient is interpreted as milliseconds (matching the examples).

coupling : {‘diffusive’, ‘additive’, ‘laplacian’, ‘sigmoidal’, ‘tanh’,

‘sigmoidal_jansen_rit’}, default ‘diffusive’

Coupling kernel. 'diffusive' uses DiffusiveCoupling (k * sum_j conn_ij (x_j - x_i)); 'additive' uses AdditiveCoupling (k * sum_j conn_ij x_j); 'laplacian' wraps conn in a LaplacianConnParam and applies it additively. The nonlinear forms 'sigmoidal' (SigmoidalCoupling), 'tanh' (HyperbolicTangentCoupling) and 'sigmoidal_jansen_rit' (SigmoidalJansenRitCoupling) apply their nonlinearity to the same delayed source read, with k as the global strength (TVB G; G ≡ k).

coupled_varstr

Name of the node state variable to couple (e.g. 'rE', 'x', 'V'). Validated at initialisation; an unknown name raises ValueError.

kfloat, brainunit.Quantity or brainstate.nn.Param, default 1.0

Global coupling strength. Pass a trainable Param to fit it.

delay_initCallable, default braintools.init.Uniform(0., 0.05)

Initializer for the delay buffer’s history.

self_connectionbool, default False

If False (default), the connectivity diagonal is zeroed (no self-coupling). Only applies to plain-array conn.

noisebrainstate.nn.Module, optional

Optional network-level noise process (e.g. an OUProcess sized for N). Its output is added to the coupling current each step.

brainmass.Simulator : drives the network and collects trajectories. brainmass.DiffusiveCoupling : the underlying diffusive coupling kernel.

The delay-buffer shape (max_delay_steps, N) does not depend on whether the (delay, index) pair is supplied flattened (as in examples/100) or as (N, N) matrices (as here), so a seeded run reproduces the hand-wired examples bit-for-bit. The self-delay (delay-matrix diagonal) is always zeroed.

A four-region Hopf network driven by the simulator:

>>> import brainmass
>>> import brainunit as u
>>> import numpy as np
>>> N = 4
>>> conn = np.ones((N, N)) * 0.1
>>> node = brainmass.HopfStep(N, a=0.1)
>>> net = brainmass.Network(node, conn=conn, coupled_var='x', k=0.5)
>>> sim = brainmass.Simulator(net, dt=0.1 * u.ms)
>>> res = sim.run(5.0 * u.ms, monitors=lambda m: m.node.x.value)
>>> res['output'].shape
(50, 4)

Return type:

Any

__init__(node, *, conn, distance=None, speed=None, coupling='diffusive', coupled_var, k=1.0, delay_init=Uniform(low=0.0, high=0.05), self_connection=False, noise=None)

Methods

__init__(node, *, conn[, distance, speed, ...])
check_valid_context(error_msg)	Raise TraceContextError if the node's trace context is invalid.
children()	Return immediate child modules.
desc(*args, **kwargs)	Create a parameter describer for this class.
init_all_states(*args[, state_tag])
init_state(*args, **kwargs)	Validate coupled_var once the node's states exist.
modules([include_self])	Return all modules in the network.
named_children()	Return an iterator over immediate child modules, yielding name and module.
named_modules([prefix, include_self])	Return an iterator over all modules in the network, yielding name and module.
named_param_modules([allowed_hierarchy])	Iterate over (name, parameter) pairs.
named_parameters([prefix, recurse])	Return an iterator over module parameters, yielding name and parameter.
nodes(*filters[, allowed_hierarchy])	Collect all children nodes.
param_modules([allowed_hierarchy])	Collect all Param parameters in this module and children.
param_precompute([allowed_hierarchy])	Context manager to temporarily cache all Param parameters.
parameters([recurse])	Return module parameters.
reg_loss()	Compute total regularization loss from all Param parameters.
reset_state(*args, **kwargs)	State resetting function.
state_trees(*filters)	Collect all states in this node and the children nodes.
states(*filters[, allowed_hierarchy])	Collect all states in this node and the children nodes.
update(*node_inputs)	Advance one step: coupling current (+ noise) -> node.

Attributes

graph_invisible_attrs
in_size
name	Name of the model.
non_hashable_params
out_size

__init__(node, *, conn, distance=None, speed=None, coupling='diffusive', coupled_var, k=1.0, delay_init=Uniform(low=0.0, high=0.05), self_connection=False, noise=None)

init_state(*args, **kwargs)

Validate coupled_var once the node’s states exist.

update(*node_inputs)

Advance one step: coupling current (+ noise) -> node.

Parameters:

*node_inputs – Extra inputs forwarded to the node after the coupling current (e.g. a second drive supplied by brainmass.Simulator.run()). The coupling current is always the node’s first positional input.

Returns:

The node’s update return value.

Return type:

Any