KuramotoNetwork

class brainmass.KuramotoNetwork(in_size, omega=0.0, K=0.0, alpha=0.0, conn=None, normalize_by_n=True, exclude_self=True, noise_theta=None, init_theta=Uniform(low=0.0, high=6.283185307179586))

Kuramoto phase oscillator network (with optional phase lag).

Implements the (Sakaguchi–)Kuramoto model for a population of coupled phase oscillators with states \(\theta_i \in \mathbb{R}\) evolving as

\[\dot{\theta}_i = \omega_i + \frac{K}{\mathcal{N}} \sum_{j=1}^{N} w_{ij} \sin\bigl(\theta_j - \theta_i - \alpha\bigr) + I_i(t),\]

where \(\omega_i\) is the natural frequency, \(K\) is a global coupling strength, \(w_{ij}\) are (optional) connection weights, and \(\alpha\) is a phase lag. If no weight matrix is provided, the model defaults to all-to-all coupling with \(w_{ij}=1\) and (by default) normalization \(\mathcal{N} = N\).

Parameters:

• in_size (int | Sequence[int] | integer | Sequence[integer]) – Spatial shape for the oscillator array. For network coupling, the last dimension is treated as the node index \(N\).

• omega (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Natural frequency for each oscillator (dimensionless here; overall derivative has unit 1/ms due to division by u.ms). Broadcastable to in_size. Default is 0.0.

• K (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Global coupling strength (dimensionless). Broadcastable to in_size when used without explicit conn. Default is 0.0.

• alpha (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Phase lag \(\alpha\) (dimensionless, radians). Broadcastable to in_size. Default is 0.0.

• conn (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Connection weights \(w_{ij}\) with shape (N, N) or flattened (N*N,). If None (default), uses all-to-all unit weights.

• normalize_by_n (bool) – If True divides the coupling sum by \(N\). Default is True.

• exclude_self (bool) – If True excludes self-coupling terms (diagonal), which matters when alpha != 0. Default is True.

• noise_theta (Noise) – Additive noise process for the phase dynamics. If provided, its output is added to theta_inp each update. Default is None.

• init_theta (Callable) – Parameter for the phase state theta (dimensionless, radians). Default is braintools.init.Uniform(0.0, 2 * u.math.pi).

Return type:

Any

theta

Phase state with shape (batch?,) + in_size after init_state.

Type:

brainstate.HiddenState

Notes

• Time derivatives returned by dtheta() carry unit 1/ms to be consistent with explicit (exponential) Euler integration.

• If conn is provided, it broadcasts across any leading batch/time dimensions in theta. If absent, coupling is computed from the pairwise phase differences without an explicit matrix.

• This implementation does not wrap the phase to [0, 2\pi). If phase wrapping is required for downstream use or visualization, apply it externally.

References

• Kuramoto, Y. (1975). Self-entrainment of a population of coupled non-linear oscillators. In International Symposium on Mathematical Problems in Theoretical Physics.

• Sakaguchi, H., & Kuramoto, Y. (1986). A soluble active rotator model showing phase transitions via mutual entertainment. Progress of Theoretical Physics, 76(3), 576–581.

dtheta(theta, drive)

Phase dynamics right-hand side.

Parameters:

• theta (array-like) – Current phase (unused here since drive already encodes the dependence via _pairwise_coupling()).

• drive (array-like) – External drive combining coupling and user-provided input.

Returns:

Time derivative dtheta/dt with unit 1/ms.

Return type:

array-like

init_state(batch_size=None, **kwargs)

Initialize phase state theta.

Parameters:

batch_size (int or None, optional) – Optional leading batch dimension. If None, no batch dimension is used. Default is None.

update(theta_inp=None)

Advance the system by one time step.

Parameters:

theta_inp (array-like or scalar or None, optional) – External input to the phase dynamics. If None, treated as zero. If noise_theta is set, its output is added. Default is None.

Returns:

The updated phase theta with the same shape as the internal state.

Return type:

array-like

Notes

• Computes coupling from the current phases and performs an exponential-Euler step using brainstate.nn.exp_euler_step.

• No phase wrapping is applied.