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.

import networkx as nx
import numpy as np
from perturbNet import (
    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 state
trajectory = numerical_integration(G, model_mm, x0, times)
steady = trajectory[-1]

# Compute LCM and GCM
LCM = local_correlation_matrix(G, "MM", steady)
GCM = global_correlation_matrix(G, steady, model_mm, times)

# Temporal distances from a source node
tau = np.array([G.degree(n) ** -0.5 for n in G.nodes()])
d_barzel, d_mp = temporal_distances(G, LCM, tau, source=0)

# Visualize propagation
paths = [nx.shortest_path(G, source=0, target=n) for n in G.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.