perturbNet

A Python library for analyzing the propagation of perturbations in steady-state dynamical systems defined on networks.

This framework implements analytical and numerical techniques for studying perturbation responses based on Local and Global Correlation Matrices, as originally introduced in Barzel & Barabási, Nat. Phys. 2013 and extended in later works.

Requires dynamical systems that can be studied via ODEs such as those studied in Ref:https://doi.org/10.1038/nphys2741 and associated works.

---

Key Features

• Local & Global Correlation Matrices from steady-state ODE dynamics
• Perturbation distance metrics (Barzel, Multi-path)
• Model-agnostic ODE integration (SIS, Michaelis-Menten, Population dynamics)
• Concentric layout visualization of perturbation propagation
• Flow-based metrics from GCMs

---

Installation

pip install -e .

---

Project Structure

.
├── pyproject.toml
├── README.md
└── src/
└── perturbNet/
├── correlation.py # LCM, GCM, GCM reconstruction
├── distances.py # Temporal distances from perturbation
├── dynamics.py # SIS, POP, MM models
├── integration.py # ODE integration with steady-state checks
├── layout.py # Concentric layout and visualizations
├── metrics.py # Flow metrics from GCM
└── __init__.py # Library entry point

---

Supported Models

The following ODE-based models are implemented:

• SIS (Epidemic spreading)
• MM (Michaelis–Menten regulatory dynamics)
• POP (Birth–death population dynamics)

All models follow the standard format:
dx_i/dt = F(x_i) + G(sum of neighbors)

---

Example Usage

Also see the usage_example.py in the examples folder.

importnetworkxasnximportnumpyasnpfromperturbNetimport (
model_mm, numerical_integration,
local_correlation_matrix, global_correlation_matrix,
temporal_distances, generate_concentric_layout,
plot_concentric_propagation
)
G=nx.erdos_renyi_graph(30, 0.2)
x0=np.random.rand(G.number_of_nodes())
times=np.linspace(0, 20, 2000)
# Steady statetrajectory=numerical_integration(G, model_mm, x0, times)
steady=trajectory[-1]
# Compute LCM and GCMLCM=local_correlation_matrix(G, "MM", steady)
GCM=global_correlation_matrix(G, steady, model_mm, times)
# Temporal distances from a source nodetau=np.array([G.degree(n) **-0.5forninG.nodes()])
d_barzel, d_mp=temporal_distances(G, LCM, tau, source=0)
# Visualize propagationpaths= [nx.shortest_path(G, source=0, target=n) forninG.nodes()]
pos, tree=generate_concentric_layout(G, paths, source=0, distances=d_mp)
plot_concentric_propagation(tree, pos, perturbations=steady/np.max(steady))

---

References

• Barzel & Barabási, Universality in network dynamics, Nature Physics, 2013
  https://doi.org/10.1038/nphys2741
• Hens et al., Spatiotemporal signal propagation in complex networks, Nature Physics, 2019
  https://doi.org/10.1038/s41567-018-0409-0
• Bontorin & De Domenico, M. Multi pathways temporal distance unravels the hidden geometry of network-driven processes.https://doi.org/10.1038/s42005-023-01204-1

---

Notes

• Designed for undirected graphs. Directed networks may require additional handling.
• Node indices must match array ordering for steady state, GCM, etc.
• Use NumericalIntegration with a long enough time vector to ensure convergence.

---

Installation

pip install -e .

Requires Python ≥ 3.8 and the following packages:

• numpy
• scipy
• matplotlib
• networkx

---

License

MIT License. See LICENSE file.