brainmass.additive_coupling

brainmass.additive_coupling#

brainmass.additive_coupling(delayed_x, conn, k=1.0, b=0.0)#

Additive (linear) coupling kernel (function form).

Computes, for each target unit i over the last axis, the additive term

current_i = k * sum_j conn[i, j] * x_{i, j} + b

with full support for leading batch/time dimensions and unit-safe algebra. This is TVB’s Linear coupling; the global coupling strength k is TVB’s G (G ≡ k) and b is its offset/bias.

Parameters:

  • delayed_x (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Zero-arg callable returning the source signal with shape (..., N_out, N_in) or flattened (..., N_out*N_in). Typically a Prefetch.

  • conn (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Connection weights with shape (N_out, N_in).

  • k (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Global coupling strength (TVB G). Scalar or broadcastable to (..., N_out).

  • b (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Additive offset/bias, added after the weighted sum. The default 0.0 is the additive identity, so it reproduces the bias-free coupling bit-for-bit (and, by brainunit’s convention, does not disturb a unit-carrying output). A non-zero b should carry the same units as k * sum_j conn x.

Returns:

Coupling output with shape (..., N_out). Units are preserved when inputs are Quantity.

Return type:

ArrayLike

Raises:

ValueError – If shapes are incompatible with the expected conventions.

Examples

>>> import brainmass
>>> import jax.numpy as jnp
>>> conn = jnp.ones((2, 2))
>>> x = jnp.array([[1.0, 2.0], [3.0, 4.0]])
>>> out = brainmass.additive_coupling(x, conn, k=1.0, b=0.5)
>>> [float(v) for v in out]
[3.5, 7.5]