xgi.dynamics.synchronization#

Simulation of the Kuramoto model.

Functions

simulate_kuramoto(H, k2, k3, omega=None, theta=None, timesteps=10000, dt=0.002)[source]#

Simulates the Kuramoto model on hypergraphs. This solves the Kuramoto model ODE on hypergraphs with edges of sizes 2 and 3 using the Euler Method. It returns timeseries of the phases.

Parameters:

  • H (Hypergraph object) – The hypergraph on which you run the Kuramoto model

  • k2 (float) – The coupling strength for links

  • k3 (float) – The coupling strength for triangles

  • omega (numpy array of real values) – The natural frequency of the nodes. If None (default), randomly drawn from a normal distribution

  • theta (numpy array of real values) – The initial phase distribution of nodes. If None (default), drawn from a random uniform distribution on [0, 2pi[.

  • timesteps (int greater than 1, default: 10000) – The number of timesteps for Euler Method.

  • dt (float greater than 0, default: 0.002) – The size of timesteps for Euler Method.

Returns:

  • theta_time (numpy array of floats) – Timeseries of phases from the Kuramoto model, of dimension (T, N)

  • times (numpy array of floats) – Times corresponding to the simulate phases

References

“Synchronization of phase oscillators on complex hypergraphs” by Sabina Adhikari, Juan G. Restrepo and Per Sebastian Skardal https://doi.org/10.48550/arXiv.2208.00909

Examples

>>> import numpy as np
>>> import xgi
>>> n = 50
>>> H = xgi.random_hypergraph(n, [0.05, 0.001], seed=None)
>>> omega = 2*np.ones(n)
>>> theta = np.linspace(0, 2*np.pi, n)
>>> theta_time, times = simulate_kuramoto(H, k2=2, k3=3, omega=omega, theta=theta)
compute_kuramoto_order_parameter(theta_time)[source]#

Calculate the order parameter for the Kuramoto model on hypergraphs.

Calculation proceeds from time series, and the output is a measure of synchrony.

Parameters:

theta_time (numpy array of floats) – Timeseries of phases from the Kuramoto model, of dimension (T, N)

Returns:

r_time – Timeseries for Kuramoto model order parameter

Return type:

numpy array of floats

simulate_simplicial_kuramoto(S, orientations=None, order=1, omega=[], sigma=1, theta0=[], T=10, n_steps=10000, index=False)[source]#

Simulate the simplicial Kuramoto model’s dynamics on an oriented simplicial complex using explicit Euler numerical integration scheme.

Parameters:

  • S (simplicial complex object) – The simplicial complex on which you run the simplicial Kuramoto model

  • orientations (dict, Default : None) – Dictionary mapping non-singleton simplices IDs to their boolean orientation

  • order (integer) – The order of the oscillating simplices

  • omega (numpy.ndarray) – The simplicial oscillators’ natural frequencies, has dimension (n_simplices of given order, 1)

  • sigma (positive real value) – The coupling strength

  • theta0 (numpy.ndarray) – The initial phase distribution, has dimension (n_simplices of given order, 1)

  • T (positive real value) – The final simulation time.

  • n_steps (integer greater than 1) – The number of integration timesteps for the explicit Euler method.

  • index (bool, default: False) – Specifies whether to output dictionaries mapping the node and edge IDs to indices.

Returns:

  • theta (numpy.ndarray) – Timeseries of the simplicial oscillators’ phases, has dimension (n_simplices of given order, n_steps)

  • theta_minus (numpy array of floats) – Timeseries of the projection of the phases onto lower order simplices, has dimension (n_simplices of given order - 1, n_steps)

  • theta_plus (numpy array of floats) – Timeseries of the projection of the phases onto higher order simplices, has dimension (n_simplices of given order + 1, n_steps)

  • om1_dict (dict) – The dictionary mapping indices to (order-1)-simplices IDs, if index is True

  • o_dict (dict) – The dictionary mapping indices to (order)-simplices IDs, if index is True

  • op1_dict (dict) – The dictionary mapping indices to (order+1)-simplices IDs, if index is True

References

“Explosive Higher-Order Kuramoto Dynamics on Simplicial Complexes” by Ana P. Millán, Joaquín J. Torres, and Ginestra Bianconi https://doi.org/10.1103/PhysRevLett.124.218301

compute_simplicial_order_parameter(theta_minus, theta_plus)[source]#

This function computes the simplicial order parameter of a simplicial Kuramoto dynamics simulation.

Parameters:

  • theta_minus (numpy.ndarray) – Timeseries of the projection of the phases onto lower order simplices, has dimension (n_simplices of given order - 1, n_steps)

  • theta_plus (numpy.ndarray) – Timeseries of the projection of the phases onto higher order simplices, has dimension (n_simplices of given order + 1, n_steps)

Returns:

R – Timeseries of the simplicial order parameter, has dimension (1, n_steps)

Return type:

numpy.ndarray

References

“Connecting Hodge and Sakaguchi-Kuramoto through a mathematical framework for coupled oscillators on simplicial complexes” by Alexis Arnaudon, Robert L. Peach, Giovanni Petri, and Paul Expert https://doi.org/10.1038/s42005-022-00963-7