Metadata-Version: 2.4
Name: diffusive-routing
Version: 1.0.0
Summary: Entropy-minimizing network routing — packets flow along paths of minimum entropic resistance (GenesisAeon Package 30)
Project-URL: Homepage, https://github.com/GenesisAeon/diffusive-routing
Project-URL: Repository, https://github.com/GenesisAeon/diffusive-routing
Project-URL: Documentation, https://genesisaeon.github.io/diffusive-routing
Project-URL: Issues, https://github.com/GenesisAeon/diffusive-routing/issues
Project-URL: Zenodo, https://doi.org/10.5281/zenodo.XXXXXXX
Author: GenesisAeon
License: MIT
License-File: LICENSE
Keywords: crep,diffusion,entropy,network-science,routing,utac
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Requires-Dist: networkx>=3.2
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Description-Content-Type: text/markdown

# diffusive-routing

**Entropy-minimizing network routing** — packets are routed along paths of
minimum entropic resistance, with the resistance field evolving under a
Turing-style reaction-diffusion process driven by network load.

[![CI](https://github.com/GenesisAeon/diffusive-routing/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/diffusive-routing/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

A self-contained synthetic routing testbed: a NetworkX topology (datacenter
fat-tree or random), an entropic resistance field `ρ_ij = baseline / (1 +
Γ_ij · C_ij)`, a modified-Dijkstra router that follows that field, and a
reaction-diffusion update `dρ/dt = D∇²ρ - kΓρ + f(load)` that lets the field
adapt over time. All values reported by the system are computed live from
the simulation — there is no fabricated benchmark data.

---

## Installation

```bash
pip install diffusive-routing
# with visualisation support (matplotlib)
pip install "diffusive-routing[viz]"
```

## Usage

```bash
# Run a simulation cycle on the default datacenter fat-tree topology
diffusive-routing run --topology datacenter-fat-tree --packets 1000

# Compare diffusive routing against a static shortest-path (OSPF-like) baseline
diffusive-routing compare-ospf --topology random --packets 200

# Visualise the entropic resistance field
diffusive-routing visualise --save-path field.png
```

Or use it as a library:

```python
from diffusive_routing import DiffusiveRouting

system = DiffusiveRouting()
result = system.run_cycle(n_packets=1000)
print(result)
print(system.get_crep_state())   # {"C": ..., "R": ..., "E": ..., "P": ..., "Gamma": ...}
print(system.get_utac_state())   # {"H": ..., "dH_dt": ..., "H_star": ..., ...}
```

## How it works

- **Entropic resistance field** (`entropy_field.py`) — per-link resistance
  derived from the link's CREP state; lower resistance means a more
  attractive path.
- **Reaction-diffusion** (`reaction_diffusion.py`) — the resistance field
  diffuses across neighbouring links and decays/reinforces based on
  utilization, so congestion on one link gradually reroutes traffic onto
  neighbours.
- **Router** (`router.py`) — routes each `Packet` via shortest path under
  the current resistance weights (a diffusive analogue of Dijkstra).
- **S_A / S_V duality** (`sa_sv_duality.py`) — tracks the action entropy of
  routed paths (`S_A`, routing cost) against the volume entropy of traffic
  incident on a destination (`S_V`), exposing a Lagrangian-style score
  `L_net = -S_A + S_V`.
- **CREP tensor** (`crep_network.py`) — per-link and network-wide
  Coherence / Resonance / Emergence / Poetics-diversity state, aggregated
  into a single `Γ` via a geometric mean.
- **Benchmark** (`benchmark.py`) — `compare-ospf` runs the same
  (src, dst) pairs through both diffusive routing and a static
  shortest-path baseline and reports throughput/hop/resistance deltas.

## Role in the GenesisAeon Ecosystem

`diffusive-routing` is package **P30** in the GenesisAeon ecosystem,
covering the **network science** domain. It implements the GenesisAeon
Diamond Interface (`run_cycle`, `get_crep_state`, `get_utac_state`,
`get_phase_events`, `to_zenodo_record`) on top of the UTAC/CREP tensor
framework shared across the ecosystem, targeting a routing `Γ` setpoint of
approximately 0.443 (efficiency `η = tanh(σ·Γ)`, `σ = 2.2`).

## Citation

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.PLACEHOLDER.svg)](https://doi.org/10.5281/zenodo.PLACEHOLDER)

DOI will be assigned automatically on first GitHub Release once
Zenodo–GitHub integration is enabled for this repo.

---

Built with [Typer](https://typer.tiangolo.com/) · [Rich](https://rich.readthedocs.io/) · [NetworkX](https://networkx.org/)
