Dynamics¶
Dynamics classes allow the user to run simulations over a network.
Base class¶

class
netrd.dynamics.
BaseDynamics
[source]¶ Base class for all dynamics processes.
The basic usage is as follows:
>>> ground_truth = nx.read_edgelist("ground_truth.txt") >>> dynamics_model = Dynamics() >>> synthetic_TS = dynamics_model.simulate(ground_truth, <some_params>) >>> # G = Reconstructor().fit(synthetic_TS)
This produces a numpy array of time series data.
Available dynamics¶
All of the following dynamics inherit from BaseDynamics
and have the
same general usage as above.
A sandpilelike branching process. 

IsingGlauber model. 

Kuramoto model of oscillators. 

LotkaVolterra dynamics of species abundance. 

SusceptibleInfectedSusceptible dynamical process. 

Ising modellike dynamics. 

Random walk dynamics. 

Voter dynamics. 
Reference¶

class
netrd.dynamics.
BaseDynamics
[source] Base class for all dynamics processes.
The basic usage is as follows:
>>> ground_truth = nx.read_edgelist("ground_truth.txt") >>> dynamics_model = Dynamics() >>> synthetic_TS = dynamics_model.simulate(ground_truth, <some_params>) >>> # G = Reconstructor().fit(synthetic_TS)
This produces a numpy array of time series data.

simulate
(G, L)[source]¶ Simulate dynamics on a ground truth network.
The results dictionary stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
the input (groundtruth) graph with \(N\) nodes.
 L (int)
the length of the desired time series.
 Returns:
 TS (np.ndarray)
an :math`N times L` array of synthetic time series data.


class
netrd.dynamics.
SherringtonKirkpatrickIsing
[source]¶ Ising modellike dynamics.

simulate
(G, L, noisy=False)[source]¶ Simulate Kinetic Ising model dynamics on a ground truth network.
The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
The input (groundtruth) graph with \(N\) nodes.
 L (int)
The length of the desired time series.
 Returns:
 TS (np.ndarray)
An \(N \times L\) array of synthetic time series data.
References
[1]D. Sherrington and S. Kirkpatrick, Phys. Rev. Lett. 35, 1792 (1975).
[2]Hoang, D.T., Song, J., Periwal, V. and Jo, J., Network inference in stochastic systems from neurons to currencies: Improved performance at small sample size. (2019)
Examples
G = nx.ring_of_cliques(4,16) L = 2001 dynamics = SherringtonKirkpatrickIsing() TS = dynamics.simulate(G, L)


class
netrd.dynamics.
SingleUnbiasedRandomWalker
[source]¶ Random walk dynamics.

simulate
(G, L, initial_node=None)[source]¶ Simulate single randomwalker dynamics on a ground truth network.
Generates an \(N \times L\) time series TS with
TS[j,t]==1
if the walker is at node \(j\) at time \(t\), andTS[j,t]==0
otherwise.The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
The input (groundtruth) graph with \(N\) nodes.
 L (int)
The length of the desired time series.
 Returns:
 TS (np.ndarray)
An \(N \times L\) array of synthetic time series data.
Examples
G = nx.ring_of_cliques(4,16) L = 2001 dynamics = SingleUnbiasedRandomWalker() TS = dynamics.simulate(G, L)


class
netrd.dynamics.
Kuramoto
[source]¶ Kuramoto model of oscillators.

simulate
(G, L, dt=0.01, strength=1, phases=None, freqs=None)[source]¶ Simulate Kuramoto model on a ground truth network.
Kuramoto oscillators model synchronization processes. At each time step, each node adjusts its phase \(\theta_i\) according to the equation
\[\theta_i = \omega_i + \frac{\lambda}{N}\sum_{j=1}^{N}\sin\left(\theta_j  \theta_i\right),\]where \(\lambda\), is a coupling strength parameter and each node has an internal frequency \(\omega_i\); the freqs function parameter provides the option to initialize these frequencies with userdefined values (or leave as None to randomly initialize). Each node’s initial phase \(\theta_{i0}\) can be randomly initialized (the default behavior) or set by specifying the phases parameter.
The results dictionary also stores the ground truth network as ‘ground_truth’ and the internal frequencies of the process as ‘internal_frequencies’.
For more information on the Kuramoto model, see the review essay included below.
 Parameters:
 G (nx.Graph)
the input (groundtruth) graph with \(N\) nodes.
 L (int)
the length of the desired time series.
 dt (float)
size of timestep for numerical integration.
 strength (float)
coupling strength (prefactor for interaction terms).
 phases (np.ndarray)
an \(N \times 1\) array of initial phases.
 freqs (np.ndarray)
an \(N \times 1\) array of internal frequencies.
 Returns:
 TS (np.ndarray)
an \(N \times L\) array of synthetic time series data.
References
[1]F. Rodrigues, T. Peron, P. Ji, J. Kurths. The Kuramoto model in complex networks. https://arxiv.org/abs/1511.07139
Examples
G = nx.ring_of_cliques(4,16) N = G.number_of_nodes() L = int(1e4) omega = np.random.uniform(0.95, 1.05, N) dynamics = Kuramoto() TS = dynamics.simulate(G, L, dt=0.01, strength=0.3, freqs=omega)


class
netrd.dynamics.
LotkaVolterra
[source]¶ LotkaVolterra dynamics of species abundance.

