🌊 Dynamics¶
Submodules¶
hypergraphx.dynamics.contagion module¶
- hypergraphx.dynamics.contagion.simplicial_contagion(hypergraph, I_0, T, beta, beta_D, mu, *, seed=None, rng=None)[source]¶
Simulates the contagion process on a simplicial hypergraph. The process is run for T time steps. The initial condition is given by I_0, which is a dictionary where the keys are the nodes and the values are 1 if the node is infected and 0 otherwise. The infection rate is beta, the three-body infection rate is beta_D, and the recovery rate is mu. The output is a vector of length T, where the i-th entry is the fraction of infected nodes at time i.
- Parameters:
hypergraph (hypergraphx.Hypergraph) – The hypergraph on which the contagion process is run.
I_0 (dictionary) – The initial condition of the contagion process.
T (int) – The number of time steps.
beta (float) – The infection rate.
beta_D (float) – The three-body infection rate.
mu (float) – The recovery rate.
seed (int, optional (keyword-only)) – Seed for reproducibility. Ignored if rng is provided.
rng (numpy.random.Generator, optional (keyword-only)) – Random number generator to use. If provided, makes the simulation reproducible without touching global RNG state.
- Returns:
The fraction of infected nodes at each time step.
- Return type:
numpy.ndarray
hypergraphx.dynamics.randwalk module¶
- hypergraphx.dynamics.randwalk.RW_stationary_state(HG, *, tol=1e-12, max_iter=10000)[source]¶
Compute the stationary state of the random walk on the hypergraph.
- Parameters:
HG (Hypergraph) – The hypergraph on which the random walk is defined.
- Returns:
stationary_state – The stationary state of the random walk on the hypergraph.
- Return type:
np.ndarray
- hypergraphx.dynamics.randwalk.random_walk(HG, s, time, *, seed=None, rng=None)[source]¶
Compute the random walk on the hypergraph.
- Parameters:
HG (Hypergraph) – The hypergraph on which the random walk is defined.
s (int) – The starting node of the random walk.
time (int) – The number of steps of the random walk.
seed (int, optional (keyword-only)) – Seed for reproducibility (does not touch global RNG state).
rng (numpy.random.Generator, optional (keyword-only)) – Random number generator to use. If provided, seed must be None.
- Returns:
nodes – The list of nodes visited by the random walk.
- Return type:
list
- hypergraphx.dynamics.randwalk.random_walk_density(HG, s, time)[source]¶
Compute the random walk on the hypergraph with starting density vector.
- Parameters:
HG (Hypergraph) – The hypergraph on which the random walk is defined.
s (np.ndarray) – The starting density vector of the random walk.
- Returns:
nodes – The list of density vectors over time.
- Return type:
list
- hypergraphx.dynamics.randwalk.transition_matrix(HG)[source]¶
Compute the transition matrix of the random walk on the hypergraph.
- Parameters:
HG (Hypergraph) – The hypergraph on which the random walk is defined.
- Returns:
K (np.ndarray)
The transition matrix of the random walk on the hypergraph.
References
[1] Timoteo Carletti, Federico Battiston, Giulia Cencetti, and Duccio Fanelli, Random walks on hypergraphs, Phys. Rev. E 96, 012308 (2017)
hypergraphx.dynamics.synch module¶
- hypergraphx.dynamics.synch.MSF(F, JF, params, interval, JH, X0, integration_time=2000.0, integration_step=0.01, C=5, verbose=True, *, seed=None, rng=None)[source]¶
Evaluates the Master Stability Function
- Parameters:
F (function determining the dynamics of the isolated system.) – It is a collable as requested by scipy.solve_ivp
JF (Jacobian matrix of the function f.) – It is a callable that returns the value of the Jacobian at a given point.
params (parameters of function f.) – It is a tuple of parameters used by the function F.
interval (the interval of values over which the MSF is computed.) – It is a list-like object containing the values of alpha at which evaluating the MSF.
JH (Jacobian matrix of the coupling function.) – It is a callable that returns the value of the Jacobian at a given point.
X0 (initial condition of the isolated system.) – It is a list-like object containg the initial conditions.
integration_time (time over which the system is integrated.)
integration_step (step of the integrating function.)
C (number of cycles of the Sprott's algorithm.)
- Returns:
MSF
- Return type:
MSF evaluated over the interval of values selected.
- hypergraphx.dynamics.synch.MSF_multi_coupling(F, JF, params, interval, sigmas, N, JHs, X0, integration_time=2000.0, integration_step=0.01, C=5, verbose=True, *, seed=None, rng=None)[source]¶
Evaluates the Master Stability Function for the higher-order all-to-all network
- Parameters:
F (function determining the dynamics of the isolated system.) – It is a collable as requested by scipy.solve_ivp
JF (Jacobian matrix of the function f.) – It is a callable that returns the value of the Jacobian at a given point.
params (parameters of function f.) – It is a tuple of parameters used by the function F.
interval (the interval of values over which the MSF is computed.) – It is a list-like object containing the values of alpha at which evaluating the MSF.
sigmas (coupling strengths.) – It is a list-like object.
N (number of nodes.)
JH (Jacobian matrix of the coupling function.) – It is a callable that returns the value of the Jacobian at a given point.
X0 (initial condition of the isolated system.) – It is a list-like object containg the initial conditions.
integration_time (time over which the system is integrated.)
integration_step (step of the integrating function.)
C (number of cycles of the Sprott's algorithm.)
- Returns:
MSF
- Return type:
MSF evaluated over the interval of values selected.
hypergraphx.dynamics.utils module¶
- hypergraphx.dynamics.utils.is_natural_coupling(JHs, dim, verbose=True, *, seed=None, rng=None)[source]¶
- hypergraphx.dynamics.utils.sprott_algorithm(alpha, C, F, JF, JH, Y0, params, integration_time=400.0, integration_step=0.01, verbose=True)[source]¶
Evaluates the Master Stability Function as the maximum Lyapunov exponent using the Sprott’s algorithm [1]
- Parameters:
alpha (value for which the MSF is computed.)
C (number of cycles of the algorithm.)
F (function determining the dynamics of the isolated system.) – It is a callable as requested by scipy.solve_ivp
JF (Jacobian matrix of the function f.) – It is a callable that returns the value of the Jacobian at a given point.
JH (Jacobian matrix of the coupling function.) – It is a callable that returns the value of the Jacobian at a given point.
Y0 (initial condition of the isolated system, and initial perturbation.) – It is a list-like object.
params (parameters of function f.) – It is a tuple of parameters used by the function F.
integration_time (time over which the system is integrated in each cycle.)
integration_step (step of the integrating function.)
- Returns:
interval – interval of values over which the MSF is computed.
MSF – MSF evaluated over the interval of values selected.
References
[1] J.C. Sprott, Chaos and Time-Series Analysis, Oxford University Press vol.69, pp.116-117 (2003).
- hypergraphx.dynamics.utils.sprott_algorithm_multi(alpha, C, F, JF, sigmas, N, JHs, Y0, params, all2all=True, integration_time=400.0, integration_step=0.01, verbose=True)[source]¶
Evaluates the Master Stability Function as the maximum Lyapunov exponent using the Sprott’s algorithm [1]
- Parameters:
alpha (value for which the MSF is computed.)
C (number of cycles of the algorithm.)
F (function determining the dynamics of the isolated system.) – It is a callable as requested by scipy.solve_ivp
JF (Jacobian matrix of the function f.) – It is a callable that returns the value of the Jacobian at a given point.
JHs (Jacobian matrices of the coupling functions.) – It is a list of callables that return the value of the Jacobians at a given point.
Y0 (initial condition of the isolated system, and initial perturbation.) – It is a list-like object.
params (parameters of function f.) – It is a tuple of parameters used by the function F.
integration_time (time over which the system is integrated in each cycle.)
integration_step (step of the integrating function.)
- Returns:
interval (interval of values over which the MSF is computed.)
MSF (MSF evaluated over the interval of values selected.)
Reference
———
[1] J.C. Sprott, Chaos and Time-Series Analysis, Oxford University Press vol.69, pp.116-117 (2003).
Module contents¶
Dynamical processes on hypergraphs.
This package intentionally provides lightweight, lazy entrypoints for the most used processes to improve discoverability without imposing import-time cost.