braintools.analysis.population.kuramoto_order_parameter

braintools.analysis.population.kuramoto_order_parameter#

braintools.analysis.population.kuramoto_order_parameter(phases, axis=-1, return_phase=False)#

Compute the Kuramoto order parameter of a population of oscillators.

The complex order parameter is the mean phasor of the oscillators,

\[R\, e^{i\psi} = \frac{1}{N} \sum_{k=1}^{N} e^{i\theta_k},\]

computed along axis (the oscillator axis) [1]. \(R \in [0, 1]\) is 1 for perfectly phase-locked oscillators and close to 0 for incoherent ones.

Parameters:

  • phases (Any) – Phases in radians, for example (T, N) for N oscillators over T time steps. A Quantity must be dimensionless (radians or degrees; degrees are converted to radians).

  • axis (int) – Axis of the oscillators, which is averaged out.

  • return_phase (bool) – If True, also return the mean phase \(\psi\).

Returns:

  • R (jax.Array) – Order parameter, phases with axis removed ((T,) for (T, N) input).

  • psi (jax.Array) – Mean phase in (-pi, pi], same shape as R. Only returned when return_phase=True.

Raises:

TypeError – If phases is a Quantity with a physical dimension.

See also

braintools.analysis.spectral.analytic_signal

Instantaneous phases of continuous signals.

braintools.analysis.spectral.plv

Phase locking between two signals.

Notes

Works under jax.jit and jax.vmap and is differentiable with respect to phases wherever \(R > 0\).

References

Examples

>>> import jax.numpy as jnp
>>> from braintools.analysis.population import kuramoto_order_parameter
>>> phases = jnp.array([[0.1, 0.1, 0.1],
...                     [0.0, 2 * jnp.pi / 3, 4 * jnp.pi / 3]])
>>> R = kuramoto_order_parameter(phases)
>>> [round(float(r), 4) for r in R]
[1.0, 0.0]
>>>
>>> R, psi = kuramoto_order_parameter(phases, return_phase=True)
>>> round(float(psi[0]), 4)
0.1