AbstractCoupling

experimental.network_dynamics.coupling.AbstractCoupling(
    incoming_states=None,
    local_states=None,
    **kwargs,
)

Ultra-minimal interface for completely custom coupling implementations.

Use this base class only when you need full control over coupling computation and the standard matrix multiplication patterns don’t apply (e.g., SubspaceCoupling).

Attributes: N_OUTPUT_STATES: Number of output states after coupling DEFAULT_PARAMS: Default coupling parameters as a Bunch

Methods

Name	Description
compute	Compute coupling input during simulation.
prepare	Prepare coupling for simulation.
update_state	Update coupling internal state after integration step.

compute

experimental.network_dynamics.coupling.AbstractCoupling.compute(
    t,
    state,
    coupling_data,
    coupling_state,
    params,
    graph,
)

Compute coupling input during simulation.

Replaces the coupling_fun built by networks. Handles all coupling computation including delays, matrix multiplication, pre/post transforms.

Args: t: Current simulation time state: Current network state [n_states, n_nodes] coupling_data: Precomputed static data (indices, etc.) coupling_state: Mutable internal state (history buffers, etc.) params: Coupling parameters (G, a, b, etc.) graph: Network graph for accessing weights/delays

Returns: Coupling input [n_coupling_inputs, n_nodes]

prepare

experimental.network_dynamics.coupling.AbstractCoupling.prepare(
    network,
    dt,
    t0,
    t1,
)

Prepare coupling for simulation.

Handles all setup logic that was previously in solve.py: - State index computation - History buffer initialization (for delays) - Parameter validation

Args: network: Network instance with graph, dynamics, initial_state dt: Integration timestep t0: Simulation start time t1: Simulation end time

Returns: Tuple of (coupling_data, coupling_state):

coupling_data: Bunch
    Static precomputed data (stored outside scan carry):
    - incoming_indices: State indices to read from
    - local_indices: Local state indices
    - delay_indices: Delay step indices (for delayed coupling)
    - Other static precomputed data
    NOTE: Does NOT contain weights/delays - access via graph parameter

coupling_state: Bunch
    Mutable internal state (stored in scan carry):
    - history: Circular buffer for delays (if applicable)
    - [empty Bunch() for instantaneous coupling]

update_state

experimental.network_dynamics.coupling.AbstractCoupling.update_state(
    coupling_data,
    coupling_state,
    new_state,
)

Update coupling internal state after integration step.

Handles state-dependent updates like history buffer management.

Args: coupling_data: Precomputed arrays (for reference) coupling_state: Current internal state new_state: New network state after integration [n_states, n_nodes]

Returns: Updated coupling_state as Bunch