ISOMORPH-demo / README.md
HyeminGu
fixed runtime error
604704b
---
title: ISOMORPH Supply Chain Digital Twin
emoji: 🏭
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.7.1
app_file: app.py
pinned: false
python_version: "3.11"
---
# ISOMORPH Supply Chain Digital Twin
**Interactive simulation environment for stress-testing supply chains under demand shocks, disruptions, and cascading transport congestion.**
ISOMORPH is a stochastic digital twin of a 13-node multi-echelon US logistics network. Configure parameters, run the simulation, and observe how local operational decisions propagate through the network over time.
## What you can explore
- **πŸ—ΊοΈ Network Map** β€” animated shipment propagation across the US network; nodes colored by backlog stress, moving dots colored by SKU. Export as an animated GIF.
- **πŸ“Š Node Detail** β€” per-node time series of inventory, backlog, inflow, outflow, and demand with disruption event markers.
- **πŸ“ˆ Bullwhip** β€” tier-level amplification chart (B = Var(inflow) / Var(outflow)); shows how demand variability grows upstream through the network.
- **πŸ”₯ Edge Util** β€” heatmap of daily shipping-lane utilization; highlights congestion and disruption events.
- **⬇️ Download** β€” full CSV export of all state variables for every node, item, and day.
## Preset scenarios
| Preset | What it demonstrates |
|--------|----------------------|
| 🟒 Baseline | Mild bullwhip emerging internally from (s, S) ordering and lead-time delays alone |
| ⚑ Demand Shock | Correlated macro shocks and per-item bursts amplify variability upstream |
| πŸ”΄ Disruption | A lane is randomly blocked; goods reroute and a catch-up wave propagates on recovery |
| πŸ“¦ Low Capacity | Cascading transport congestion from the last-mile inward; systemic stockouts and extreme bullwhip |
Use the preset buttons to instantly load a scenario, then tune individual parameters with the left-panel sliders and click **β–Ά Run Simulation** to re-run.
## Paper
*ISOMORPH: A Supply Chain Digital Twin for Simulation, Dataset Generation, and Forecasting Benchmarks*
Zhang et al., 2026 β€” [arXiv:2605.12768](https://arxiv.org/abs/2605.12768)
Full simulator and datasets: [github.com/tuhinsahai/ISOMORPH](https://github.com/tuhinsahai/ISOMORPH)
## Acknowledgements
This material is based upon work supported by the Defense Advanced Research Projects Agency (DARPA) under Agreement No. HR00112590112. Approved for public release; distribution is unlimited.
## Citation
```bibtex
@misc{zhang2026isomorphsupplychaindigital,
title={ISOMORPH: A Supply Chain Digital Twin for Simulation, Dataset Generation, and Forecasting Benchmarks},
author={Zhizhen Zhang and Hyemin Gu and Benjamin J. Zhang and Daniel Elenius and Michael Tyrrell and Theo J. Bourdais and Houman Owhadi and Markos A. Katsoulakis and Tuhin Sahai},
year={2026},
eprint={2605.12768},
archivePrefix={arXiv},
primaryClass={stat.ML},
url={https://arxiv.org/abs/2605.12768},
}
```