simulate
(G, L, init=None, gr=None, cap=None, inter=None, dt=0.01, stochastic=True, pertb=None)[source]¶ Simulate time series on a network from the LotkaVolterra model.
The LotkaVolterra model was designed to describe dynamics of species abundances in an ecosystem. Species \(i\)’s abundance change per time is \(\frac{d X_i}{d t} = r_i X_i \left(1  \frac{X_i}{K_i} + \sum_{j \neq i} W_{ij} \frac{X_j}{K_i}\right)\) where \(r_i\) and \(K_i\) are the growth rate and the carrying capacity of species \(i\) respectively, and \(W_{ij}\) are the relative interaction strength of species \(j\) on \(i\).
The results dictionary also stores the ground truth network as ‘ground_truth’ and the intermediate time steps as ‘time_steps’.
 Parameters:
 G (nx.Graph)
Underlying groundtruth network of simulated time series which has \(N\) nodes.
 L (int)
Length of time series.
 init (np.ndarray)
Length\(N\) 1D array of nodes’ initial condition. If not specified an initial condition is unifromly generated from 0 to the nodes’ carrying capacity.
 gr (np.ndarray)
Length\(N\) 1D array of nodes’ growth rate. If not specified, default to 1 for all nodes.
 cap (np.ndarray)
Length\(N\) 1D array of nodes’ carrying capacity. If not specified, default to 1 for all nodes.
 inter (np.ndarray)
\(N \times N\) array of interaction weights between nodes. If not specified, default to a zerodiagonal matrix whose [i, j] entry is \(\frac{sign(j  i)}{N  1}\).
 dt (float or np.ndarray)
Sizes of time steps when simulating the continuoustime dynamics.
 stochastic (bool)
Whether to simulate the stochastic or deterministic dynamics.
 pertb (np.ndarray)
Length\(N\) 1D array of perturbation magnitude of nodes’ growth. If not specified, default to 0.01 for all nodes.
 Returns:
 TS (np.ndarray)
\(N \times L\) array of L observations on \(N\) nodes.
Notes
The deterministic dynamics is simulated through the forthorder RungeKutta method, and the stochastic one is simulated through multiplicative noise with the EulerMaruyama method.
The groundtruth network, time steps and the time series can be found in results[‘groundtruth’], reuslts[‘time_steps’] and results[‘time_series’] respectively.


class
netrd.dynamics.
IsingGlauber
[source]¶ IsingGlauber model.

simulate
(G, L, init=None, beta=2)[source]¶ Simulate time series on a network from the IsingGlauber model.
In the IsingGlauber model, each node has a binary state. At every time step, nodes switch their state with certain probability. For inactive nodes, this probability is \(1 / (1 + e^{\beta (k  2m) / k})\) where \(\beta\) is a parameter tuning the likelihood of switching state, \(k\) is degree of the node and \(m\) is the number of its active neighbors; for active nodes the switchstate probability is \(1  1 / (1 + e^{\beta (k  2m) / k})\) instead.
The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
Underlying groundtruth network of simulated time series which has \(N\) nodes.
 L (int)
Length of time series.
 init (np.ndarray)
Length\(N\) 1D array of nodes’ initial condition, which must have binary value (0 or 1).
 beta (float)
Inverse temperature tuning the likelihood that a node switches its state. Default to \(2\).
 Returns:
 TS (np.ndarray)
\(N \times L\) array of \(L\) observations on \(N\) nodes.


class
netrd.dynamics.
BranchingModel
[source]¶ A sandpilelike branching process.

simulate
(G, L, initial_fraction=0.1, m=0.9975, target_Ahat=0.2, distribution_type='unif', scale=0.95, noise=True)[source]¶ Simulate a (sandpilelike) branching process dynamics .
The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
directed or undirected ground truth graph
 L (int)
desired length of time series
 initial_fraction (float)
fraction of nodes that start as active
 m (float)
branching ratio of the dynamical process. \(m=1.0\) means the system will be at criticality
 target_Ahat (float)
desired average activity. This will ensure the process does not reach a stationary state and will always have some external drive.
 num_edges (int)
the length of the cache, which should correspond to the combination of all possible activity over the simulation.
 distribution_type (str)
string describing which type of random numbers
 scale (float)
scale for how likely nodes are to topple
 noise (bool)
add nonzero values to the time series
 Returns:
 TS (np.ndarray)
an \(N \times L\) time series
References
[1]Levina, Anna, and Viola Priesemann. “Subsampling scaling.” Nature communications 8 (2017) 15140. https://www.nature.com/articles/ncomms15140


class
netrd.dynamics.
VoterModel
[source]¶ Voter dynamics.

simulate
(G, L, noise=None)[source]¶ Simulate votermodelstyle dynamics on a network.
Nodes are randomly assigned a state in \(\{1, 1\}\); at each time step all nodes asynchronously update by choosing their new state uniformly from their neighbors. Generates an \(N \times L\) time series.
The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
the input (groundtruth) graph with N nodes.
 L (int)
the length of the desired time series.
 noise (float, str or None)
if noise is present, with this probability a node’s state will be randomly redrawn from \(\{1, 1\}\) independent of its neighbors’ states. If ‘automatic’, set noise to \(1/N\).
 Returns:
 TS (np.ndarray)
an \(N \times L\) array of synthetic time series data.


class
netrd.dynamics.
SISModel
[source]¶ SusceptibleInfectedSusceptible dynamical process.

simulate
(G, L, num_seeds=1, beta=None, mu=None)[source]¶ Simulate SIS model dynamics on a network.
The results dictionary also stores the ground truth network as ‘ground_truth’.
 Parameters:
 G (nx.Graph)
the input (groundtruth) graph with \(N\) nodes.
 L (int)
the length of the desired time series.
 num_seeds (int)
the number of initially infected nodes.
 beta (float)
the infection rate for the SIS process.
 mu (float)
the recovery rate for the SIS process.
 Returns:
 TS (np.ndarray)
an \(N \times L\) array of synthetic time series data.
