initial demo

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anonymous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,15 +1,60 @@
 ---
-title: ISOMORPH Demo
-emoji: 🦀
-colorFrom: indigo
+title: ISOMORPH Supply Chain Digital Twin
+emoji: 🏭
+colorFrom: blue
 colorTo: indigo
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
+sdk_version: 4.44.1
 app_file: app.py
 pinned: false
-license: mit
-short_description: Interactive supply-chain stress-testing simulator
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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},
+}
+```

analysis/bullwhip_analysis.py

@@ -0,0 +1,203 @@
+"""
+Per-node and per-tier bullwhip analysis on the digital-twin sim output.
+B_n = Var(inflow_n) / Var(outflow_n)        (Cachon-style amplification ratio)
+"""
+import os
+from pathlib import Path
+import numpy as np
+import pandas as pd
+
+REPO = Path(__file__).resolve().parents[1]
+DATA = os.environ.get("DATA", str(REPO / "data" / "output_item50"))
+OUT  = os.environ.get("OUT",  str(REPO / "results" / "bullwhip"))
+os.makedirs(OUT, exist_ok=True)
+
+# ---------- 1. Network ----------
+edges = pd.read_csv(os.path.join(DATA, "edge_list.csv"))
+nodes = set(edges["from"]) | set(edges["to"])
+parents, children = {}, {}
+for _, r in edges.iterrows():
+    children.setdefault(r["from"], []).append(r["to"])
+    parents.setdefault(r["to"], []).append(r["from"])
+
+sinks = [n for n in nodes if n not in children]
+
+# Tier labels follow the inventory-parameter table of the paper
+# (manuscript Table tab:inventory-params, App. C.4). A longest-path-from-sink
+# BFS would put Memphis at depth 2 (same as Columbus/Richmond, i.e. Tier-4),
+# but the paper labels Memphis as Tier-3 alongside Charlotte and Chicago.
+TIER = {
+    # Destination
+    "NewYork":      0,
+    # Last-mile DCs
+    "Baltimore":    1,   # Tier-5 (LM)
+    "Philadelphia": 1,   # Tier-5 (LM)
+    # Tier-4
+    "Columbus":     2,
+    "Richmond":     2,
+    # Tier-3 (Memphis included by paper convention; topological depth = 2)
+    "Charlotte":    3,
+    "Chicago":      3,
+    "Memphis":      3,
+    # Tier-2
+    "Atlanta":      4,
+    # Hub
+    "Nashville":    5,
+    # Sources -- no inflow on the released edges, dropped by compute_B below
+    "SanFrancisco": 6,
+    "StLouis":      6,
+    "Orlando":      6,
+}
+missing = nodes - set(TIER)
+assert not missing, f"TIER mapping missing nodes: {missing}"
+tier = {n: TIER[n] for n in nodes}
+
+print("Tiers:")
+for t in sorted(set(tier.values())):
+    print(f"  T{t}: {sorted(n for n in nodes if tier[n]==t)}")
+
+# ---------- 2. Shipments → per-(node, item) daily inflow & outflow ----------
+print("\nLoading shipments ...")
+ship = pd.read_csv(
+    os.path.join(DATA, "shipments.csv"),
+    usecols=["day", "arrival_day", "from", "to", "item", "units"],
+)
+print(f"  shipments rows: {len(ship):,}")
+
+# Outflow at node n on day t (item k): units shipped FROM n on day t
+out = (
+    ship.groupby(["from", "item", "day"])["units"].sum()
+        .rename("units").reset_index()
+        .rename(columns={"from": "node", "day": "t"})
+)
+# Inflow at node n on day t (item k): units arriving AT n on arrival_day t
+inn = (
+    ship.groupby(["to", "item", "arrival_day"])["units"].sum()
+        .rename("units").reset_index()
+        .rename(columns={"to": "node", "arrival_day": "t"})
+)
+del ship
+
+# ---------- 3. Customer demand at retail sink (NewYork) ----------
+dr = pd.read_csv(os.path.join(DATA, "daily_records.csv"),
+                 usecols=["day", "item", "demand"])
+
+# ---------- 4. Per-(node, item) variances ----------
+T_MAX = int(dr["day"].max()) + 1
+items = sorted(dr["item"].unique())
+print(f"  horizon: {T_MAX} days, items: {len(items)}")
+
+def to_dense(df, value_col="units"):
+    """pivot a (node,item,t,value) frame to {node:{item: ndarray[T_MAX]}}."""
+    out = {}
+    for (node, item), g in df.groupby(["node", "item"]):
+        v = np.zeros(T_MAX, dtype=np.float64)
+        idx = g["t"].values.astype(int)
+        # Some arrival days may exceed T_MAX (shipments still in transit at end).
+        mask = idx < T_MAX
+        v[idx[mask]] = g[value_col].values[mask]
+        out.setdefault(node, {})[item] = v
+    return out
+
+print("Pivoting outflow ...")
+outflow = to_dense(out)
+print("Pivoting inflow ...")
+inflow = to_dense(inn)
+
+# Sink: outflow = customer demand
+demand_NY = {}
+for item, g in dr.groupby("item"):
+    v = np.zeros(T_MAX, dtype=np.float64)
+    v[g["day"].values.astype(int)] = g["demand"].values
+    demand_NY[item] = v
+sink = sinks[0]
+outflow.setdefault(sink, {})
+for item in items:
+    outflow[sink][item] = demand_NY[item]   # override: customer-facing outflow
+
+# ---------- 5. Compute B per (node, item) at a given aggregation window ----------
+# Burn-in: drop first 365 days to avoid initialization transients
+BURN = 365
+
+def aggregate(series, window):
+    """Sum a daily ndarray into non-overlapping `window`-day bins (drops trailing partial bin)."""
+    if window <= 1:
+        return series
+    n = (len(series) // window) * window
+    return series[:n].reshape(-1, window).sum(axis=1)
+
+def compute_B(window, label, suffix):
+    """Compute per-(node,item) bullwhip ratios at a given temporal aggregation."""
+    rows = []
+    for node in nodes:
+        for item in items:
+            d = outflow.get(node, {}).get(item)
+            o = inflow.get(node, {}).get(item)
+            if d is None or o is None:
+                continue
+            d, o = d[BURN:], o[BURN:]
+            d, o = aggregate(d, window), aggregate(o, window)
+            if len(d) < 2:
+                continue
+            vd, vo = d.var(ddof=1), o.var(ddof=1)
+            if vd == 0 or vo == 0:
+                continue
+            rows.append(dict(
+                node=node, tier=tier[node], item=item,
+                var_demand=vd, var_inflow=vo, B=vo / vd,
+                mean_demand=d.mean(), mean_inflow=o.mean(),
+            ))
+    df = pd.DataFrame(rows)
+    df.to_csv(os.path.join(OUT, f"bullwhip_per_node_item{suffix}.csv"), index=False)
+
+    print(f"\n########## Aggregation: {label} (window={window}d, n_bins={(T_MAX-BURN)//window}) ##########")
+    print(f"Per-(node,item) rows: {len(df)}")
+
+    print(f"\n=== Per-node mean B ({label}) ===")
+    node_summary = (
+        df.groupby(["tier", "node"])
+          .agg(B_mean=("B", "mean"),
+               B_median=("B", "median"),
+               B_p10=("B", lambda s: s.quantile(0.1)),
+               B_p90=("B", lambda s: s.quantile(0.9)),
+               n_items=("B", "count"))
+          .reset_index()
+          .sort_values(["tier", "node"])
+    )
+    print(node_summary.to_string(index=False))
+    node_summary.to_csv(os.path.join(OUT, f"bullwhip_per_node{suffix}.csv"), index=False)
+
+    print(f"\n=== Per-tier summary ({label}) ===")
+    tier_summary = (
+        df.groupby("tier")
+          .agg(B_mean=("B", "mean"),
+               B_median=("B", "median"),
+               mean_var_demand=("var_demand", "mean"),
+               mean_var_inflow=("var_inflow", "mean"),
+               n_obs=("B", "count"))
+          .reset_index()
+          .sort_values("tier")
+    )
+    print(tier_summary.to_string(index=False))
+    tier_summary.to_csv(os.path.join(OUT, f"bullwhip_per_tier{suffix}.csv"), index=False)
+
+    print(f"\n=== Between-tier variance amplification ({label}) ===")
+    btw = tier_summary[["tier", "mean_var_demand"]].copy()
+    btw["amplification_to_next_upstream_tier"] = (
+        btw["mean_var_demand"].shift(-1) / btw["mean_var_demand"]
+    )
+    print(btw.to_string(index=False))
+    btw.to_csv(os.path.join(OUT, f"bullwhip_between_tier{suffix}.csv"), index=False)
+    return df, node_summary, tier_summary
+
+# Daily (original): suffix "" keeps backward-compatible filenames
+compute_B(window=1,  label="daily",   suffix="")
+# Monthly (Cachon-faithful, 30-day bins on simulation time)
+compute_B(window=30, label="monthly", suffix="_monthly")
+
+print("\nSaved:")
+for f in ["bullwhip_per_node_item.csv","bullwhip_per_node.csv",
+          "bullwhip_per_tier.csv","bullwhip_between_tier.csv",
+          "bullwhip_per_node_item_monthly.csv","bullwhip_per_node_monthly.csv",
+          "bullwhip_per_tier_monthly.csv","bullwhip_between_tier_monthly.csv"]:
+    print(" ", os.path.join(OUT, f))

analysis/make_baseline_overview.py

@@ -0,0 +1,194 @@
+"""Generate baseline_overview.pdf for §3 from output_item50.
+
+3 x 2 layout combining catalogue heterogeneity with mechanism:
+
+  Left column (3 panels)  -- raw_item_series.png style: each row is
+                             one catalogue item showing demand,
+                             served, and unmet overlaid over the
+                             full T = 52,560-day horizon. Items:
+                             I01, I20, I40 sample the catalogue.
+
+  Right column (3 panels) -- internal network state for the focal
+                             item I01 in a 5-year zoom window
+                             centred on the largest macro-shock:
+                             (b) destination on-hand inventory
+                             (d) destination backlog
+                             (f) last-mile edge utilisation
+                                 (PHL->NYC, BAL->NYC) with 0.95
+                                 saturation threshold
+
+The yellow band on each left panel marks the right column's window.
+Together the two columns expose both the catalogue's per-item
+heterogeneity and the mechanism that produces fill-rate drop events.
+"""
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+REPO = Path(__file__).resolve().parents[1]
+DATA = REPO / "data" / "output_item50"
+OUT  = REPO / "results" / "figures"
+
+# ---------- styling ----------
+plt.rcParams.update({
+    "font.family": "serif",
+    "font.size": 10,
+    "axes.labelsize": 9.5,
+    "axes.titlesize": 9.5,
+    "axes.titleweight": "bold",
+    "xtick.labelsize": 8.5,
+    "ytick.labelsize": 8.5,
+    "legend.fontsize": 8.0,
+    "mathtext.fontset": "cm",
+    "axes.spines.top": False,
+    "axes.spines.right": False,
+    "axes.grid": True,
+    "grid.alpha": 0.22,
+    "grid.linewidth": 0.5,
+    "lines.linewidth": 0.55,
+})
+
+C_DEMAND = "#3a7cb8"
+C_SERVED = "#d97706"
+C_UNMET = "#b91c1c"
+C_ONHAND = "#0e7c66"
+C_BACKLOG = "#7c3aed"
+C_PHIL = "#c0392b"
+C_BALT = "#e67e22"
+C_THRESH = "#666666"
+C_WIN = "#f1c40f"
+
+ITEMS_LEFT = ["I01", "I02", "I03"]
+FOCAL = "I01"
+
+# ---------- load ----------
+print("Loading daily records ...")
+records = pd.read_csv(DATA / "daily_records.csv")
+records["unmet"] = records["demand"] - records["served_from_stock"]
+
+demand_pv = records.pivot(index="day", columns="item", values="demand")
+served_pv = records.pivot(index="day", columns="item",
+                          values="served_from_stock")
+unmet_pv = records.pivot(index="day", columns="item", values="unmet")
+onhand_pv = records.pivot(index="day", columns="item",
+                           values="dest_on_hand_end_before_ship")
+backlog_pv = records.pivot(index="day", columns="item",
+                            values="dest_backlog_end_before_ship")
+T = demand_pv.shape[0]
+print(f"Horizon T = {T} days; left items: {ITEMS_LEFT}; "
+      f"focal item: {FOCAL}")
+
+# edge utilisation
+edge_util = np.load(DATA / "edge_utilisation.npy")
+edge_list = pd.read_csv(DATA / "edge_list.csv")
+phil_idx = int(edge_list.index[(edge_list["from"] == "Philadelphia")
+                               & (edge_list["to"] == "NewYork")][0])
+balt_idx = int(edge_list.index[(edge_list["from"] == "Baltimore")
+                               & (edge_list["to"] == "NewYork")][0])
+
+# ---------- zoom window ----------
+agg = demand_pv.sum(axis=1).values
+WIN = 5 * 365
+roll = pd.Series(agg).rolling(WIN, center=True).mean()
+peak = int(roll.idxmax())
+start = max(0, peak - WIN // 2)
+end = min(T, start + WIN)
+start = max(0, end - WIN)
+print(f"Zoom window: days {start}..{end} (peak at day {peak})")
+
+# focal-item slices
+foc_onhand = onhand_pv[FOCAL].values
+foc_backlog = backlog_pv[FOCAL].values
+foc_onhand_z = foc_onhand[start:end]
+foc_backlog_z = foc_backlog[start:end]
+util_phil_z = edge_util[start:end, phil_idx]
+util_balt_z = edge_util[start:end, balt_idx]
+
+# ---------- figure ----------
+fig, axes = plt.subplots(3, 2, figsize=(13, 7.4),
+                          gridspec_kw={"hspace": 0.55, "wspace": 0.20,
+                                       "width_ratios": [1.7, 1.0]})
+
+panel_letters_left = ["a", "c", "e"]
+
+# -------- left column: per-item demand/served/unmet --------
+for r, item in enumerate(ITEMS_LEFT):
+    d = demand_pv[item].values
+    s = served_pv[item].values
+    u = unmet_pv[item].values
+    fr = s.sum() / max(d.sum(), 1e-9)
+    ymax = max(d.max(), s.max()) * 1.10
+
+    ax = axes[r, 0]
+    ax.fill_between(np.arange(T), 0, u, color=C_UNMET, alpha=0.18,
+                    lw=0)
+    ax.plot(np.arange(T), d, color=C_DEMAND, lw=0.45, alpha=0.85,
+            label="demand" if r == 0 else None)
+    ax.plot(np.arange(T), s, color=C_SERVED, lw=0.45, alpha=0.85,
+            label="served" if r == 0 else None)
+    ax.plot(np.arange(T), u, color=C_UNMET, lw=0.45, alpha=0.95,
+            label="unmet" if r == 0 else None)
+    ax.axvspan(start, end, color=C_WIN, alpha=0.22, lw=0,
+               label="zoom window" if r == 0 else None)
+    ax.set_xlim(0, T - 1)
+    ax.set_ylim(0, ymax)
+    ax.set_ylabel(f"{item} demand (units)")
+    ax.set_title(f"({panel_letters_left[r]})  {item} full horizon "
+                 f"($T={T}$, fill rate {fr:.3f})", loc="left")
+    if r == 0:
+        ax.legend(loc="upper right", ncol=4, frameon=False,
+                  columnspacing=1.0, handlelength=1.4)
+    if r == 2:
+        ax.set_xlabel("time unit")
+
+# -------- right column: focal-item mechanism in zoom --------
+# y-axis scaled to the zoom-window range, not the full horizon, so
+# the dynamics inside the window are readable
+ymax_onh = max(1.0, foc_onhand_z.max() * 1.10)
+ymax_bk = max(1.0, foc_backlog_z.max() * 1.10)
+days_z = np.arange(start, end)
+
+# (b) destination on-hand for focal item
+ax = axes[0, 1]
+ax.fill_between(days_z, 0, foc_onhand_z, color=C_ONHAND, alpha=0.18,
+                lw=0)
+ax.plot(days_z, foc_onhand_z, color=C_ONHAND, lw=0.85, alpha=0.95)
+ax.set_xlim(start, end - 1)
+ax.set_ylim(0, ymax_onh)
+ax.set_ylabel(f"{FOCAL} on-hand")
+ax.set_title(f"(b)  Zoom: {FOCAL} destination on-hand inventory",
+             loc="left")
+
+# (d) destination backlog for focal item
+ax = axes[1, 1]
+ax.fill_between(days_z, 0, foc_backlog_z, color=C_BACKLOG, alpha=0.18,
+                lw=0)
+ax.plot(days_z, foc_backlog_z, color=C_BACKLOG, lw=0.85, alpha=0.95)
+ax.set_xlim(start, end - 1)
+ax.set_ylim(0, ymax_bk)
+ax.set_ylabel(f"{FOCAL} backlog")
+ax.set_title(f"(d)  Zoom: {FOCAL} destination backlog", loc="left")
+
+# (f) last-mile edge utilisation in zoom
+ax = axes[2, 1]
+ax.plot(days_z, util_phil_z, color=C_PHIL, lw=0.85, alpha=0.95,
+        label=r"PHL$\to$NYC")
+ax.plot(days_z, util_balt_z, color=C_BALT, lw=0.85, alpha=0.85,
+        label=r"BAL$\to$NYC")
+ax.axhline(0.95, color=C_THRESH, ls="--", lw=0.9, alpha=0.7,
+           label=r"$U=0.95$")
+ax.set_xlim(start, end - 1)
+ax.set_ylim(0, 1.05)
+ax.set_ylabel(r"$U_{e,t}$")
+ax.set_xlabel("time unit")
+ax.set_title("(f)  Zoom: last-mile edge utilisation", loc="left")
+ax.legend(loc="upper left", ncol=3, frameon=False,
+          columnspacing=1.0, handlelength=1.6)
+
+plt.savefig(OUT / "baseline_overview.pdf", bbox_inches="tight")
+plt.savefig(OUT / "baseline_overview.png", dpi=160,
+            bbox_inches="tight")
+print(f"Saved {OUT / 'baseline_overview.pdf'}")
+print(f"Saved {OUT / 'baseline_overview.png'}")

analysis/make_scenario_family.py

@@ -0,0 +1,255 @@
+"""
+Figure 4 (replacement): single-row small multiples, rendered as
+two separate figures so each can be placed independently in the
+paper.
+
+For one item (I36, with high macro-shock sensitivity g_i and high
+burst rate r_i), under four demand-side scenarios:
+
+  scenario_family_demand.pdf
+        realised demand y_{i,t}  +  deterministic intensity
+        lambda_{i,t}  (Eq.\\ ref{eq:intensity})
+
+  scenario_family_oh.pdf
+        destination on-hand OH^{d*,i}_t at NewYork
+        (end-of-step value; the network's response to demand)
+
+Supply-side sweeps leave y_{i,t} unchanged by construction and
+are omitted.
+"""
+
+from pathlib import Path
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+from matplotlib.ticker import MaxNLocator, MultipleLocator, FuncFormatter
+import matplotlib.patheffects as pe
+
+
+def _short_count(x: float, _pos: int) -> str:
+    """Compact integer formatter: 1.2M, 30K, 5K, 0."""
+    if x == 0:
+        return "0"
+    ax = abs(x)
+    if ax >= 1e6:
+        return f"{x/1e6:g}M"
+    if ax >= 1e3:
+        return f"{x/1e3:g}K"
+    return f"{int(x)}"
+
+
+SHORT = FuncFormatter(_short_count)
+
+REPO = Path(__file__).resolve().parents[1]
+DATA = REPO / "data" / "output_mixture"
+OUT  = REPO / "results" / "figures"
+OUT.mkdir(parents=True, exist_ok=True)
+
+ITEM = "I36"
+T_FULL = 52560
+
+# (dir name, panel title, accent colour for line, shadow tint)
+SCENARIOS = [
+    ("baseline",  r"baseline",
+     "#3470a8", "#cddbeb"),  # cobalt  / pale blue
+    ("drift_hi",  r"drift  $(\phi^{\mathrm{AR}}\!=\!0.99)$",
+     "#7e5b9a", "#dcd2e5"),  # plum    / pale mauve
+    ("shock_xhi", r"shock  $(N{\times}h^{G}\!=\!3{\times}4)$",
+     "#c08438", "#f0d8b6"),  # caramel / pale cream
+    ("burst_xhi", r"burst  $(r{\times}h^{P}\!=\!3{\times}4)$",
+     "#a64141", "#e7c4c2"),  # brick   / pale rose
+]
+
+# ---------------------------------------------------------------- style
+mpl.rcParams.update({
+    "font.family": "serif",
+    "font.serif": ["Times New Roman", "Nimbus Roman", "DejaVu Serif"],
+    "mathtext.fontset": "cm",
+    "font.size": 9.5,
+    "axes.labelsize": 9.5,
+    "axes.titlesize": 10.0,
+    "axes.titleweight": "normal",
+    "xtick.labelsize": 8.0,
+    "ytick.labelsize": 8.0,
+    "axes.spines.top": False,
+    "axes.spines.right": False,
+    "axes.linewidth": 0.5,
+    "xtick.major.width": 0.5,
+    "ytick.major.width": 0.5,
+    "xtick.minor.width": 0.3,
+    "ytick.minor.width": 0.3,
+    "xtick.major.size": 2.4,
+    "ytick.major.size": 2.4,
+    "xtick.minor.size": 1.3,
+    "ytick.minor.size": 1.3,
+    "xtick.direction": "out",
+    "ytick.direction": "out",
+    "axes.grid": False,
+    "axes.axisbelow": True,
+    "pdf.fonttype": 42,
+    "ps.fonttype": 42,
+    "text.usetex": False,
+})
+
+# ---------------------------------------------------------------- data
+def load_panel(scenario: str, item: str):
+    df = pd.read_csv(
+        DATA / scenario / "seed2025" / "daily_records.csv",
+        usecols=("day", "item", "demand", "dest_on_hand_end_before_ship"),
+    )
+    s = df[df["item"] == item].sort_values("day")
+    y = s["demand"].to_numpy()
+    oh = s["dest_on_hand_end_before_ship"].to_numpy()
+    assert y.size == T_FULL, f"{scenario}: got {y.size} rows for {item}"
+
+    cols = (DATA / scenario / "seed2025" / "demand_signals_cols.txt").read_text().strip().split(",")
+    j = cols.index(item)
+    lam = np.load(DATA / scenario / "seed2025" / "demand_signals.npy")[:, j]
+    return y, lam, oh
+
+
+panels = [(scen, title, accent, shadow, *load_panel(scen, ITEM))
+          for scen, title, accent, shadow in SCENARIOS]
+
+# ---------------------------------------------------------------- figure
+t_years = np.arange(T_FULL) / 1e4
+decim = max(1, T_FULL // 6000)
+
+
+# =================================================================
+# Figure A: realised demand y_{i,t} + intensity lambda_{i,t}
+# =================================================================
+figA, axesA = plt.subplots(
+    1, len(SCENARIOS), figsize=(12.0, 2.55),
+    sharey=False,
+    gridspec_kw={"wspace": 0.22},
+)
+
+for ax, (scen, title, accent, shadow, y, lam, _oh) in zip(axesA, panels):
+    ax.plot(t_years[::decim], y[::decim],
+            color=shadow, lw=0.35, alpha=0.85,
+            zorder=1, rasterized=True)
+    ax.plot(t_years, lam,
+            color=accent, lw=0.95, alpha=1.0,
+            solid_capstyle="round", solid_joinstyle="round",
+            zorder=3,
+            path_effects=[pe.Stroke(linewidth=1.9, foreground="white"),
+                          pe.Normal()])
+    ax.set_title(title, style="italic")
+    ax.set_xlim(0, T_FULL / 1e4)
+    ax.xaxis.set_major_locator(MultipleLocator(1.0))
+    ax.xaxis.set_minor_locator(MultipleLocator(0.5))
+    ymax_panel = max(y.max(), lam.max())
+    ax.set_ylim(0, ymax_panel * 1.06)
+    ax.yaxis.set_major_locator(MaxNLocator(nbins=4, integer=True))
+    ax.yaxis.set_minor_locator(MaxNLocator(nbins=8, integer=True))
+
+axesA[0].set_ylabel(rf"item {ITEM} demand")
+figA.supxlabel(r"time $t$ ($\times 10^{4}$ time units)",
+               y=0.04, fontsize=9.5)
+figA.subplots_adjust(left=0.055, right=0.995, top=0.86, bottom=0.22)
+
+outA = OUT / "scenario_family_demand.pdf"
+figA.savefig(outA, bbox_inches="tight")
+figA.savefig(outA.with_suffix(".png"), dpi=200, bbox_inches="tight")
+plt.close(figA)
+
+
+# =================================================================
+# Figure B: destination (NewYork) on-hand OH^{d*, i}_t
+# =================================================================
+figB, axesB = plt.subplots(
+    1, len(SCENARIOS), figsize=(12.0, 2.55),
+    sharey=False,
+    gridspec_kw={"wspace": 0.22},
+)
+
+for ax, (scen, title, accent, shadow, _y, _lam, oh) in zip(axesB, panels):
+    ax.plot(t_years[::decim], oh[::decim],
+            color=accent, lw=0.85, alpha=1.0,
+            solid_capstyle="round", solid_joinstyle="round",
+            zorder=3,
+            path_effects=[pe.Stroke(linewidth=1.7, foreground="white"),
+                          pe.Normal()])
+    ax.set_title(title, style="italic")
+    ax.set_xlim(0, T_FULL / 1e4)
+    ax.xaxis.set_major_locator(MultipleLocator(1.0))
+    ax.xaxis.set_minor_locator(MultipleLocator(0.5))
+    ymax_panel = max(1.0, float(oh.max()))
+    ax.set_ylim(0, ymax_panel * 1.08)
+    ax.yaxis.set_major_locator(MaxNLocator(nbins=4, integer=True))
+    ax.yaxis.set_minor_locator(MaxNLocator(nbins=8, integer=True))
+    ax.yaxis.set_major_formatter(SHORT)
+
+axesB[0].set_ylabel(rf"destination on-hand, item {ITEM}")
+figB.supxlabel(r"time $t$ ($\times 10^{4}$ time units)",
+               y=0.04, fontsize=9.5)
+figB.subplots_adjust(left=0.055, right=0.995, top=0.86, bottom=0.22)
+
+outB = OUT / "scenario_family_oh.pdf"
+figB.savefig(outB, bbox_inches="tight")
+figB.savefig(outB.with_suffix(".png"), dpi=200, bbox_inches="tight")
+plt.close(figB)
+
+
+# =================================================================
+# Figure C: combined 2x4 (demand row on top, on-hand row on bottom).
+# Same data as Figures A and B, sharing the x-axis within each column.
+# =================================================================
+figC, axesC = plt.subplots(
+    2, len(SCENARIOS), figsize=(12.0, 4.6),
+    sharex="col", sharey=False,
+    gridspec_kw={"wspace": 0.22, "hspace": 0.18},
+)
+
+for col, (scen, title, accent, shadow, y, lam, oh) in enumerate(panels):
+    ax_top = axesC[0, col]
+    ax_bot = axesC[1, col]
+
+    ax_top.plot(t_years[::decim], y[::decim],
+                color=shadow, lw=0.30, alpha=0.70,
+                zorder=1, rasterized=True)
+    ax_top.plot(t_years, lam,
+                color=accent, lw=0.75, alpha=0.85,
+                solid_capstyle="round", solid_joinstyle="round",
+                zorder=3,
+                path_effects=[pe.Stroke(linewidth=1.5, foreground="white"),
+                              pe.Normal()])
+    ax_top.set_title(title, style="italic")
+    ax_top.set_xlim(0, T_FULL / 1e4)
+    ax_top.xaxis.set_major_locator(MultipleLocator(1.0))
+    ax_top.xaxis.set_minor_locator(MultipleLocator(0.5))
+    ymax_top = max(y.max(), lam.max())
+    ax_top.set_ylim(0, ymax_top * 1.06)
+    ax_top.yaxis.set_major_locator(MaxNLocator(nbins=4, integer=True))
+    ax_top.yaxis.set_minor_locator(MaxNLocator(nbins=8, integer=True))
+
+    ax_bot.plot(t_years[::decim], oh[::decim],
+                color=accent, lw=0.75, alpha=0.85,
+                solid_capstyle="round", solid_joinstyle="round",
+                zorder=3,
+                path_effects=[pe.Stroke(linewidth=1.5, foreground="white"),
+                              pe.Normal()])
+    ax_bot.set_xlim(0, T_FULL / 1e4)
+    ax_bot.xaxis.set_major_locator(MultipleLocator(1.0))
+    ax_bot.xaxis.set_minor_locator(MultipleLocator(0.5))
+    ymax_bot = max(1.0, float(oh.max()))
+    ax_bot.set_ylim(0, ymax_bot * 1.08)
+    ax_bot.yaxis.set_major_locator(MaxNLocator(nbins=4, integer=True))
+    ax_bot.yaxis.set_minor_locator(MaxNLocator(nbins=8, integer=True))
+    ax_bot.yaxis.set_major_formatter(SHORT)
+
+axesC[0, 0].set_ylabel(rf"item {ITEM} demand")
+axesC[1, 0].set_ylabel(rf"destination on-hand, item {ITEM}")
+figC.supxlabel(r"time $t$ ($\times 10^{4}$ time units)",
+               y=0.02, fontsize=9.5)
+figC.subplots_adjust(left=0.055, right=0.995, top=0.93, bottom=0.11)
+
+outC = OUT / "scenario_family.pdf"
+figC.savefig(outC, bbox_inches="tight")
+figC.savefig(outC.with_suffix(".png"), dpi=200, bbox_inches="tight")
+plt.close(figC)
+
+print(f"wrote {outA}, {outB}, and {outC}  item={ITEM}  "
+      f"scenarios={[s for s, *_ in SCENARIOS]}")

app.py

@@ -0,0 +1,789 @@
+"""
+ISOMORPH Supply Chain Digital Twin — Interactive Demo
+======================================================
+Run locally:
+    python app.py
+
+Deploy to Hugging Face Spaces:
+    Upload this file together with the simulator/ and demo/ directories.
+    Set SDK: gradio  in the Space README.
+
+Interaction flow:
+    Configure parameters  →  ▶ Run Simulation
+        →  Network Map   (animated shipment propagation)
+        →  Node Detail   (per-node time series)
+        →  Bullwhip      (tier-level amplification chart)
+        →  Edge Util     (heatmap of capacity usage)
+        →  Download      (CSV export)
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+import time
+from typing import Optional
+
+import gradio as gr
+import numpy as np
+import pandas as pd
+
+from simulator.demo_simulator import run_demo_simulation
+from demo.visualize import (
+    make_network_animation_html,
+    make_network_animation_gif,
+    make_node_timeseries,
+    make_bullwhip_chart,
+    make_edge_heatmap,
+)
+
+# ============================================================================
+# Static reference data
+# ============================================================================
+
+# All directed edges in the fixed ISOMORPH topology
+_EDGE_STRINGS = [
+    "None  (no disruption)",
+    "SanFrancisco → Nashville",
+    "StLouis → Nashville",
+    "Orlando → Nashville",
+    "Nashville → Atlanta",
+    "Atlanta → Chicago",
+    "Atlanta → Charlotte",
+    "Atlanta → Memphis",
+    "Chicago → Columbus",
+    "Charlotte → Richmond",
+    "Columbus → Philadelphia",
+    "Richmond → Philadelphia",
+    "Richmond → Baltimore",
+    "Columbus → Baltimore",
+    "Memphis → Baltimore",
+    "Philadelphia → NewYork",
+    "Baltimore → NewYork",
+]
+
+# Node choices ordered: destination first, then by tier
+_NODE_TIER = {
+    "NewYork": 0,
+    "Philadelphia": 1, "Baltimore": 1,
+    "Columbus": 2, "Richmond": 2,
+    "Charlotte": 3, "Chicago": 3, "Memphis": 3,
+    "Atlanta": 4,
+    "Nashville": 5,
+    "SanFrancisco": 6, "StLouis": 6, "Orlando": 6,
+}
+_NODE_CHOICES = sorted(_NODE_TIER, key=lambda n: (_NODE_TIER[n], n))
+
+_TIER_LABEL = {
+    0: "Destination", 1: "Last-mile",
+    2: "Tier-4", 3: "Tier-3",
+    4: "Tier-2 (Atlanta)", 5: "Hub (Nashville)", 6: "Source",
+}
+
+# Narrative preset configurations (T, n_items, seed, pipeline_mult,
+#   phi_lo, shock_height_scale, burst_rate_scale, burst_height_scale,
+#   containers_scale, ss_scale, leadtime_scale,
+#   disruption_edge_str, disruption_prob, disruption_duration,
+#   holding_cost, backlog_penalty)
+_PRESETS = {
+    "baseline": (
+        200, 3, 42, 7.0, 0.95, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+        "None  (no disruption)", 0.0, 10, 1.0, 5.0,
+    ),
+    "demand_shock": (
+        200, 3, 42, 7.0, 0.95, 4.0, 2.0, 3.0, 1.0, 1.0, 1.0,
+        "None  (no disruption)", 0.0, 10, 1.0, 5.0,
+    ),
+    "disruption": (
+        200, 3, 42, 7.0, 0.95, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
+        "Atlanta → Chicago", 0.08, 14, 1.0, 5.0,
+    ),
+    "low_capacity": (
+        200, 3, 42, 7.0, 0.95, 1.0, 1.0, 1.0, 0.4, 1.0, 1.0,
+        "None  (no disruption)", 0.0, 10, 1.0, 5.0,
+    ),
+}
+
+
+# ============================================================================
+# Helper utilities
+# ============================================================================
+
+def _parse_edge(edge_str: str):
+    """'Atlanta → Chicago'  →  ('Atlanta', 'Chicago'),  'None...'  →  None."""
+    if edge_str.startswith("None"):
+        return None
+    parts = edge_str.split(" → ")
+    return (parts[0].strip(), parts[1].strip()) if len(parts) == 2 else None
+
+
+def _build_config(T, n_items, seed, pipeline_mult,
+                  phi_lo, shock_height_scale,
+                  burst_rate_scale, burst_height_scale,
+                  containers_scale, ss_scale, leadtime_scale,
+                  disruption_edge_str, disruption_prob, disruption_duration,
+                  holding_cost, backlog_penalty) -> dict:
+    return {
+        "T":                    int(T),
+        "n_items":              int(n_items),
+        "seed":                 int(seed),
+        "pipeline_mult":        float(pipeline_mult),
+        "phi_lo":               float(phi_lo),
+        "phi_hi":               min(float(phi_lo) + 0.02, 0.9999),
+        "shock_height_scale":   float(shock_height_scale),
+        "burst_rate_scale":     float(burst_rate_scale),
+        "burst_height_scale":   float(burst_height_scale),
+        "containers_scale":     float(containers_scale),
+        "ss_scale":             float(ss_scale),
+        "leadtime_scale":       float(leadtime_scale),
+        "disruption_edge":      _parse_edge(str(disruption_edge_str)),
+        "disruption_prob":      float(disruption_prob),
+        "disruption_duration":  int(disruption_duration),
+        "holding_cost":         float(holding_cost),
+        "backlog_penalty":      float(backlog_penalty),
+    }
+
+
+def _format_summary(result, elapsed_s: float) -> str:
+    """Return a Markdown summary table."""
+    lines = [
+        f"**Simulation complete** in `{elapsed_s:.2f}s`  ·  "
+        f"T = {result.T} days  ·  "
+        f"Items = {len(result.item_ids)}  ·  "
+        f"Shipments logged = {len(result.shipments):,}",
+        "",
+        "| Item | Fill Rate | Total Demand | Backlogs |",
+        "|------|----------:|-------------:|---------:|",
+    ]
+    for iid in result.item_ids:
+        fr   = result.fill_rate.get(iid, 0.0)
+        dem  = int(result.demand[iid].sum())
+        bl   = int(result.backlog["NewYork"][iid].sum())
+        lines.append(f"| `{iid}` | {fr:.1%} | {dem:,} | {bl:,} |")
+
+    n_ev = len(result.disruption_log)
+    if n_ev:
+        ded = result.disruption_log[0]["edge"]
+        lines += [
+            "",
+            f"⚠️ **Disruption** on `{ded[0]} → {ded[1]}`"
+            f"  ·  {n_ev} event(s) triggered over {result.T} days",
+        ]
+    return "\n".join(lines)
+
+
+def _make_csv_bytes(result) -> bytes:
+    """Return a CSV as bytes for download."""
+    rows = []
+    for nid in result.node_ids:
+        for iid in result.item_ids:
+            for t in range(result.T):
+                rows.append({
+                    "day":       t,
+                    "node":      nid,
+                    "item":      iid,
+                    "inventory": int(result.inventory[nid][iid][t]),
+                    "backlog":   int(result.backlog[nid][iid][t]),
+                    "inflow":    int(result.inflow[nid][iid][t]),
+                    "outflow":   int(result.outflow[nid][iid][t]),
+                    "demand":    int(result.demand[iid][t])
+                               if nid == "NewYork" else "",
+                })
+    buf = io.StringIO()
+    pd.DataFrame(rows).to_csv(buf, index=False)
+    return buf.getvalue().encode()
+
+
+# ============================================================================
+# Gradio callbacks
+# ============================================================================
+
+def run_sim(T, n_items, seed, pipeline_mult,
+            phi_lo, shock_height_scale,
+            burst_rate_scale, burst_height_scale,
+            containers_scale, ss_scale, leadtime_scale,
+            disruption_edge_str, disruption_prob, disruption_duration,
+            holding_cost, backlog_penalty):
+    """
+    Main callback: builds config, runs simulation, generates all figures.
+    Returns (sim_state, anim_fig, ts_fig, bw_fig, heat_fig, summary_md,
+             item_filter_update).
+    """
+    try:
+        config = _build_config(
+            T, n_items, seed, pipeline_mult,
+            phi_lo, shock_height_scale,
+            burst_rate_scale, burst_height_scale,
+            containers_scale, ss_scale, leadtime_scale,
+            disruption_edge_str, disruption_prob, disruption_duration,
+            holding_cost, backlog_penalty,
+        )
+        t0 = time.time()
+        result = run_demo_simulation(config)
+        elapsed = time.time() - t0
+
+        fig_anim = make_network_animation_html(result)
+        fig_ts   = make_node_timeseries(result, "NewYork")
+        fig_bw   = make_bullwhip_chart(result)
+        fig_heat = make_edge_heatmap(result)
+        summary  = _format_summary(result, elapsed)
+
+        item_choices = ["All items"] + result.item_ids
+        return (
+            result,
+            fig_anim,
+            fig_ts,
+            fig_bw,
+            fig_heat,
+            summary,
+            gr.update(choices=item_choices, value="All items"),
+        )
+
+    except Exception as exc:
+        err = f"**Error during simulation:** `{exc}`"
+        return None, None, None, None, None, err, gr.update()
+
+
+def update_timeseries(result, node_id: str, item_filter: str):
+    """Redraws the node time-series when node or item selection changes."""
+    if result is None:
+        return None
+    item_ids = None if item_filter == "All items" else [item_filter]
+    return make_node_timeseries(result, node_id, item_ids=item_ids)
+
+
+def generate_gif(result):
+    """Renders the network animation as an animated GIF and returns the file path."""
+    if result is None:
+        return None
+    return make_network_animation_gif(result)
+
+
+def prepare_download(result):
+    """Writes a CSV to a temp file and returns the path for gr.File."""
+    if result is None:
+        return None
+    data = _make_csv_bytes(result)
+    tmp = tempfile.NamedTemporaryFile(
+        suffix=".csv", delete=False, mode="wb", prefix="isomorph_")
+    tmp.write(data)
+    tmp.close()
+    return tmp.name
+
+
+# Collect all slider/dropdown inputs in order (must match run_sim signature)
+def _all_inputs(components: dict) -> list:
+    return [
+        components["T"], components["n_items"], components["seed"],
+        components["pipeline_mult"], components["phi_lo"],
+        components["shock_height_scale"],
+        components["burst_rate_scale"], components["burst_height_scale"],
+        components["containers_scale"], components["ss_scale"],
+        components["leadtime_scale"],
+        components["disruption_edge"], components["disruption_prob"],
+        components["disruption_duration"],
+        components["holding_cost"], components["backlog_penalty"],
+    ]
+
+
+# ============================================================================
+# Gradio application layout
+# ============================================================================
+
+_CSS = """
+#run-btn { font-size: 1.1em; }
+.panel-header { font-weight: 600; color: #1a1a2e; }
+.result-tab > div { padding-top: 4px; }
+footer { display: none !important; }
+
+/* Shared accent accordion style — used for highlighted collapsibles */
+#markov-accordion > .label-wrap,
+#learn-more-accordion > .label-wrap,
+#state-space-accordion > .label-wrap {
+    background: linear-gradient(90deg, #1a3a5c 0%, #2471a3 100%);
+    border-radius: 6px;
+    padding: 8px 14px;
+}
+#markov-accordion > .label-wrap span,
+#markov-accordion > .label-wrap .icon,
+#learn-more-accordion > .label-wrap span,
+#learn-more-accordion > .label-wrap .icon,
+#state-space-accordion > .label-wrap span,
+#state-space-accordion > .label-wrap .icon {
+    color: #ffffff !important;
+    font-weight: 700;
+    font-size: 1.05em;
+    letter-spacing: 0.01em;
+}
+#markov-accordion,
+#learn-more-accordion,
+#state-space-accordion {
+    border: 2px solid #2471a3 !important;
+    border-radius: 8px;
+    margin-top: 10px;
+}
+"""
+
+_DESCRIPTION = """
+***Interactive simulation environment for stress-testing supply chains under demand shocks, disruptions, and cascading transport congestion.***
+
+Modern supply chains are vulnerable to delays, congestion, shortages, and cascading disruptions. This demo provides an interpretable digital twin for configuring and simulating the real-time evolution of a **stochastic multi-echelon supply-chain network**, studying how local operational decisions propagate through large logistics networks over time.
+
+This demo runs a **fixed 13-node US network**: three suppliers (San Francisco, St. Louis, Orlando) → regional hub (Nashville) → distribution warehouses (Atlanta, Chicago, Charlotte, Memphis, Columbus, Richmond) → last-mile DCs (Philadelphia, Baltimore) → destination (New York).
+
+**Users can interactively configure:**
+**Demand characteristics** · **Network capacity** · **Edge disruptions** · **Simulation scope** — then observe how operational effects propagate through the system over time.
+
+**The platform is designed to support:**
+- Stress-testing supply chains under demand shocks, congestion, and disruptions
+- Studying bullwhip effect amplification across network tiers
+- Visualizing cascading congestion, bottleneck formation, and inventory depletion
+- Building intuition for how local operational decisions affect global network behavior
+
+All within a fixed 13-node network and a product catalogue of up to 5 SKUs.
+
+---
+
+**Presets and parameter tuning**
+
+Four preset buttons at the top instantly load and run a scenario. There is one baseline and three stress-test scenarios:
+
+- 🟢 **Baseline** — stable operating conditions; observe inventory cycles and the mild bullwhip effect emerging internally from (s, S) ordering and lead-time delays alone
+- ⚡ **Demand Shock** — correlated macro shocks and per-item bursts amplify demand variability; backlogs build at NewYork (destination) and variability amplifies upstream through the network
+- 🔴 **Disruption** — the Atlanta→Chicago lane is randomly blocked; goods reroute and inventory depletes downstream of the outage, then a catch-up wave propagates on recovery
+- 📦 **Low Capacity** — all edges at 40% capacity; cascading transport congestion propagates from the last-mile inward, causing systemic stockouts and extreme bullwhip amplification
+
+To stress-test further, adjust individual parameters using the sliders in the left panel and click **▶ Run Simulation**. The sliders are organized into groups:
+
+- **⚙️ Simulation Settings** — horizon length, number of SKUs, random seed, and pipeline multiplier; these define the scope of any run and are not specific to a scenario
+- **📈 Demand Scenario** — shock amplitude, burst frequency and size, AR persistence; primary levers for the ⚡ Demand Shock scenario
+- **🔴 Disruption** — edge to block, outage probability, duration; primary levers for the 🔴 Disruption scenario
+- **🚚 Supply & Network** — edge capacity, reorder thresholds, source lead times; primary levers for the 📦 Low Capacity scenario
+- **💰 Costs** — holding cost and backlog penalty; display-only annotations that do not affect simulation dynamics, but are recorded in the CSV export for post-hoc cost analysis
+
+The full simulator — where topology, catalogue size, demand model, replenishment policy, and routing are all user-configurable — is open-source at **https://github.com/tuhinsahai/ISOMORPH**.
+"""
+
+_LEARN_MORE = """
+ISOMORPH simulates the flow of multiple product types (each called a **Stock Keeping Unit, SKU**) through a directed network of factories, intermediate warehouses, and a customer-facing destination, advancing every location and link forward in discrete time.
+
+In each time step, random customer demand arrives at the destination, is served from available stock or recorded as **backlog**, and triggers replenishment orders that propagate back through the network. Shipments travel along directed edges with fixed transit times, are routed via **Dijkstra shortest-path**, packed greedily into **finite-capacity containers**, and restocked at each warehouse under **(s, S) reorder policies** — reorder up to level S when stock drops below reorder point s.
+
+Demand is driven by a **five-component signal**: a persistent AR(1) trend, a long-run drift, rare macro shocks shared across all SKUs (e.g. a holiday surge), independent per-item burst events, and Gaussian noise — producing the correlated, lumpy demand patterns characteristic of real logistics networks.
+
+The simulation is **stochastic**: demand draws, source lead times, and disruption timing are all random. Changing the **random seed** gives a different realization of the same scenario, enabling ensemble analysis and forward uncertainty quantification.
+"""
+
+_STATE_SPACE = """
+**Why ISOMORPH tracks more than just inventory — the "right state space"**
+
+Most supply-chain datasets record only how much stock sits at each location. ISOMORPH also records, at every simulated day: the replenishment orders currently outstanding with suppliers, the shipments traveling through the network, and a running smoothed estimate of recent demand — alongside on-hand inventory and backlog at every node. Together these five types of information form the **complete state** of the simulation.
+
+This matters because knowing only today's warehouse stock is not enough to predict tomorrow: a shipment already in transit will arrive regardless of what else happens, and a pending supplier order determines when restocking will occur. Without tracking these "invisible" quantities, the simulation would need to remember weeks of past history to make predictions. With all five, tomorrow depends only on today — the mathematical property called **Markovian** (a Markov chain).
+
+This "right state" design also enforces **three exact conservation laws** that hold on every simulated day, for every random scenario, with no approximation:
+1. Each node's inventory changes by exactly what arrives minus what ships.
+2. Total units inside the network change only when a supplier delivers or a customer is served.
+3. Backlog only grows when customer demand exceeds on-hand stock.
+
+These laws are built into the simulator's structure, not imposed afterward — so they serve as verification tools: any violation would indicate a bug, not a modeling choice.
+"""
+
+
+with gr.Blocks(
+    title="ISOMORPH Supply Chain Digital Twin",
+    css=_CSS,
+    theme=gr.themes.Soft(primary_hue="blue", neutral_hue="slate"),
+) as demo:
+
+    # ── State ────────────────────────────────────────────────────────────────
+    sim_state = gr.State(None)
+
+    # ── Header ───────────────────────────────────────────────────────────────
+    gr.Markdown("# ISOMORPH Supply Chain Digital Twin")
+    gr.Markdown(_DESCRIPTION)
+
+    with gr.Accordion("📖 Learn more about the simulator dynamics", open=False, elem_id="learn-more-accordion"):
+        gr.Markdown(_LEARN_MORE)
+    with gr.Accordion("🔢 Mathematical structure of the state space — the \"right state space\"", open=False, elem_id="state-space-accordion"):
+        gr.Markdown(_STATE_SPACE)
+
+    # ── Quick-preset buttons ─────────────────────────────────────────────────
+    with gr.Row():
+        gr.Markdown("**Quick presets:**")
+        btn_baseline  = gr.Button("🟢 Baseline",       size="sm", variant="secondary")
+        btn_shock     = gr.Button("⚡ Demand Shock",   size="sm", variant="secondary")
+        btn_disrupt   = gr.Button("🔴 Disruption",     size="sm", variant="secondary")
+        btn_low_cap   = gr.Button("📦 Low Capacity",   size="sm", variant="secondary")
+
+    gr.Markdown("---")
+
+    # ── Main layout: controls | results ──────────────────────────────────────
+    with gr.Row(equal_height=False):
+
+        # ── LEFT: Configuration panel ─────────────────────────────────────
+        with gr.Column(scale=1, min_width=280):
+
+            with gr.Accordion("⚙️ Simulation Settings", open=True):
+                c = {}   # dict of all input components (for easy callback wiring)
+
+                c["T"] = gr.Slider(
+                    10, 500, value=200, step=5,
+                    label="Horizon T (days)",
+                    info="Total simulation length. 200 days ≈ 7 months; enough to see seasonal patterns and bullwhip cycles. Keep ≤ 500 for fast response.",
+                )
+                c["n_items"] = gr.Slider(
+                    1, 5, value=3, step=1,
+                    label="Number of SKUs (Stock Keeping Units)",
+                    info="Each SKU is an independent product type with its own AR(1) demand, (s,S) reorder policy, and physical volume. More SKUs increases total network load.",
+                )
+                c["seed"] = gr.Number(
+                    value=42, label="Random seed", precision=0,
+                    info="Controls all stochastic draws (demand, shocks, bursts, lead times). Change this to get a different random realization of the same scenario.",
+                )
+                c["pipeline_mult"] = gr.Slider(
+                    0, 15, value=7.0, step=0.5,
+                    label="Pipeline multiplier",
+                    info="How many days of smoothed (EMA) demand are kept in the in-transit replenishment pipeline. Higher = more inventory pre-positioned; 0 = purely reactive (s,S) ordering.",
+                )
+
+            with gr.Accordion("📈 Demand Scenario", open=True):
+                c["phi_lo"] = gr.Slider(
+                    0.50, 0.999, value=0.95, step=0.01,
+                    label="Demand memory  φ  (AR coefficient)",
+                    info="Auto-regressive coefficient controlling demand persistence. Near 1.0 = slow, long trends (hard to forecast); near 0.5 = rapid mean-reverting fluctuations.",
+                )
+                c["shock_height_scale"] = gr.Slider(
+                    0.0, 6.0, value=1.0, step=0.1,
+                    label="Macro shock amplitude",
+                    info="Scales the height of rare, correlated demand spikes that hit all SKUs simultaneously (e.g. a holiday surge). 0 = no shocks; 4+ = severe shocks.",
+                )
+                c["burst_rate_scale"] = gr.Slider(
+                    0.0, 6.0, value=1.0, step=0.1,
+                    label="Idiosyncratic burst frequency",
+                    info="Scales how often individual-SKU demand bursts occur (independent across items). Higher = more frequent localized spikes.",
+                )
+                c["burst_height_scale"] = gr.Slider(
+                    0.0, 6.0, value=1.0, step=0.1,
+                    label="Idiosyncratic burst amplitude",
+                    info="Scales how large each individual-SKU burst is when it occurs.",
+                )
+
+            with gr.Accordion("🔴 Disruption", open=False):
+                c["disruption_edge"] = gr.Dropdown(
+                    choices=_EDGE_STRINGS,
+                    value="None  (no disruption)",
+                    label="Edge to disrupt",
+                    info="Select a directed shipping lane to subject to random outages. When triggered, that edge's capacity drops to zero for the disruption duration.",
+                )
+                c["disruption_prob"] = gr.Slider(
+                    0.0, 0.30, value=0.0, step=0.01,
+                    label="Disruption probability per day",
+                    info="Each day, a Bernoulli draw with this probability triggers a new disruption event (if none is currently active). 0.08 ≈ one event every ~13 days.",
+                )
+                c["disruption_duration"] = gr.Slider(
+                    1, 60, value=10, step=1,
+                    label="Disruption duration (days)",
+                    info="Number of consecutive days the edge is completely blocked once triggered. Marked as red dashed lines in the Node Detail and Edge Util plots.",
+                )
+
+            with gr.Accordion("🚚 Supply & Network", open=False):
+                c["containers_scale"] = gr.Slider(
+                    0.1, 3.0, value=1.0, step=0.1,
+                    label="Edge capacity scale",
+                    info="Multiplies the number of shipping containers available per edge per day. <1 = congested network (queuing, missed shipments); >1 = excess capacity (lower utilization).",
+                )
+                c["ss_scale"] = gr.Slider(
+                    0.1, 3.0, value=1.0, step=0.1,
+                    label="Reorder threshold  (s, S) scale",
+                    info="Scales both the reorder point s and the order-up-to level S at every warehouse. <1 = lean / just-in-time; >1 = large safety-stock buffers.",
+                )
+                c["leadtime_scale"] = gr.Slider(
+                    0.5, 10.0, value=1.0, step=0.5,
+                    label="Source lead-time scale",
+                    info="Multiplies the replenishment lead time at source nodes (SanFrancisco, StLouis, Orlando). High values simulate distant or slow suppliers and create longer supply gaps.",
+                )
+
+            with gr.Accordion("💰 Costs (display only)", open=False):
+                c["holding_cost"] = gr.Slider(
+                    0.1, 10.0, value=1.0, step=0.1,
+                    label="Inventory holding cost per unit per day",
+                    info="Cost of carrying one unit of stock for one day (warehousing, capital). Display only — does not affect simulation dynamics.",
+                )
+                c["backlog_penalty"] = gr.Slider(
+                    1.0, 20.0, value=5.0, step=0.5,
+                    label="Backlog penalty per unit per day",
+                    info="Penalty for each unit of unfulfilled demand per day (lost-sale cost, SLA breach). Display only — does not affect simulation dynamics.",
+                )
+
+            run_btn = gr.Button(
+                "▶  Run Simulation", variant="primary",
+                size="lg", elem_id="run-btn",
+            )
+            status_md = gr.Markdown(
+                "_Configure parameters above and click ▶ Run Simulation._"
+            )
+
+        # ── RIGHT: Results panel ──────────────────────────────────────────
+        with gr.Column(scale=2, min_width=560):
+
+            with gr.Tabs():
+
+                # Tab 1 — animated network map
+                with gr.Tab("🗺️ Network Map"):
+                    gr.Markdown(
+                        "This map shows the physical flow of goods across the US supply chain in real time."
+                        " Node colors reflect inventory health at every simulation day;"
+                        " moving dots trace shipments as they travel between facilities.\n\n"
+                        "**Node color** = backlog stress —"
+                        " <span style='color:#4CAF50'>■ green</span> (healthy)"
+                        " → <span style='color:#FFC107'>■ yellow</span> (building backlog)"
+                        " → <span style='color:#F44336'>■ red</span> (stockout)  \n"
+                        "**Node shape** = facility role —"
+                        " ★ destination · ■ last-mile DC · ● warehouse · ◆ Tier-2 · ⬡ hub · ▲ supplier  \n"
+                        "**Moving dot color** = which Stock Keeping Unit (SKU) is being shipped  \n"
+                        "**Edge thickness** = proportional to the daily shipping capacity of that lane\n\n\n"
+                        "**How to interact:**\n\n"
+                        "- ▶ **Play / scrub:** press **▶ Play** to animate through the simulation, or drag the day slider to jump to any point.\n"
+                        "- 🏭 **Hover over a node:** see its current total inventory and backlog counts.\n"
+                        "- 📦 **Hover over a moving dot:** see the shipment's origin, destination, quantity, and arrival day."
+                    )
+                    anim_plot = gr.HTML(label="Shipment propagation")
+                    with gr.Row():
+                        gif_btn = gr.Button(
+                            "⬇️ Export as GIF", variant="secondary", size="sm",
+                        )
+                        gr.Markdown(
+                            "_Renders up to 80 frames as a portable animated GIF "
+                            "(requires `kaleido` and `Pillow`). May take ~30 s._"
+                        )
+                    gif_dl = gr.File(label="Animated GIF", file_types=[".gif"])
+
+                # Tab 2 — node detail time series
+                with gr.Tab("📊 Node Detail"):
+                    gr.Markdown(
+                        "Shows the time history of inventory and material flows at one node across all simulation days."
+                        " Use this to trace how a facility responds to demand shocks, disruptions, or capacity constraints.\n\n"
+                        "**Inventory** = on-hand stock at this node (units)"
+                        " — state component (1), <b>OH<sup>n,i</sup><sub>t</sub></b>: integer count of item <i>i</i> held at node <i>n</i> on day <i>t</i>  \n"
+                        "**Backlog** = <span style='color:#c0392b'>unfulfilled demand</span> waiting to be served (units; non-zero means stock ran out)"
+                        " — state component (2), <b>B<sup>n,i</sup><sub>t</sub></b>: demand units owed; non-zero only at the destination  \n"
+                        "**Inflow** = units <span style='color:#2980b9'>arriving</span> per day"
+                        " — daily receipts <b>R<sup>n,i</sup><sub>t</sub></b>: the realization of component (4) IT<sub>t</sub>;"
+                        " at non-destination nodes R<sup>n,i</sup><sub>t</sub> = <i>q</i> when a pending order Out<sup>n,i</sup> = (<i>t</i>, <i>q</i>) matures;"
+                        " at the destination it is the subset of IT<sub>t</sub> whose arrival timestamp equals <i>t</i>  \n"
+                        "**Outflow** = units <span style='color:#27ae60'>dispatched</span> per day"
+                        " — daily dispatches <b>D<sup>n,i</sup><sub>t</sub></b>: units packed onto outgoing edges by the greedy bin-packing algorithm,"
+                        " driven by component (3) Out<sub>t</sub> and Dijkstra routing  \n"
+                        "**Demand** = actual customer orders received per day, <b><i>y</i><sub>i,t</sub></b>"
+                        " — external random input to the chain, not a state component; shown only at the destination (NewYork)."
+                        " Note: the internal <b>smoothed demand estimate</b> (state component 5),"
+                        " λ̃<sup>i</sup><sub>t+1</sub> = 0.05·<i>y</i><sub>i,t</sub> + 0.95·λ̃<sup>i</sup><sub>t</sub>,"
+                        " is the exponential moving average of <i>y</i><sub>i,t</sub> and is what drives replenishment order sizing — it is not plotted here  \n"
+                        "**<span style='color:rgba(255,80,80,0.9)'>Red dashed vertical line</span>**"
+                        " = day a disruption event was triggered on a connected edge\n\n\n"
+                        "Select a **Node** and an **Item (SKU)** from the dropdowns below. **How to read the panels:**\n\n"
+                        "- 📦 **Inventory + Backlog:** when inventory (panel 1) hits zero, backlog (panel 2) spikes — the node has run out of stock and is accumulating unfulfilled demand.\n"
+                        "- 🔄 **Inflow + Outflow:** when inflow (panel 3) persistently exceeds outflow (panel 4), the node is building up stock; when outflow exceeds inflow, it is drawing down reserves.\n"
+                        "- ⚡ **Demand (destination only):** compare demand (panel 5) with inflow (panel 3) — a lag between a demand spike and the inflow response reveals the end-to-end replenishment delay through the network."
+                    )
+                    with gr.Accordion("📐 About the Markov State — Mathematical Details", open=False, elem_id="markov-accordion"):
+                        gr.Markdown(
+                            "The simulation is a Markov chain whose full state at each day is "
+                            "ξ<sub>t</sub> = (OH<sub>t</sub>, B<sub>t</sub>, Out<sub>t</sub>, IT<sub>t</sub>, λ̃<sub>t</sub>) — five components: "
+                            "(1) on-hand inventory, (2) backlog, (3) outstanding supplier orders, (4) scheduled in-transit arrivals, and (5) smoothed demand estimate. "
+                            "Together these C(3N+1) = **120 fixed scalar dimensions** "
+                            "— where N = 13 nodes and C = 3 SKUs (Stock Keeping Units) for this simulation — "
+                            "(plus a variable-length in-transit list IT<sub>t</sub>) "
+                            "contain everything needed to determine the next day's state, with no reliance on history. "
+                            "The full ISOMORPH release provides datasets at catalogue sizes C = 50 and C = 200, corresponding to "
+                            "**≥ 2,000 and ≥ 8,000 fixed scalar state dimensions** respectively "
+                            "(see the <a href='https://arxiv.org/pdf/2605.12768' target='_blank'>ISOMORPH paper</a> for the complete state-space specification).\n\n"
+                            "This panel directly plots components (1) and (2). "
+                            "The remaining three components are not plotted directly, but their effects appear as the daily increment terms Inflow and Outflow, "
+                            "which satisfy the per-node conservation law:\n\n"
+                            "OH<sup>n,i</sup><sub>t+1</sub> = OH<sup>n,i</sup><sub>t</sub> + R<sup>n,i</sup><sub>t</sub> − D<sup>n,i</sup><sub>t</sub>\n\n"
+                            "This identity holds exactly on every simulated day — it is not an approximation but a structural invariant of the Markov chain. "
+                            "Any deviation would indicate a simulation bug, not a modeling choice."
+                        )
+                    with gr.Row():
+                        node_dd = gr.Dropdown(
+                            choices=_NODE_CHOICES,
+                            value="NewYork",
+                            label="Node",
+                            info="13 nodes by tier — NewYork: destination · Philadelphia, Baltimore: last-mile DCs · Columbus, Richmond: tier-4 · Charlotte, Chicago, Memphis: tier-3 · Atlanta: tier-2 · Nashville: hub · SanFrancisco, StLouis, Orlando: suppliers",
+                            scale=2,
+                        )
+                        item_filter_dd = gr.Dropdown(
+                            choices=["All items"],
+                            value="All items",
+                            label="Item (SKU)",
+                            info="Stock Keeping Unit — a distinct product type. Show all SKUs overlaid, or isolate one to remove clutter.",
+                            scale=1,
+                        )
+                    ts_plot = gr.Plot(label="Time series")
+
+                # Tab 3 — bullwhip chart
+                with gr.Tab("📈 Bullwhip"):
+                    gr.Markdown(
+                        'Measures how much demand variability amplifies as orders travel upstream — the "bullwhip effect."'
+                        " Replenishment decisions made with delayed inventory information, lead-time uncertainty, and lumpy (s,S) ordering"
+                        " can cause upstream order variability to exceed downstream demand variability — but the pattern is not always a"
+                        " simple monotone staircase. **Amplification can be uneven, selective, or even locally suppressed depending on"
+                        " the scenario and the network topology** — which nodes connect to which, and how many paths exist between tiers.\n\n"
+                        "**Bar height** = B = Var(inflow) / Var(outflow), averaged over all nodes in that tier  \n"
+                        "**<span style='color:#555'>&#9135;&#9135; Dashed line at B = 1</span>**"
+                        " = no-amplification baseline; each tier passes demand through unchanged  \n"
+                        "**<span style='color:#c0392b'>B &gt; 1</span>**"
+                        " = orders placed at that tier are more variable than the downstream demand that triggered them  \n"
+                        "**<span style='color:#2980b9'>B &lt; 1</span>**"
+                        " = that tier smooths variability — can occur when bottlenecks suppress flow propagation  \n"
+                        "**Tier axis** = <span style='color:#2980b9'>NewYork (downstream, left)</span>"
+                        " → <span style='color:#c0392b'>Suppliers (upstream, right)</span>  \n"
+                        "**Bar color** = one distinct color per Stock Keeping Unit (SKU)\n\n\n"
+                        "**What to expect across scenarios:**\n\n"
+                        "- 🟢 **Baseline:** the network already exhibits a clear bullwhip effect without any externally imposed shocks."
+                        " Amplification is not uniform — specific tiers, particularly last-mile replenishment nodes, may become dominant"
+                        " variability amplifiers as local ordering policies interact with transportation delays and inventory thresholds."
+                        " Complex upstream variability emerges internally from otherwise stable conditions.\n"
+                        "- ⚡ **Demand Shock:** macro shocks and per-SKU bursts inject additional variability at the destination."
+                        " Upstream tiers respond with larger replenishment swings as delayed information and transport lags compound the fluctuations.\n"
+                        "- 🔴 **Disruption:** the pattern becomes mixed. Some tiers may temporarily show B < 1 because transport bottlenecks"
+                        " suppress downstream flow propagation. Other tiers exhibit sharp amplification as delayed replenishment creates"
+                        " catch-up ordering waves once the disruption clears.\n"
+                        "- 📦 **Low Capacity:** congestion and stockouts generate highly lumpy replenishment behavior."
+                        " Extreme amplification can appear at selected tiers, where recovery orders become much larger and more variable"
+                        " than the original downstream demand signal."
+                    )
+                    bw_plot = gr.Plot(label="Bullwhip amplification")
+
+                # Tab 4 — edge utilization heatmap
+                with gr.Tab("🔥 Edge Util"):
+                    gr.Markdown(
+                        "Shows which shipping lanes are busy, congested, or completely blocked at each simulation day."
+                        " Persistent congestion on a lane starves downstream nodes and propagates stockouts forward.\n\n"
+                        "**Row** = one directed shipping lane (upstream node → downstream node)  \n"
+                        "**Column** = simulation day  \n"
+                        "**Cell color** = fraction of daily shipping capacity used —"
+                        " <span style='color:#5b9bd5'>■ light blue</span> (near-empty)"
+                        " → <span style='color:#e67e22'>■ orange</span> (~50%)"
+                        " → <span style='color:#c0392b'>■ red</span> (saturated at 100%)  \n"
+                        "**<span style='color:#2980b9'>Blue dashed vertical line</span>**"
+                        " = day a disruption event blocked this lane (capacity dropped to zero)\n\n\n"
+                        "**How to read the heatmap:**\n\n"
+                        "- 🔴 **Red bands:** persistent red on a lane means it is chronically saturated, forcing upstream nodes to stockpile or reroute goods via longer alternate paths.\n"
+                        "- 🔍 **Locate the bottleneck:** compare the last-mile lanes (Philadelphia/Baltimore → NewYork) with upstream lanes — the lane that stays red longest is the binding constraint.\n"
+                        "- 🔵 **Disruption events:** enable a disruption in the left panel and re-run to see blue dashed markers appear on the day each outage was triggered."
+                    )
+                    heat_plot = gr.Plot(label="Edge utilization")
+
+                # Tab 5 — download
+                with gr.Tab("⬇️ Download"):
+                    gr.Markdown(
+                        "Click **Prepare CSV** to generate a downloadable file "
+                        "containing inventory, backlog, inflow, and outflow "
+                        "for every node and item at every time step."
+                    )
+                    dl_btn  = gr.Button("Prepare CSV", variant="secondary")
+                    csv_dl  = gr.File(label="Download", file_types=[".csv"])
+
+    # =========================================================================
+    # Callback wiring
+    # =========================================================================
+
+    _inputs = _all_inputs(c)
+
+    # ── Outputs returned by run_sim ───────────────────────────────────────────
+    _run_outputs = [
+        sim_state, anim_plot, ts_plot, bw_plot, heat_plot,
+        status_md, item_filter_dd,
+    ]
+
+    # api_name=False on every handler suppresses Gradio's JSON-schema
+    # introspection, which crashes on Python 3.9 + Gradio 4.44 when a
+    # gr.State holds a complex dataclass (TypeError: 'bool' not iterable).
+    run_btn.click(
+        fn=run_sim,
+        inputs=_inputs,
+        outputs=_run_outputs,
+        api_name=False,
+    )
+
+    # ── Quick preset buttons (set knobs then run) ─────────────────────────────
+    def _preset(name: str):
+        vals = _PRESETS[name]
+        result_vals = run_sim(*vals)
+        return list(vals) + list(result_vals)
+
+    _preset_slider_outputs = [
+        c["T"], c["n_items"], c["seed"], c["pipeline_mult"],
+        c["phi_lo"], c["shock_height_scale"],
+        c["burst_rate_scale"], c["burst_height_scale"],
+        c["containers_scale"], c["ss_scale"], c["leadtime_scale"],
+        c["disruption_edge"], c["disruption_prob"], c["disruption_duration"],
+        c["holding_cost"], c["backlog_penalty"],
+    ]
+
+    for btn, name in [
+        (btn_baseline, "baseline"),
+        (btn_shock,    "demand_shock"),
+        (btn_disrupt,  "disruption"),
+        (btn_low_cap,  "low_capacity"),
+    ]:
+        btn.click(
+            fn=lambda n=name: _preset(n),
+            inputs=[],
+            outputs=_preset_slider_outputs + _run_outputs,
+            api_name=False,
+        )
+
+    # ── Node / item selection updates time series ─────────────────────────────
+    node_dd.change(
+        fn=update_timeseries,
+        inputs=[sim_state, node_dd, item_filter_dd],
+        outputs=[ts_plot],
+        api_name=False,
+    )
+    item_filter_dd.change(
+        fn=update_timeseries,
+        inputs=[sim_state, node_dd, item_filter_dd],
+        outputs=[ts_plot],
+        api_name=False,
+    )
+
+    # ── CSV download ──────────────────────────────────────────────────────────
+    dl_btn.click(
+        fn=prepare_download,
+        inputs=[sim_state],
+        outputs=[csv_dl],
+        api_name=False,
+    )
+
+    # ── GIF export ────────────────────────────────────────────────────────────
+    gif_btn.click(
+        fn=generate_gif,
+        inputs=[sim_state],
+        outputs=[gif_dl],
+        api_name=False,
+    )
+
+    # ── Auto-run baseline on page load ────────────────────────────────────────
+    demo.load(
+        fn=lambda: _preset("baseline"),
+        inputs=[],
+        outputs=_preset_slider_outputs + _run_outputs,
+        api_name=False,
+    )
+
+
+# ============================================================================
+# Entry point
+# ============================================================================
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+    )

demo/visualize.py

@@ -0,0 +1,946 @@
+"""
+ISOMORPH Demo — Visualization Module
+=====================================
+All functions return plotly.graph_objects.Figure objects for rendering in
+Gradio gr.Plot components.
+
+Public API
+----------
+    make_network_animation(result, frame_step=None)
+        Animated US map: shipment particles travel along edges, nodes colored
+        by backlog stress.  Play / Pause controls + scrubber slider.
+
+    make_node_timeseries(result, node_id, item_ids=None)
+        Subplot panel for one node: inventory, backlog, inflow, outflow,
+        and (at the destination) realized demand.
+
+    make_bullwhip_chart(result)
+        Bar chart of mean B = Var(inflow)/Var(outflow) per tier, from
+        destination (left) to hub/sources (right).
+
+    make_edge_heatmap(result)
+        Heatmap of edge utilization (fraction of daily capacity) over time.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+# ── Color constants ───────────────────────────────────────────────────────────
+
+# One color per item (up to 5) — matplotlib tab10 subset
+ITEM_COLORS = ["#1f77b4", "#ff7f0e", "#2ca02c", "#9467bd", "#d62728"]
+
+# Node stress: green (0 = no backlog) → yellow → red (1 = all backlog)
+NODE_COLORSCALE = [[0.0, "#4CAF50"], [0.35, "#FFC107"], [1.0, "#F44336"]]
+
+# Visual size of node marker by tier
+_TIER_MARKER_SIZE = {0: 22, 1: 16, 2: 13, 3: 13, 4: 15, 5: 18, 6: 11}
+
+# Human-readable tier labels (for bullwhip x-axis)
+_TIER_LABEL = {
+    0: "Destination",
+    1: "Last-mile",
+    2: "Tier-4",
+    3: "Tier-3",
+    4: "Tier-2<br>(Atlanta)",
+    5: "Hub<br>(Nashville)",
+    6: "Sources",
+}
+
+# Descriptive role name shown in hover tooltip and node-type legend
+_TIER_TYPE_NAME = {
+    0: "Destination (end customer)",
+    1: "Last-mile DC",
+    2: "Tier-4 Warehouse",
+    3: "Tier-3 Warehouse",
+    4: "Tier-2 Warehouse (Atlanta)",
+    5: "Regional Hub (Nashville)",
+    6: "Source / Supplier",
+}
+
+# Plotly Scattergeo marker symbol per tier — visually distinguishes role
+_TIER_SYMBOL = {
+    0: "star",          # Destination — prominent star
+    1: "square",        # Last-mile DCs
+    2: "circle",        # Tier-4 warehouses
+    3: "circle",        # Tier-3 warehouses
+    4: "diamond",       # Tier-2 (Atlanta pivot)
+    5: "hexagram",      # Hub (Nashville)
+    6: "triangle-up",   # Source suppliers
+}
+
+
+# ============================================================================
+# Private helpers
+# ============================================================================
+
+def _edge_travel_times(result) -> Dict[Tuple[str, str], float]:
+    """Derive edge travel times from the first shipment that uses each hop."""
+    tt: Dict[Tuple[str, str], float] = {}
+    for s in result.shipments:
+        path = s["path_nodes"]
+        ets  = s["edge_times"]
+        for h in range(len(ets)):
+            hop = (path[h], path[h + 1])
+            if hop not in tt:
+                tt[hop] = float(ets[h])
+            if len(tt) == len(result.edge_ids):
+                return tt   # early exit once all edges covered
+    return tt
+
+
+def _node_stress(result, t: int) -> List[float]:
+    """
+    Return a per-node backlog-fraction in [0, 1] at timestep t.
+    stress = total_backlog / (total_backlog + total_inventory + 1)
+    Ordered to match result.node_ids.
+    """
+    fracs = []
+    for nid in result.node_ids:
+        bl  = sum(int(result.backlog[nid][iid][t])  for iid in result.item_ids)
+        inv = sum(int(result.inventory[nid][iid][t]) for iid in result.item_ids)
+        fracs.append(bl / max(bl + inv, 1))
+    return fracs
+
+
+def _node_hover_custom(result, t: int,
+                       type_names: Optional[List[str]] = None) -> List[List]:
+    """
+    Return per-node customdata rows [inv, bl, type_name] at time t.
+    type_names (static) is passed once and repeated in every frame so the
+    hovertemplate can reference %{customdata[2]}.
+    """
+    rows = []
+    for i, nid in enumerate(result.node_ids):
+        inv = sum(int(result.inventory[nid][iid][t]) for iid in result.item_ids)
+        bl  = sum(int(result.backlog[nid][iid][t])  for iid in result.item_ids)
+        tname = type_names[i] if type_names else ""
+        rows.append([inv, bl, tname])
+    return rows
+
+
+def _interpolate_position(
+    shipment: dict,
+    t: int,
+    node_coords: Dict[str, Tuple[float, float]],
+) -> Optional[Tuple[float, float]]:
+    """
+    Return (lat, lon) for a shipment at integer day t, or None if not active.
+    The particle travels along path_nodes using edge_times for timing.
+    """
+    d = shipment["day"]
+    a = shipment["arrival_day"]
+    if t < d or t >= a:
+        return None
+    path = shipment["path_nodes"]
+    ets  = shipment["edge_times"]
+    elapsed = float(t - d)
+    cum = 0.0
+    for h, tt in enumerate(ets):
+        tt = float(tt)
+        if elapsed <= cum + tt + 1e-9:
+            frac = (elapsed - cum) / max(tt, 1e-6)
+            frac = max(0.0, min(1.0, frac))
+            lat_a, lon_a = node_coords[path[h]]
+            lat_b, lon_b = node_coords[path[h + 1]]
+            return lat_a + frac * (lat_b - lat_a), lon_a + frac * (lon_b - lon_a)
+        cum += tt
+    return None
+
+
+def _frame_particles(result, t: int, item_filter: Optional[str] = None):
+    """
+    Return (lats, lons, texts, colors) for all active shipment particles
+    at timestep t.  colors is a list of CSS color strings keyed by item.
+    """
+    item_color_map = {iid: ITEM_COLORS[i % len(ITEM_COLORS)]
+                      for i, iid in enumerate(result.item_ids)}
+    lats, lons, texts, colors = [], [], [], []
+    for s in result.shipments:
+        if item_filter and s["item"] != item_filter:
+            continue
+        pos = _interpolate_position(s, t, result.node_coords)
+        if pos is None:
+            continue
+        lat, lon = pos
+        lats.append(lat)
+        lons.append(lon)
+        texts.append(
+            f"<b>{s['item']}</b><br>{s['from']}→{s['to']}<br>"
+            f"qty: {s['units']}  day {s['day']}→{s['arrival_day']}"
+        )
+        colors.append(item_color_map[s["item"]])
+    return lats, lons, texts, colors
+
+
+def _bullwhip_ratios(result) -> Dict[str, Dict[str, float]]:
+    """
+    Compute B_(n,i) = Var(inflow_(n,i)) / Var(outflow_(n,i)) per node/item.
+    At the destination node outflow is replaced by customer demand.
+    Source nodes (tier 6) are excluded (no inflow on network edges).
+    """
+    dest_id = next(
+        nid for nid in result.node_ids if result.tier.get(nid) == 0
+    )
+    ratios: Dict[str, Dict[str, float]] = {}
+    for nid in result.node_ids:
+        tier = result.tier.get(nid, -1)
+        if tier == 6:
+            continue
+        ratios[nid] = {}
+        for iid in result.item_ids:
+            inflow_arr  = result.inflow[nid][iid].astype(float)
+            if nid == dest_id:
+                outflow_arr = result.demand[iid].astype(float)
+            else:
+                outflow_arr = result.outflow[nid][iid].astype(float)
+            var_in  = float(np.var(inflow_arr,  ddof=1)) if result.T > 1 else 0.0
+            var_out = float(np.var(outflow_arr, ddof=1)) if result.T > 1 else 0.0
+            if var_out > 1.0:   # guard against near-zero outflow variance
+                ratios[nid][iid] = var_in / var_out
+    return ratios
+
+
+# ============================================================================
+# 1.  Animated network map
+# ============================================================================
+
+def make_network_animation(
+    result,
+    frame_step: Optional[int] = None,
+    frame_duration_ms: int = 150,
+) -> go.Figure:
+    """
+    Animated Scattergeo map of the supply-chain network.
+
+    Parameters
+    ----------
+    result : SimResult
+    frame_step : int or None
+        Days between animation frames.  Auto-computed to cap at ~200 frames.
+    frame_duration_ms : int
+        Milliseconds per frame during playback.
+    """
+    T = result.T
+    max_frames = 200
+    if frame_step is None:
+        frame_step = max(1, T // max_frames)
+    frame_times = list(range(0, T, frame_step))
+
+    node_ids   = result.node_ids
+    coords     = result.node_coords
+    edge_tt    = _edge_travel_times(result)
+
+    # ── Node metadata ──────────────────────────────────────────────────────
+    node_lats       = [coords[n][0] for n in node_ids]
+    node_lons       = [coords[n][1] for n in node_ids]
+    node_sizes      = [_TIER_MARKER_SIZE.get(result.tier.get(n, 3), 13)
+                       for n in node_ids]
+    node_labels     = node_ids
+    node_type_names = [_TIER_TYPE_NAME.get(result.tier.get(n, -1), "Warehouse")
+                       for n in node_ids]
+    node_symbols    = [_TIER_SYMBOL.get(result.tier.get(n, 3), "circle")
+                       for n in node_ids]
+
+    # ── Edge traces (static) ───────────────────────────────────────────────
+    edge_traces = []
+    max_cap = max(result.edge_cap.values()) if result.edge_cap else 1.0
+    for eid in result.edge_ids:
+        u, v  = eid
+        if u not in coords or v not in coords:
+            continue
+        cap  = result.edge_cap.get(eid, 1.0)
+        lw   = 1.0 + 3.5 * (cap / max_cap) ** 0.5
+        tt   = edge_tt.get(eid, "?")
+        edge_traces.append(go.Scattergeo(
+            lat=[coords[u][0], coords[v][0], None],
+            lon=[coords[u][1], coords[v][1], None],
+            mode="lines",
+            line=dict(width=lw, color="rgba(140,140,160,0.55)"),
+            hoverinfo="text",
+            text=f"{u} → {v}<br>travel: {tt} day(s)<br>daily cap: {cap:.0f} units",
+            showlegend=False,
+            name=f"{u}→{v}",
+        ))
+    n_edge_traces = len(edge_traces)
+
+    # ── Initial node trace (t=0) ───────────────────────────────────────────
+    stress_0   = _node_stress(result, 0)
+    custom_0   = _node_hover_custom(result, 0, node_type_names)
+    node_trace = go.Scattergeo(
+        lat=node_lats,
+        lon=node_lons,
+        mode="markers+text",
+        text=node_labels,
+        textposition="top center",
+        textfont=dict(size=9, color="black"),
+        marker=dict(
+            size=node_sizes,
+            symbol=node_symbols,
+            color=stress_0,
+            colorscale=NODE_COLORSCALE,
+            cmin=0.0, cmax=1.0,
+            colorbar=dict(
+                title="Backlog<br>stress",
+                thickness=12,
+                len=0.5,
+                x=1.01,
+                tickvals=[0, 0.5, 1],
+                ticktext=["0 (healthy)", "0.5", "1 (stockout)"],
+                tickfont=dict(size=9),
+            ),
+            line=dict(width=1.5, color="white"),
+        ),
+        customdata=custom_0,
+        hovertemplate=(
+            "<b>%{text}</b><br>"
+            "Role: %{customdata[2]}<br>"
+            "Total inventory: %{customdata[0]:,} units<br>"
+            "Total backlog: %{customdata[1]:,} units<br>"
+            "<extra></extra>"
+        ),
+        showlegend=False,
+        name="nodes",
+    )
+
+    # ── Initial shipment trace (t=0) ───────────────────────────────────────
+    lats0, lons0, texts0, colors0 = _frame_particles(result, 0)
+    ship_trace = go.Scattergeo(
+        lat=lats0,
+        lon=lons0,
+        mode="markers",
+        marker=dict(size=7, color=colors0, opacity=0.85,
+                    line=dict(width=0.5, color="white")),
+        hoverinfo="text",
+        text=texts0,
+        showlegend=False,
+        name="shipments",
+    )
+
+    # ── Legend: item colors (shipment dots) ──────────────────────────────
+    item_legend_traces = []
+    for i, iid in enumerate(result.item_ids):
+        item_legend_traces.append(go.Scattergeo(
+            lat=[None], lon=[None],
+            mode="markers",
+            marker=dict(size=9, color=ITEM_COLORS[i % len(ITEM_COLORS)],
+                        symbol="circle"),
+            name=iid,
+            legendgrouptitle_text="Shipment items" if i == 0 else None,
+            legendgroup="items",
+            showlegend=True,
+        ))
+
+    # ── Legend: node-type symbols ─────────────────────────────────────────
+    # One proxy trace per distinct tier present in this result.
+    seen_tiers: dict = {}
+    for n in node_ids:
+        t_val = result.tier.get(n, -1)
+        if t_val not in seen_tiers:
+            seen_tiers[t_val] = (_TIER_TYPE_NAME.get(t_val, "Unknown"),
+                                 _TIER_SYMBOL.get(t_val, "circle"))
+    node_type_legend_traces = []
+    for i, (t_val, (tname, sym)) in enumerate(
+            sorted(seen_tiers.items(), key=lambda x: x[0])):
+        node_type_legend_traces.append(go.Scattergeo(
+            lat=[None], lon=[None],
+            mode="markers",
+            marker=dict(size=10, color="gray", symbol=sym),
+            name=tname,
+            legendgrouptitle_text="Node types" if i == 0 else None,
+            legendgroup="node_types",
+            showlegend=True,
+        ))
+
+    # ── Assemble base figure ───────────────────────────────────────────────
+    all_traces = (edge_traces + [node_trace, ship_trace]
+                  + item_legend_traces + node_type_legend_traces)
+    fig = go.Figure(data=all_traces)
+    # Trace indices of dynamic traces (edge + node + ship; legend traces follow)
+    idx_nodes = n_edge_traces
+    idx_ships = n_edge_traces + 1
+
+    # ── Pre-compute frames ─────────────────────────────────────────────────
+    frames = []
+    for t in frame_times:
+        stress_t = _node_stress(result, t)
+        custom_t = _node_hover_custom(result, t, node_type_names)
+        lats_t, lons_t, texts_t, colors_t = _frame_particles(result, t)
+
+        frames.append(go.Frame(
+            data=[
+                # Plain dicts avoid serialising default None lat/lon values
+                # that go.Scattergeo() would inject and confuse Plotly.js.
+                {"type": "scattergeo",
+                 "marker": {"color": stress_t},
+                 "customdata": custom_t},
+                {"type": "scattergeo",
+                 "lat": lats_t, "lon": lons_t,
+                 "text": texts_t,
+                 "marker": {"color": colors_t, "size": 7, "opacity": 0.85}},
+            ],
+            traces=[idx_nodes, idx_ships],
+            layout={"title": {"text": f"<b>ISOMORPH Supply Chain</b>  —  Day {t} / {T - 1}"}},
+            name=str(t),
+        ))
+    fig.frames = frames
+
+    # ── Slider steps ──────────────────────────────────────────────────────
+    slider_steps = [
+        dict(
+            method="animate",
+            args=[[str(t)],
+                  dict(mode="immediate",
+                       frame=dict(duration=0, redraw=True),
+                       transition=dict(duration=0))],
+            label=str(t),
+        )
+        for t in frame_times
+    ]
+
+    # ── Layout ────────────────────────────────────────────────────────────
+    fig.update_layout(
+        title=dict(
+            text=f"<b>ISOMORPH Supply Chain</b>  —  Day 0 / {T - 1}",
+            x=0.5, xanchor="center", font=dict(size=14),
+        ),
+        geo=dict(
+            scope="usa",
+            projection_type="albers usa",
+            showland=True, landcolor="rgb(243,243,243)",
+            showlakes=True, lakecolor="rgb(210,230,255)",
+            showrivers=True, rivercolor="rgb(210,230,255)",
+            showcoastlines=True, coastlinecolor="rgb(180,180,200)",
+            showsubunits=True, subunitcolor="rgb(200,200,215)",
+            bgcolor="rgba(255,255,255,0)",
+        ),
+        legend=dict(
+            x=0.01, y=0.01,
+            bgcolor="rgba(255,255,255,0.82)",
+            bordercolor="lightgray", borderwidth=1,
+            font=dict(size=9),
+            tracegroupgap=6,
+        ),
+        updatemenus=[dict(
+            type="buttons",
+            showactive=False,
+            y=1.08, x=0.0, xanchor="left",
+            buttons=[
+                dict(
+                    label="▶  Play",
+                    method="animate",
+                    args=[None, dict(
+                        frame=dict(duration=frame_duration_ms, redraw=True),
+                        fromcurrent=True,
+                        transition=dict(duration=0),
+                    )],
+                ),
+                dict(
+                    label="⏸  Pause",
+                    method="animate",
+                    args=[[None], dict(
+                        frame=dict(duration=0, redraw=False),
+                        mode="immediate",
+                        transition=dict(duration=0),
+                    )],
+                ),
+            ],
+        )],
+        sliders=[dict(
+            currentvalue=dict(
+                prefix="Day: ",
+                font=dict(size=11),
+                visible=True,
+                xanchor="center",
+            ),
+            pad=dict(t=50, b=10),
+            len=0.9,
+            x=0.05,
+            steps=slider_steps,
+            transition=dict(duration=0),
+        )],
+        margin=dict(l=0, r=0, t=80, b=60),
+        height=540,
+        paper_bgcolor="white",
+    )
+    return fig
+
+
+# ============================================================================
+# 2.  Node detail time-series panel
+# ============================================================================
+
+def make_node_timeseries(
+    result,
+    node_id: str,
+    item_ids: Optional[List[str]] = None,
+) -> go.Figure:
+    """
+    4–5 subplot panel for a single node showing inventory, backlog, inflow,
+    outflow, and (destination only) realized demand.
+
+    Parameters
+    ----------
+    result : SimResult
+    node_id : str
+        Node to visualise.
+    item_ids : list[str] or None
+        Subset of items to plot.  Defaults to all items in result.
+    """
+    if item_ids is None:
+        item_ids = result.item_ids
+
+    dest_id    = next(n for n in result.node_ids if result.tier.get(n) == 0)
+    is_dest    = (node_id == dest_id)
+    # Use plain Python lists — avoids numpy int32/int64 serialization issues
+    # inside Gradio 4.x's gr.Plot JSON path.
+    days       = list(range(result.T))
+    n_panels   = 5 if is_dest else 4
+
+    panel_titles = [
+        "On-hand inventory  (units stored at this node)",
+        "Backlog  (unfulfilled demand pending)",
+        "Inflow  (units arriving per day)",
+        "Outflow  (units shipped out per day)",
+    ]
+    if is_dest:
+        panel_titles.append("Realized demand  (customer orders received per day)")
+
+    fig = make_subplots(
+        rows=n_panels, cols=1,
+        shared_xaxes=True,
+        subplot_titles=panel_titles,
+        vertical_spacing=0.06,
+    )
+
+    for idx, iid in enumerate(item_ids):
+        color = ITEM_COLORS[idx % len(ITEM_COLORS)]
+
+        # Capture loop variables by value via default args to avoid closure issues.
+        def _add(row, y_arr, dash="solid", _iid=iid, _color=color):
+            fig.add_trace(
+                go.Scatter(
+                    x=days,
+                    y=y_arr.tolist(),   # convert np.int32 → Python ints
+                    mode="lines",
+                    name=_iid,
+                    line=dict(color=_color, width=1.5, dash=dash),
+                    legendgroup=_iid,
+                    showlegend=(row == 1),
+                    hovertemplate=f"Day %{{x}}<br>{_iid}: %{{y:,.0f}}<extra></extra>",
+                ),
+                row=row, col=1,
+            )
+
+        _add(1, result.inventory[node_id][iid])
+        _add(2, result.backlog[node_id][iid])
+        _add(3, result.inflow[node_id][iid])
+        _add(4, result.outflow[node_id][iid])
+        if is_dest:
+            _add(5, result.demand[iid], dash="dot")
+
+    # Disruption event markers — one vline per panel.
+    # add_vline(row=, col=) was not available in all Plotly 5.x builds;
+    # iterate over subplot y-axis references instead.
+    if result.disruption_log:
+        yref_list = ["y"] + [f"y{i}" for i in range(2, n_panels + 1)]
+        for ev in result.disruption_log:
+            for yref in yref_list:
+                fig.add_shape(
+                    type="line",
+                    x0=ev["day"], x1=ev["day"],
+                    y0=0, y1=1,
+                    xref="x", yref=f"{yref} domain",
+                    line=dict(dash="dash", color="rgba(255,80,80,0.5)", width=1),
+                )
+
+    # Panel y-axis labels
+    y_labels = ["Units", "Units", "Units/day", "Units/day"]
+    if is_dest:
+        y_labels.append("Units/day")
+    for row, lbl in enumerate(y_labels, start=1):
+        fig.update_yaxes(title_text=lbl, row=row, col=1,
+                         title_font=dict(size=10), tickfont=dict(size=9))
+
+    fig.update_xaxes(title_text="Day", row=n_panels, col=1,
+                     tickfont=dict(size=9))
+
+    tier_name  = _TIER_LABEL.get(result.tier.get(node_id, -1), "")
+    type_name  = _TIER_TYPE_NAME.get(result.tier.get(node_id, -1), "")
+    disruption_note = (
+        "  ·  <span style='color:rgba(255,80,80,0.9)'>red dashes = disruption events</span>"
+        if result.disruption_log else ""
+    )
+    fig.update_layout(
+        title=dict(
+            text=(f"<b>{node_id}</b>  —  {type_name}"
+                  f"{disruption_note}"),
+            x=0.5, xanchor="center", font=dict(size=13),
+        ),
+        legend=dict(
+            title="Items (SKUs)",
+            x=1.01, y=1.0,
+            font=dict(size=10),
+            bgcolor="rgba(255,255,255,0.8)",
+            bordercolor="lightgray", borderwidth=1,
+        ),
+        height=180 * n_panels + 80,
+        paper_bgcolor="white",
+        plot_bgcolor="rgba(248,248,252,1)",
+        margin=dict(l=60, r=120, t=60, b=50),
+    )
+    # Light grid
+    fig.update_xaxes(showgrid=True, gridcolor="rgba(200,200,220,0.5)")
+    fig.update_yaxes(showgrid=True, gridcolor="rgba(200,200,220,0.5)")
+    return fig
+
+
+# ============================================================================
+# 3.  Bullwhip amplification chart
+# ============================================================================
+
+def make_bullwhip_chart(result) -> go.Figure:
+    """
+    Bar chart of tier-level bullwhip ratio B = Var(inflow)/Var(outflow).
+    Bars are grouped by item; tiers run from destination (left) to hub (right).
+    A dashed reference line at B = 1 marks the no-amplification baseline.
+    """
+    ratios = _bullwhip_ratios(result)
+
+    # Collect tiers present (excluding sources, tier 6)
+    tiers_present = sorted(
+        {result.tier[n] for n in ratios if ratios[n]},
+    )
+
+    # Per-item bar traces
+    fig = go.Figure()
+    for idx, iid in enumerate(result.item_ids):
+        tier_means = []
+        for t in tiers_present:
+            nodes_in_tier = [n for n in ratios
+                             if result.tier.get(n) == t and iid in ratios[n]]
+            if nodes_in_tier:
+                tier_means.append(
+                    float(np.mean([ratios[n][iid] for n in nodes_in_tier]))
+                )
+            else:
+                tier_means.append(None)
+
+        x_labels = [_TIER_LABEL.get(t, f"Tier {t}") for t in tiers_present]
+        fig.add_trace(go.Bar(
+            x=x_labels,
+            y=tier_means,
+            name=iid,
+            marker_color=ITEM_COLORS[idx % len(ITEM_COLORS)],
+            opacity=0.82,
+            text=[f"{v:.2f}" if v is not None else "" for v in tier_means],
+            textposition="outside",
+            textfont=dict(size=9),
+        ))
+
+    # Reference line at B = 1
+    fig.add_hline(
+        y=1.0, line_dash="dash",
+        line_color="rgba(80,80,80,0.6)", line_width=1.5,
+        annotation_text="B = 1  (no amplification)",
+        annotation_position="top right",
+        annotation_font_size=9,
+    )
+
+    fig.update_layout(
+        title=dict(
+            text=(
+                "<b>Bullwhip Amplification by Tier</b><br>"
+                "<sup>B &gt; 1 means demand variability grows as orders travel upstream</sup>"
+            ),
+            x=0.5, xanchor="center", font=dict(size=13),
+        ),
+        xaxis=dict(
+            title="Network tier  (NewYork = downstream  →  Suppliers = upstream)",
+            title_font=dict(size=11),
+            tickfont=dict(size=10),
+        ),
+        yaxis=dict(
+            title="B = Var(inflow) / Var(outflow)",
+            title_font=dict(size=11),
+            tickfont=dict(size=9),
+            rangemode="tozero",
+        ),
+        barmode="group",
+        legend=dict(
+            title="Items",
+            x=1.01, y=1.0,
+            font=dict(size=10),
+            bgcolor="rgba(255,255,255,0.8)",
+            bordercolor="lightgray", borderwidth=1,
+        ),
+        height=400,
+        paper_bgcolor="white",
+        plot_bgcolor="rgba(248,248,252,1)",
+        margin=dict(l=60, r=120, t=60, b=60),
+    )
+    fig.update_yaxes(showgrid=True, gridcolor="rgba(200,200,220,0.5)")
+    return fig
+
+
+# ============================================================================
+# 4.  Edge utilization heatmap
+# ============================================================================
+
+def make_edge_heatmap(result) -> go.Figure:
+    """
+    Heatmap of edge utilization (fraction of daily capacity) over time.
+    Y-axis: edges sorted downstream→upstream.
+    X-axis: simulation day.
+    Color: 0 (white/green) = empty → 1 (red) = at capacity.
+    Disruption events are shown as vertical dashed lines.
+    """
+    # Sort edges: downstream edges first (by tier of source node)
+    def _edge_tier(eid):
+        return result.tier.get(eid[0], 99)
+
+    sorted_edges = sorted(result.edge_ids, key=_edge_tier)
+
+    edge_labels = [f"{u} → {v}" for u, v in sorted_edges]
+    z = np.array([result.edge_util[eid] for eid in sorted_edges],
+                 dtype=np.float64)   # shape (n_edges, T)
+
+    days = list(range(result.T))
+
+    fig = go.Figure(go.Heatmap(
+        z=z.tolist(),
+        x=days,
+        y=edge_labels,
+        colorscale=[
+            [0.0,  "rgb(240,248,255)"],   # near-empty: very light blue
+            [0.5,  "rgb(255,200,100)"],   # half full: yellow-orange
+            [1.0,  "rgb(220,50,50)"],     # saturated: red
+        ],
+        zmin=0.0, zmax=1.0,
+        colorbar=dict(
+            title="Utilization<br>fraction",
+            thickness=13,
+            len=0.7,
+            tickvals=[0, 0.5, 1],
+            ticktext=["0%", "50%", "100%"],
+            tickfont=dict(size=9),
+        ),
+        hovertemplate=(
+            "Edge: %{y}<br>Day: %{x}<br>Utilization: %{z:.1%}<extra></extra>"
+        ),
+    ))
+
+    # Disruption event markers
+    for ev in result.disruption_log:
+        fig.add_vline(
+            x=ev["day"], line_dash="dash",
+            line_color="rgba(80,80,255,0.6)", line_width=1.5,
+        )
+        fig.add_annotation(
+            x=ev["day"], y=1.01, xref="x", yref="paper",
+            text="disruption", showarrow=False,
+            font=dict(size=8, color="blue"), textangle=-90,
+        )
+
+    fig.update_layout(
+        title=dict(
+            text=(
+                "<b>Edge Utilization over Time</b><br>"
+                "<sup>Fraction of daily shipping capacity used per edge  "
+                "(0 = empty, 1 = fully saturated).  "
+                "Blue dashes mark disruption events.</sup>"
+            ),
+            x=0.5, xanchor="center", font=dict(size=13),
+        ),
+        xaxis=dict(
+            title="Day",
+            title_font=dict(size=11),
+            tickfont=dict(size=9),
+        ),
+        yaxis=dict(
+            title="Edge",
+            title_font=dict(size=11),
+            tickfont=dict(size=9),
+            autorange="reversed",  # downstream edges at top
+        ),
+        height=max(320, 30 * len(sorted_edges) + 120),
+        paper_bgcolor="white",
+        margin=dict(l=160, r=80, t=60, b=60),
+    )
+    return fig
+
+
+# ============================================================================
+# 5.  HTML wrapper for animated network map (Gradio gr.HTML compatible)
+# ============================================================================
+
+def make_network_animation_html(
+    result,
+    frame_step: Optional[int] = None,
+    frame_duration_ms: int = 150,
+) -> str:
+    """
+    Return an <iframe srcdoc=...> string for the animated network map.
+
+    Gradio's gr.Plot uses Plotly.react() internally, which strips the frames
+    array and breaks Play/Pause.  An <iframe> with a full standalone HTML page
+    (full_html=True) calls Plotly.newPlot() directly so frames are preserved
+    and the animation works.  The iframe also avoids the height:100% collapse
+    that occurs when embedding partial HTML in gr.HTML.
+    """
+    import html as _html
+    import plotly.io as pio
+
+    fig = make_network_animation(result, frame_step, frame_duration_ms)
+    full_html = pio.to_html(
+        fig,
+        include_plotlyjs="cdn",
+        full_html=True,
+        config={"responsive": True},
+    )
+    escaped = _html.escape(full_html, quote=True)
+    return (
+        f'<iframe srcdoc="{escaped}" '
+        f'width="100%" height="600" frameborder="0" scrolling="no" '
+        f'style="border:none;display:block;"></iframe>'
+    )
+
+
+# ============================================================================
+# 6.  Animated GIF export
+# ============================================================================
+
+def make_network_animation_gif(
+    result,
+    frame_step: Optional[int] = None,
+    frame_duration_ms: int = 150,
+    max_frames: int = 80,
+) -> str:
+    """
+    Render the network animation as an animated GIF and return the temp file path.
+
+    Requires:
+        pip install kaleido Pillow
+
+    Parameters
+    ----------
+    result : SimResult
+    frame_step : int or None
+        Days between frames.  Auto-computed to cap at max_frames.
+    frame_duration_ms : int
+        Milliseconds per frame during playback.
+    max_frames : int
+        Maximum number of frames to render (keeps file size reasonable).
+    """
+    import io as _io
+    import tempfile
+    import plotly.io as pio
+
+    try:
+        from PIL import Image
+    except ImportError:
+        raise ImportError("Pillow is required for GIF export: pip install Pillow")
+
+    T = result.T
+    if frame_step is None:
+        frame_step = max(1, T // max_frames)
+    frame_times = list(range(0, T, frame_step))
+
+    coords    = result.node_coords
+    node_ids  = result.node_ids
+    node_lats = [coords[n][0] for n in node_ids]
+    node_lons = [coords[n][1] for n in node_ids]
+    node_sizes   = [_TIER_MARKER_SIZE.get(result.tier.get(n, 3), 13) for n in node_ids]
+    node_labels  = node_ids
+    node_symbols = [_TIER_SYMBOL.get(result.tier.get(n, 3), "circle") for n in node_ids]
+    max_cap = max(result.edge_cap.values()) if result.edge_cap else 1.0
+
+    # Static edge traces (reused across frames)
+    edge_traces = []
+    for eid in result.edge_ids:
+        u, v = eid
+        if u not in coords or v not in coords:
+            continue
+        cap = result.edge_cap.get(eid, 1.0)
+        lw  = 1.0 + 3.5 * (cap / max_cap) ** 0.5
+        edge_traces.append(go.Scattergeo(
+            lat=[coords[u][0], coords[v][0], None],
+            lon=[coords[u][1], coords[v][1], None],
+            mode="lines",
+            line=dict(width=lw, color="rgba(140,140,160,0.55)"),
+            hoverinfo="skip",
+            showlegend=False,
+        ))
+
+    pil_frames = []
+    for t in frame_times:
+        stress_t = _node_stress(result, t)
+        lats_t, lons_t, _, colors_t = _frame_particles(result, t)
+
+        traces = list(edge_traces)  # shallow copy of static traces
+
+        traces.append(go.Scattergeo(
+            lat=node_lats, lon=node_lons,
+            mode="markers+text",
+            text=node_labels,
+            textposition="top center",
+            textfont=dict(size=9, color="black"),
+            marker=dict(
+                size=node_sizes, symbol=node_symbols,
+                color=stress_t, colorscale=NODE_COLORSCALE,
+                cmin=0.0, cmax=1.0,
+                line=dict(width=1.5, color="white"),
+            ),
+            hoverinfo="skip",
+            showlegend=False,
+        ))
+
+        if lats_t:
+            traces.append(go.Scattergeo(
+                lat=lats_t, lon=lons_t,
+                mode="markers",
+                marker=dict(size=7, color=colors_t, opacity=0.85,
+                            line=dict(width=0.5, color="white")),
+                hoverinfo="skip",
+                showlegend=False,
+            ))
+
+        fig = go.Figure(data=traces)
+        fig.update_layout(
+            title=dict(
+                text=f"<b>ISOMORPH</b>  —  Day {t} / {T - 1}",
+                x=0.5, xanchor="center", font=dict(size=12),
+            ),
+            geo=dict(
+                scope="usa", projection_type="albers usa",
+                showland=True,  landcolor="rgb(243,243,243)",
+                showlakes=True, lakecolor="rgb(210,230,255)",
+                showcoastlines=True, coastlinecolor="rgb(180,180,200)",
+                showsubunits=True, subunitcolor="rgb(200,200,215)",
+                bgcolor="white",
+            ),
+            margin=dict(l=0, r=0, t=40, b=5),
+            height=380, width=680,
+            paper_bgcolor="white",
+            showlegend=False,
+        )
+
+        img_bytes = pio.to_image(fig, format="png", width=680, height=380, scale=1)
+        pil_frames.append(Image.open(_io.BytesIO(img_bytes)).convert("RGB"))
+
+    tmp = tempfile.NamedTemporaryFile(suffix=".gif", delete=False, prefix="isomorph_")
+    pil_frames[0].save(
+        tmp.name,
+        save_all=True,
+        append_images=pil_frames[1:],
+        loop=0,
+        duration=frame_duration_ms,
+        optimize=False,
+    )
+    tmp.close()
+    return tmp.name

eval/chronos_run.py

@@ -0,0 +1,135 @@
+"""
+CLI driver: run a foundation model zero-shot on one ISOMORPH release.
+
+Outputs:
+  results/{model_short}_{dataset}.csv  long-format per-channel metrics
+  results/{model_short}_{dataset}_summary.csv  cross-channel mean/median
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from data_utils import load_dataset, iter_test_windows
+from metrics import metrics_at_horizons, to_long_dataframe, HORIZONS
+from chronos_runner import (
+    load_chronos, predict_rolling_origin, collect_y_true,
+)
+
+
+def short_name(model_id: str) -> str:
+    return model_id.split("/")[-1].replace("-", "_")
+
+
+def run(out_dir: Path, model_id: str, results_dir: Path,
+        L: int, H: int, stride: int,
+        num_samples: int, channel_batch: int,
+        max_windows: int | None = None,
+        label: str | None = None) -> None:
+    print(f"=== {out_dir.name}  with {model_id} ===", file=sys.stderr)
+    split = load_dataset(out_dir)
+    if label is not None:
+        split.label = label
+    print(f"  T={split.T}  n_items={split.n_items}  "
+          f"train_end={split.train_end}  val_end={split.val_end}  "
+          f"test=[{split.test_start}, {split.T})", file=sys.stderr)
+
+    starts = list(iter_test_windows(split, L=L, H=H, stride=stride))
+    if max_windows is not None:
+        starts = starts[:max_windows]
+    print(f"  rolling-origin windows: {len(starts)}  "
+          f"(L={L}, H={H}, stride={stride})", file=sys.stderr)
+
+    pipe = load_chronos(model_id)
+    t0 = time.time()
+    y_pred = predict_rolling_origin(
+        pipe, split.D, starts, L=L, H=H,
+        num_samples=num_samples, channel_batch=channel_batch,
+    )
+    y_true = collect_y_true(split.D, starts, H)
+    elapsed = time.time() - t0
+    print(f"  inference done in {elapsed/60:.1f} min", file=sys.stderr)
+
+    metric_dict = metrics_at_horizons(y_true, y_pred, split.mase_denom,
+                                      horizons=HORIZONS)
+    long_df = to_long_dataframe(metric_dict, split.item_ids,
+                                model=model_id, dataset=split.label)
+
+    sn = short_name(model_id)
+    results_dir.mkdir(parents=True, exist_ok=True)
+    out_long = results_dir / f"{sn}_{split.label}.csv"
+    long_df.to_csv(out_long, index=False)
+    print(f"  -> {out_long}", file=sys.stderr)
+
+    # Persist raw tensors for post-hoc slicing (e.g. stationary-vs-shock).
+    out_npz = results_dir / f"{sn}_{split.label}_tensors.npz"
+    np.savez_compressed(
+        out_npz, y_pred=y_pred, y_true=y_true,
+        window_starts=np.asarray(starts, dtype=np.int64),
+        item_ids=np.asarray(split.item_ids),
+        L=L, H=H, stride=stride, model=model_id, dataset=split.label,
+    )
+    print(f"  -> {out_npz}", file=sys.stderr)
+
+    # Cross-channel summary at each (metric, h).
+    summary = (long_df
+               .groupby(["model", "dataset", "metric", "h"])["value"]
+               .agg(mean="mean", median="median",
+                    q25=lambda x: x.quantile(0.25),
+                    q75=lambda x: x.quantile(0.75),
+                    n="count")
+               .reset_index())
+    out_sum = results_dir / f"{sn}_{split.label}_summary.csv"
+    summary.to_csv(out_sum, index=False)
+    print(f"  -> {out_sum}", file=sys.stderr)
+
+    # Print a compact body-table preview.
+    print("\n  Headline (median across channels):", file=sys.stderr)
+    print(summary.pivot_table(index="metric", columns="h",
+                              values="median").to_string(),
+          file=sys.stderr)
+
+
+def main():
+    repo = Path(__file__).resolve().parents[1]
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default=str(repo / "data"))
+    ap.add_argument("--dataset", default="output_item50")
+    ap.add_argument("--scenario_path", default=None,
+                    help="Path to a scenario directory "
+                         "(e.g. data/output_mixture/baseline/seed2025). "
+                         "Overrides --root/--dataset when set.")
+    ap.add_argument("--label", default=None,
+                    help="Output filename label. Defaults to the directory "
+                         "name. For scenario paths, set this to the scenario "
+                         "name so results from different scenarios don't collide.")
+    ap.add_argument("--model_id", default="amazon/chronos-t5-base")
+    ap.add_argument("--out", default=str(
+        repo / "results" / "eval" / "baseline_and_scenarios"))
+    ap.add_argument("--L", type=int, default=512)
+    ap.add_argument("--H", type=int, default=30)
+    ap.add_argument("--stride", type=int, default=30)
+    ap.add_argument("--num_samples", type=int, default=20)
+    ap.add_argument("--channel_batch", type=int, default=16)
+    ap.add_argument("--max_windows", type=int, default=None,
+                    help="cap for smoke testing")
+    args = ap.parse_args()
+    if args.scenario_path is not None:
+        out_dir = Path(args.scenario_path)
+    else:
+        out_dir = Path(args.root) / args.dataset
+    run(out_dir, args.model_id, Path(args.out),
+        L=args.L, H=args.H, stride=args.stride,
+        num_samples=args.num_samples,
+        channel_batch=args.channel_batch,
+        max_windows=args.max_windows,
+        label=args.label)
+
+
+if __name__ == "__main__":
+    main()

eval/chronos_runner.py

@@ -0,0 +1,83 @@
+"""
+Chronos zero-shot rolling-origin inference.
+
+Loads a Chronos pipeline from HuggingFace (uses HF_HOME cache so no
+network is needed once the checkpoint is local), runs L=512 → H=30
+inference per channel batched across channels, and reduces the 20
+sample paths to the per-day median for point-forecast metrics.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+import time
+
+import numpy as np
+import torch
+
+from chronos import ChronosPipeline
+
+
+def load_chronos(model_id: str, device: str | None = None,
+                 dtype: torch.dtype | None = None) -> ChronosPipeline:
+    """Load Chronos pipeline; auto-detect device/dtype if not given."""
+    if device is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    if dtype is None:
+        dtype = (torch.bfloat16 if device == "cuda"
+                 else torch.float32)
+    print(f"  loading {model_id} on {device} ({dtype})", file=sys.stderr)
+    return ChronosPipeline.from_pretrained(
+        model_id, device_map=device, torch_dtype=dtype,
+    )
+
+
+def predict_rolling_origin(
+    pipe: ChronosPipeline,
+    D: np.ndarray,                # (T, n_items)
+    window_starts: list[int],     # rolling-origin t values; forecast [t, t+H)
+    L: int = 512, H: int = 30,
+    num_samples: int = 20,
+    channel_batch: int = 16,
+) -> np.ndarray:
+    """Returns y_pred of shape (n_windows, H, n_items), point=median."""
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_pred = np.zeros((n_windows, H, n_items), dtype=np.float32)
+
+    t0 = time.time()
+    for wi, t in enumerate(window_starts):
+        ctx = D[t - L:t, :]                           # (L, n_items)
+        # Predict all channels for this window in batches.
+        for j0 in range(0, n_items, channel_batch):
+            j1 = min(j0 + channel_batch, n_items)
+            # ChronosPipeline.predict expects a list of 1-D tensors.
+            ctxs = [torch.tensor(ctx[:, j], dtype=torch.float32)
+                    for j in range(j0, j1)]
+            samples = pipe.predict(
+                ctxs, prediction_length=H,
+                num_samples=num_samples, limit_prediction_length=False,
+            )
+            # samples: (batch, num_samples, H) -- median over samples
+            samples = samples.cpu().to(torch.float32).numpy()
+            med = np.median(samples, axis=1)          # (batch, H)
+            y_pred[wi, :, j0:j1] = med.T              # (H, batch)
+        if wi == 0 or (wi + 1) % 10 == 0 or wi + 1 == n_windows:
+            elapsed = time.time() - t0
+            rate = (wi + 1) / max(elapsed, 1e-9)
+            eta = (n_windows - wi - 1) / max(rate, 1e-9)
+            print(f"  window {wi+1:4d}/{n_windows}  "
+                  f"elapsed={elapsed:6.1f}s  "
+                  f"rate={rate:5.2f} win/s  "
+                  f"eta={eta/60:5.1f}min", file=sys.stderr)
+    return y_pred
+
+
+def collect_y_true(D: np.ndarray, window_starts: list[int],
+                   H: int) -> np.ndarray:
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_true = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    for wi, t in enumerate(window_starts):
+        y_true[wi] = D[t:t + H]
+    return y_true

eval/data_utils.py

@@ -0,0 +1,103 @@
+"""
+Dataset I/O for §4 zero-shot foundation-model evaluation.
+
+Loads per-channel daily demand from the released CSVs, computes the
+chronological 70/15/15 split, and the MASE denominator (lag-7
+seasonal-naive in-sample MAE per channel, computed on the train slice;
+matches the GIFT-Eval-style definition used in paper §F.1).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class DemandSplit:
+    """A single dataset's demand series with its chronological splits."""
+    label: str
+    item_ids: list[str]
+    D: np.ndarray              # shape (T, n_items), float32
+    train_end: int             # exclusive
+    val_end: int               # exclusive — test = [val_end, T)
+    mase_denom: np.ndarray     # shape (n_items,), per-channel MAE of
+                               # lag-7 seasonal-naive on the train slice
+
+    @property
+    def T(self) -> int:
+        return self.D.shape[0]
+
+    @property
+    def n_items(self) -> int:
+        return self.D.shape[1]
+
+    @property
+    def test_start(self) -> int:
+        return self.val_end
+
+
+def load_dataset(out_dir: Path,
+                 split_train: float = 0.70,
+                 split_val: float = 0.15) -> DemandSplit:
+    """Load demand from daily_records.csv into (T, n_items) array."""
+    cols_path = out_dir / "demand_signals_cols.txt"
+    item_ids = cols_path.read_text().strip().split(",")
+    n_items = len(item_ids)
+    item_to_col = {iid: j for j, iid in enumerate(item_ids)}
+
+    dr = pd.read_csv(
+        out_dir / "daily_records.csv",
+        usecols=["day", "item", "demand"],
+        dtype={"day": np.int32, "demand": np.int64},
+    )
+    T = int(dr["day"].max() + 1)
+    D = np.zeros((T, n_items), dtype=np.float32)
+    days = dr["day"].to_numpy()
+    cols = dr["item"].map(item_to_col).to_numpy()
+    if pd.isna(cols).any():
+        raise ValueError("unknown items in daily_records.csv")
+    cols = cols.astype(np.int64)
+    D[days, cols] = dr["demand"].to_numpy(dtype=np.float32)
+
+    train_end = int(round(T * split_train))
+    val_end = int(round(T * (split_train + split_val)))
+
+    # MASE denominator: per-channel mean absolute lag-7 first difference
+    # of the TRAIN slice (seasonal-naive at weekly lag, the GluonTS default
+    # for daily frequency and the convention reported in paper §F.1).
+    train = D[:train_end]
+    SEASONAL_LAG = 7
+    diff = np.abs(train[SEASONAL_LAG:] - train[:-SEASONAL_LAG])
+    mase_denom = diff.mean(axis=0).astype(np.float32)
+    # Guard against zero (constant channel); fall back to 1.0 to avoid div-0
+    mase_denom = np.where(mase_denom > 0, mase_denom, 1.0)
+
+    return DemandSplit(
+        label=out_dir.name,
+        item_ids=item_ids,
+        D=D,
+        train_end=train_end,
+        val_end=val_end,
+        mase_denom=mase_denom,
+    )
+
+
+def iter_test_windows(split: DemandSplit, L: int = 512, H: int = 30,
+                      stride: int = 30):
+    """Yield rolling-origin windows whose forecast horizon lies in test.
+
+    Each window: context indices [t - L, t), forecast indices [t, t + H).
+    The first t is split.test_start; the last t satisfies t + H <= T.
+    Context is allowed to span train/val/test boundaries (rolling-origin).
+    """
+    T = split.T
+    t = split.test_start
+    while t + H <= T:
+        if t - L < 0:
+            t += stride
+            continue
+        yield t
+        t += stride

eval/gift_style_mase.py

@@ -0,0 +1,176 @@
+"""Compute GIFT-Eval-style aggregate MASE on the two ISOMORPH baseline
+releases for the four foundation models, so the values are directly
+comparable in scale to the GIFT-Eval leaderboard.
+
+Definition (matches GluonTS standard MASE + GIFT-Eval aggregation):
+  MASE_per_channel(model)   = MAE_model_per_channel  / D_seasonal
+  MASE_per_channel(SN)      = MAE_SN_per_channel     / D_seasonal
+  RelMASE_per_channel(M)    = MASE_model / MASE_SN  (= MAE_model / MAE_SN)
+  Aggregate                 = geometric_mean over channels
+
+  D_seasonal: per-channel mean abs lag-m first difference on the train
+              slice, with m=7 (weekly), the GluonTS default for daily
+              frequency.
+
+  SN baseline: at test window starting day t with horizon H=30,
+              prediction y_pred[t+h] = y[t+h-7] for h in [0, H).
+
+The MAE values for the four models per channel per horizon are read
+directly from the per-channel CSVs already produced by the foundation
+evaluation runs (no re-inference). Only Seasonal Naive is computed
+fresh.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import numpy as np
+import pandas as pd
+
+REPO = Path(__file__).resolve().parents[1]
+ROOT = REPO / "data"
+RESULT_DIR = REPO / "results" / "eval" / "baseline_and_scenarios"
+
+L = 512
+H = 30
+STRIDE = 30
+SEASONAL_M = 7
+
+DATASETS = ["output_item50", "output_item200"]
+HORIZONS = [1, 7, 14, 30]
+
+MODELS = {
+    "Chronos":    "chronos_t5_base_{ds}.csv",
+    "Moirai":     "moirai_1_1_R_base_{ds}.csv",
+    "TimesFM":    "timesfm_2_0_500m_pytorch_{ds}.csv",
+    "Lag-Llama":  "lag_llama_{ds}.csv",
+}
+
+
+def load_demand(ds_dir: Path) -> tuple[np.ndarray, list[str]]:
+    item_ids = (ds_dir / "demand_signals_cols.txt").read_text().strip().split(",")
+    item_to_col = {iid: j for j, iid in enumerate(item_ids)}
+    dr = pd.read_csv(ds_dir / "daily_records.csv",
+                     usecols=["day", "item", "demand"],
+                     dtype={"day": np.int32, "demand": np.int64})
+    T = int(dr["day"].max() + 1)
+    D = np.zeros((T, len(item_ids)), dtype=np.float32)
+    D[dr["day"].to_numpy(),
+      dr["item"].map(item_to_col).to_numpy(dtype=np.int64)] = \
+        dr["demand"].to_numpy(dtype=np.float32)
+    return D, item_ids
+
+
+def seasonal_denom(D_train: np.ndarray, m: int) -> np.ndarray:
+    """Mean abs lag-m first difference per channel on the train slice."""
+    diff = np.abs(D_train[m:] - D_train[:-m])
+    den = diff.mean(axis=0).astype(np.float32)
+    return np.where(den > 0, den, 1.0)
+
+
+def seasonal_naive_mae(D: np.ndarray, train_end: int, val_end: int,
+                       L: int, H: int, stride: int, m: int) -> np.ndarray:
+    """Per-channel-per-horizon MAE of SN(m) under the rolling-origin protocol.
+
+    Returns shape (len(HORIZONS), C). Cumulative-mean over the first h
+    forecast days then averaged over windows.
+    """
+    T, C = D.shape
+    test_start = val_end
+    starts = list(range(test_start, T - H + 1, stride))
+    n_W = len(starts)
+    abs_err = np.zeros((n_W, H, C), dtype=np.float32)
+    for w, t in enumerate(starts):
+        for h in range(H):
+            true = D[t + h]
+            pred = D[t + h - m]
+            abs_err[w, h] = np.abs(true - pred)
+    mae_per_h = np.zeros((len(HORIZONS), C), dtype=np.float32)
+    for i, h in enumerate(HORIZONS):
+        mae_per_h[i] = abs_err[:, :h, :].mean(axis=(0, 1))
+    return mae_per_h, n_W
+
+
+def model_mae(csv_path: Path) -> dict[int, np.ndarray]:
+    """Load per-channel MAE at each horizon from a model CSV."""
+    df = pd.read_csv(csv_path)
+    out = {}
+    for h in HORIZONS:
+        sub = df[(df["metric"] == "MAE") & (df["h"] == h)]
+        sub = sub.sort_values("channel")
+        out[h] = sub["value"].to_numpy(dtype=np.float32)
+    return out
+
+
+def gift_aggregate(rel_per_channel: np.ndarray) -> float:
+    """Geometric mean across channels."""
+    rel_per_channel = np.maximum(rel_per_channel, 1e-12)
+    return float(np.exp(np.log(rel_per_channel).mean()))
+
+
+def main():
+    rows = []
+    for ds in DATASETS:
+        ds_dir = ROOT / ds
+        print(f"\n=== {ds} ===")
+        D, item_ids = load_demand(ds_dir)
+        T, C = D.shape
+        train_end = int(round(T * 0.70))
+        val_end = int(round(T * 0.85))
+        print(f"  T={T}, C={C}, train_end={train_end}, val_end={val_end}")
+
+        d_seasonal = seasonal_denom(D[:train_end], SEASONAL_M)
+        print(f"  seasonal-{SEASONAL_M} denom:  "
+              f"min={d_seasonal.min():.3f}  "
+              f"mean={d_seasonal.mean():.3f}  max={d_seasonal.max():.3f}")
+
+        # Seasonal Naive baseline on rolling windows
+        sn_mae, n_W = seasonal_naive_mae(D, train_end, val_end,
+                                          L=L, H=H, stride=STRIDE,
+                                          m=SEASONAL_M)
+        print(f"  windows: {n_W}; SN MAE @ h=30 (mean over channels): "
+              f"{sn_mae[3].mean():.3f}")
+        sn_mase = sn_mae / d_seasonal[None, :]   # (4, C)
+
+        for model_name, csv_template in MODELS.items():
+            csv_name = csv_template.format(ds=ds)
+            csv_path = RESULT_DIR / csv_name
+            if not csv_path.exists():
+                print(f"  [{model_name}] MISSING {csv_name}")
+                continue
+            mae_dict = model_mae(csv_path)
+            for i, h in enumerate(HORIZONS):
+                model_mae_arr = mae_dict[h]
+                model_mase = model_mae_arr / d_seasonal
+                rel = model_mase / sn_mase[i]
+                # Cap absurd outliers to avoid inf in geom mean
+                rel = np.clip(rel, 1e-3, 1e3)
+                gift_mase = gift_aggregate(rel)
+                rows.append({
+                    "dataset": ds,
+                    "model":   model_name,
+                    "h":       h,
+                    "MAE_mean": float(model_mae_arr.mean()),
+                    "MASE_seasonal_mean": float(model_mase.mean()),
+                    "RelMASE_geom_over_channels": gift_mase,
+                })
+
+    out = pd.DataFrame(rows)
+    print("\n\n=== Summary (GIFT-style RelMASE = geom mean over channels of "
+          "[MAE_model / MAE_SeasonalNaive(m=7)]) ===")
+    pivot = out.pivot_table(index=["dataset", "model"], columns="h",
+                            values="RelMASE_geom_over_channels")
+    print(pivot.round(3).to_string())
+
+    # Headline aggregate (across horizons): geom mean over h
+    print("\n=== Per-(dataset, model) aggregate over horizons "
+          "(geom mean over h ∈ {1,7,14,30}) ===")
+    agg = (pivot.apply(lambda r: np.exp(np.log(r).mean()), axis=1)
+                 .round(3))
+    print(agg.to_string())
+
+    out.to_csv(RESULT_DIR / "gift_style_mase.csv", index=False)
+    print(f"\nSaved: {RESULT_DIR / 'gift_style_mase.csv'}")
+
+
+if __name__ == "__main__":
+    main()

eval/lagllama_run.py

@@ -0,0 +1,131 @@
+"""
+CLI driver: run Lag-Llama zero-shot on one ISOMORPH release.
+
+Outputs (mirror Chronos / Moirai / TimesFM runners):
+  results/lag_llama_{dataset}.csv          per-channel long-format metrics
+  results/lag_llama_{dataset}_summary.csv  cross-channel mean/median
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from data_utils import load_dataset, iter_test_windows
+from metrics import metrics_at_horizons, to_long_dataframe, HORIZONS
+from lagllama_runner import (
+    load_lagllama, predict_rolling_origin, collect_y_true,
+)
+
+
+MODEL_LABEL = "time-series-foundation-models/Lag-Llama"
+SHORT = "lag_llama"
+
+
+def run(out_dir: Path, results_dir: Path,
+        L: int, H: int, stride: int,
+        num_samples: int, batch_size: int,
+        max_windows: int | None = None,
+        label: str | None = None) -> None:
+    print(f"=== {out_dir.name}  with {MODEL_LABEL} ===", file=sys.stderr)
+    split = load_dataset(out_dir)
+    if label is not None:
+        split.label = label
+    print(f"  T={split.T}  n_items={split.n_items}  "
+          f"train_end={split.train_end}  val_end={split.val_end}  "
+          f"test=[{split.test_start}, {split.T})", file=sys.stderr)
+
+    starts = list(iter_test_windows(split, L=L, H=H, stride=stride))
+    if max_windows is not None:
+        starts = starts[:max_windows]
+    print(f"  rolling-origin windows: {len(starts)}  "
+          f"(L={L}, H={H}, stride={stride})", file=sys.stderr)
+
+    predictor = load_lagllama(
+        prediction_length=H, context_length=L,
+        num_samples=num_samples, batch_size=batch_size,
+    )
+
+    t0 = time.time()
+    y_pred = predict_rolling_origin(predictor, split.D, starts, L=L, H=H)
+    y_true = collect_y_true(split.D, starts, H)
+    elapsed = time.time() - t0
+    print(f"  inference done in {elapsed/60:.1f} min", file=sys.stderr)
+
+    metric_dict = metrics_at_horizons(y_true, y_pred, split.mase_denom,
+                                      horizons=HORIZONS)
+    long_df = to_long_dataframe(metric_dict, split.item_ids,
+                                model=MODEL_LABEL, dataset=split.label)
+
+    results_dir.mkdir(parents=True, exist_ok=True)
+    out_long = results_dir / f"{SHORT}_{split.label}.csv"
+    long_df.to_csv(out_long, index=False)
+    print(f"  -> {out_long}", file=sys.stderr)
+
+    # Persist raw tensors for post-hoc slicing (e.g. stationary-vs-shock).
+    out_npz = results_dir / f"{SHORT}_{split.label}_tensors.npz"
+    np.savez_compressed(
+        out_npz, y_pred=y_pred, y_true=y_true,
+        window_starts=np.asarray(starts, dtype=np.int64),
+        item_ids=np.asarray(split.item_ids),
+        L=L, H=H, stride=stride, model=MODEL_LABEL, dataset=split.label,
+    )
+    print(f"  -> {out_npz}", file=sys.stderr)
+
+    summary = (long_df
+               .groupby(["model", "dataset", "metric", "h"])["value"]
+               .agg(mean="mean", median="median",
+                    q25=lambda x: x.quantile(0.25),
+                    q75=lambda x: x.quantile(0.75),
+                    n="count")
+               .reset_index())
+    out_sum = results_dir / f"{SHORT}_{split.label}_summary.csv"
+    summary.to_csv(out_sum, index=False)
+    print(f"  -> {out_sum}", file=sys.stderr)
+
+    print("\n  Headline (median across channels):", file=sys.stderr)
+    print(summary.pivot_table(index="metric", columns="h",
+                              values="median").to_string(),
+          file=sys.stderr)
+
+
+def main():
+    repo = Path(__file__).resolve().parents[1]
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default=str(repo / "data"))
+    ap.add_argument("--dataset", default="output_item50")
+    ap.add_argument("--scenario_path", default=None,
+                    help="Path to a scenario directory; "
+                         "overrides --root/--dataset when set.")
+    ap.add_argument("--label", default=None,
+                    help="Output filename label; defaults to out_dir.name.")
+    ap.add_argument("--out", default=str(
+        repo / "results" / "eval" / "baseline_and_scenarios"))
+    ap.add_argument("--L", type=int, default=512,
+                    help="context length; with L>32 RoPE scaling auto-on")
+    ap.add_argument("--H", type=int, default=30)
+    ap.add_argument("--stride", type=int, default=30)
+    ap.add_argument("--num_samples", type=int, default=100,
+                    help="probabilistic samples for the median point forecast")
+    ap.add_argument("--batch_size", type=int, default=32)
+    ap.add_argument("--max_windows", type=int, default=None,
+                    help="cap for smoke testing")
+    args = ap.parse_args()
+    if args.scenario_path is not None:
+        out_dir = Path(args.scenario_path)
+    else:
+        out_dir = Path(args.root) / args.dataset
+    run(out_dir, Path(args.out),
+        L=args.L, H=args.H, stride=args.stride,
+        num_samples=args.num_samples,
+        batch_size=args.batch_size,
+        max_windows=args.max_windows,
+        label=args.label)
+
+
+if __name__ == "__main__":
+    main()

eval/lagllama_runner.py

@@ -0,0 +1,130 @@
+"""
+Lag-Llama zero-shot rolling-origin inference.
+
+Wraps time-series-foundation-models/Lag-Llama via the official GluonTS-style
+LagLlamaEstimator. Univariate (like Chronos / TimesFM): per window we hand
+the model C 1-D context arrays and reduce 100 sample paths to the per-day
+median for the point forecast.
+
+CRITICAL: Lag-Llama was trained on context length 32. Any L > 32 requires
+RoPE scaling (linear factor = (L + H) / 32). Without this the position
+embeddings extrapolate and the forecast degrades sharply.
+
+Designed to mirror chronos_runner.py's I/O contract so metrics.py stays
+unchanged.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+from gluonts.dataset.common import ListDataset
+
+from huggingface_hub import hf_hub_download
+from lag_llama.gluon.estimator import LagLlamaEstimator
+
+
+_LAGLLAMA_TRAINING_CTX = 32   # what the public checkpoint was trained on
+
+
+def load_lagllama(prediction_length: int, context_length: int,
+                  num_samples: int = 100, batch_size: int = 32,
+                  ckpt_path: str | None = None,
+                  device: str | None = None):
+    """Load Lag-Llama as a GluonTS PyTorchPredictor."""
+    if device is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    if ckpt_path is None:
+        ckpt_path = hf_hub_download(
+            repo_id="time-series-foundation-models/Lag-Llama",
+            filename="lag-llama.ckpt",
+        )
+    print(f"  loading Lag-Llama from {ckpt_path}  on {device}  "
+          f"(L={context_length}, H={prediction_length}, "
+          f"num_samples={num_samples}, batch_size={batch_size})",
+          file=sys.stderr)
+
+    # Pull the model architecture knobs out of the checkpoint so we
+    # construct a matching estimator regardless of release.
+    ckpt = torch.load(ckpt_path, map_location=device, weights_only=False)
+    args = ckpt["hyper_parameters"]["model_kwargs"]
+
+    # RoPE scaling so positional encodings extrapolate cleanly to L > 32.
+    rope_scaling = None
+    needed_extent = context_length + prediction_length
+    if needed_extent > _LAGLLAMA_TRAINING_CTX:
+        rope_scaling = {
+            "type": "linear",
+            "factor": float(needed_extent) / float(_LAGLLAMA_TRAINING_CTX),
+        }
+        print(f"  enabling RoPE scaling: factor="
+              f"{rope_scaling['factor']:.3f}  "
+              f"(L+H={needed_extent} > training ctx {_LAGLLAMA_TRAINING_CTX})",
+              file=sys.stderr)
+
+    estimator = LagLlamaEstimator(
+        ckpt_path=ckpt_path,
+        prediction_length=prediction_length,
+        context_length=context_length,
+        input_size=args["input_size"],
+        n_layer=args["n_layer"],
+        n_embd_per_head=args["n_embd_per_head"],
+        n_head=args["n_head"],
+        scaling=args["scaling"],
+        time_feat=args["time_feat"],
+        rope_scaling=rope_scaling,
+        batch_size=batch_size,
+        num_parallel_samples=num_samples,
+    )
+    lightning_module = estimator.create_lightning_module()
+    transformation = estimator.create_transformation()
+    predictor = estimator.create_predictor(transformation, lightning_module)
+    return predictor
+
+
+def predict_rolling_origin(predictor, D: np.ndarray,
+                           window_starts: list[int],
+                           L: int, H: int) -> np.ndarray:
+    """Returns y_pred of shape (n_windows, H, n_items); point=median."""
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_pred = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    anchor = pd.Period("2000-01-01", freq="D")
+
+    t0 = time.time()
+    for wi, t in enumerate(window_starts):
+        ctx = D[t - L:t, :]                                 # (L, n_items)
+        items = [
+            {"target": ctx[:, j].astype(np.float32), "start": anchor}
+            for j in range(n_items)
+        ]
+        ds = ListDataset(items, freq="D")
+        forecasts = list(predictor.predict(ds))
+        for j, fc in enumerate(forecasts):
+            # fc.samples: (num_parallel_samples, H)
+            y_pred[wi, :, j] = np.median(
+                np.asarray(fc.samples, dtype=np.float32), axis=0
+            )
+        if wi == 0 or (wi + 1) % 10 == 0 or wi + 1 == n_windows:
+            elapsed = time.time() - t0
+            rate = (wi + 1) / max(elapsed, 1e-9)
+            eta = (n_windows - wi - 1) / max(rate, 1e-9)
+            print(f"  window {wi+1:4d}/{n_windows}  "
+                  f"elapsed={elapsed:6.1f}s  "
+                  f"rate={rate:5.2f} win/s  "
+                  f"eta={eta/60:5.1f}min", file=sys.stderr)
+    return y_pred
+
+
+def collect_y_true(D: np.ndarray, window_starts: list[int],
+                   H: int) -> np.ndarray:
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_true = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    for wi, t in enumerate(window_starts):
+        y_true[wi] = D[t:t + H]
+    return y_true

eval/metrics.py

@@ -0,0 +1,86 @@
+"""
+Forecast metrics computed at horizons h ∈ {1, 7, 14, 30}.
+
+Inputs are y_true and y_pred of shape (n_windows, H, n_items),
+plus mase_denom of shape (n_items,). We accumulate per-item per-h
+sums and counts and then aggregate at the end.
+
+NOTE on the headline numbers in the paper.
+The per-channel ``MASE = MAE / mase_denom`` column written by this
+module is a convenience output; it is *not* what populates paper
+Table 1 / 6 / 7. Those tables report the GIFT-Eval-style aggregate
+(geometric mean over channels of ``MAE_model / MAE_SeasonalNaive``),
+which is recomputed post-hoc from the per-channel MAE column by
+``gift_style_mase.py``. Downstream consumers of these CSVs (the
+analysis scripts in this repo) likewise only read the MAE rows.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+HORIZONS = [1, 7, 14, 30]   # 1-indexed: h=1 means first forecast day
+
+
+def _smape_term(y_true: np.ndarray, y_pred: np.ndarray) -> np.ndarray:
+    """Standard sMAPE: 200 * |y - y_hat| / (|y| + |y_hat|).
+
+    Convention: when both numerator-relevant values are zero, the term
+    is zero (perfect forecast on a zero ground-truth).
+    """
+    num = 2.0 * np.abs(y_true - y_pred)
+    den = np.abs(y_true) + np.abs(y_pred)
+    out = np.where(den > 0, num / den, 0.0)
+    return 100.0 * out
+
+
+def metrics_at_horizons(
+    y_true: np.ndarray, y_pred: np.ndarray, mase_denom: np.ndarray,
+    horizons: list[int] = HORIZONS,
+) -> dict:
+    """Returns a dict keyed by (metric, h) -> per-channel array.
+
+    y_true, y_pred: shape (n_windows, H, n_items), float
+    mase_denom:    shape (n_items,)
+
+    For h=k, we average the per-day error over [0, k) and over windows;
+    that is, MAE@k = mean over (window, day in [0,k), channel).
+    Reporting per-channel: average over (window, day in [0,k)) → array of
+    shape (n_items,).
+    """
+    n_windows, H, n_items = y_true.shape
+    out = {}
+    abs_err = np.abs(y_true - y_pred)                 # (W, H, C)
+    sq_err  = (y_true - y_pred) ** 2                  # (W, H, C)
+    smape   = _smape_term(y_true, y_pred)             # (W, H, C)
+
+    for h in horizons:
+        if h > H:
+            continue
+        # Cumulative-mean over the first h forecast days, then average
+        # over windows. Result is per-channel: shape (n_items,).
+        mae   = abs_err[:, :h, :].mean(axis=(0, 1))
+        rmse  = np.sqrt(sq_err[:, :h, :].mean(axis=(0, 1)))
+        smap  = smape[:, :h, :].mean(axis=(0, 1))
+        mase  = mae / mase_denom
+
+        out[("MAE", h)]   = mae
+        out[("RMSE", h)]  = rmse
+        out[("SMAPE", h)] = smap
+        out[("MASE", h)]  = mase
+    return out
+
+
+def to_long_dataframe(metric_dict: dict, item_ids: list[str],
+                      model: str, dataset: str):
+    """Flatten the (metric, h) -> (n_items,) dict into long format."""
+    import pandas as pd
+    rows = []
+    for (metric, h), arr in metric_dict.items():
+        for i, iid in enumerate(item_ids):
+            rows.append({
+                "model": model, "dataset": dataset,
+                "channel": iid, "metric": metric, "h": h,
+                "value": float(arr[i]),
+            })
+    return pd.DataFrame(rows)

eval/moirai_run.py

@@ -0,0 +1,154 @@
+"""
+CLI driver: run Moirai zero-shot on one ISOMORPH release.
+
+Outputs (mirror Chronos runner naming):
+  results/{model_short}_{dataset}.csv          per-channel long-format metrics
+  results/{model_short}_{dataset}_summary.csv  cross-channel mean/median
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from data_utils import load_dataset
+from metrics import metrics_at_horizons, to_long_dataframe, HORIZONS
+from moirai_runner import (
+    load_moirai, build_test_data,
+    predict_rolling_origin, collect_y_true,
+)
+
+
+def short_name(model_id: str) -> str:
+    return model_id.split("/")[-1].replace("-", "_").replace(".", "_")
+
+
+def run(out_dir: Path, model_id: str, results_dir: Path,
+        L: int, H: int, stride: int,
+        num_samples: int, batch_size: int, patch_size,
+        max_windows: int | None = None,
+        label: str | None = None) -> None:
+    print(f"=== {out_dir.name}  with {model_id} ===", file=sys.stderr)
+    split = load_dataset(out_dir)
+    if label is not None:
+        split.label = label
+    print(f"  T={split.T}  n_items={split.n_items}  "
+          f"train_end={split.train_end}  val_end={split.val_end}  "
+          f"test=[{split.test_start}, {split.T})", file=sys.stderr)
+
+    test_data, n_windows = build_test_data(
+        split.D, split.item_ids, split.val_end,
+        H=H, stride=stride, max_windows=max_windows,
+    )
+    print(f"  rolling-origin windows: {n_windows}  "
+          f"(L={L}, H={H}, stride={stride})", file=sys.stderr)
+
+    predictor = load_moirai(
+        model_id,
+        prediction_length=H, context_length=L,
+        target_dim=split.n_items,
+        num_samples=num_samples, patch_size=patch_size,
+        batch_size=batch_size,
+    )
+
+    t0 = time.time()
+    y_pred = predict_rolling_origin(
+        predictor, test_data, n_windows, H, split.n_items,
+    )
+    y_true = collect_y_true(test_data, n_windows, H, split.n_items)
+    elapsed = time.time() - t0
+    print(f"  inference done in {elapsed/60:.1f} min", file=sys.stderr)
+
+    metric_dict = metrics_at_horizons(y_true, y_pred, split.mase_denom,
+                                      horizons=HORIZONS)
+    long_df = to_long_dataframe(metric_dict, split.item_ids,
+                                model=model_id, dataset=split.label)
+
+    sn = short_name(model_id)
+    results_dir.mkdir(parents=True, exist_ok=True)
+    out_long = results_dir / f"{sn}_{split.label}.csv"
+    long_df.to_csv(out_long, index=False)
+    print(f"  -> {out_long}", file=sys.stderr)
+
+    # Persist raw tensors for post-hoc slicing (e.g. stationary-vs-shock).
+    # Moirai's GluonTS test_data hides explicit window starts; reconstruct
+    # them from the (val_end, stride, n_windows) triple — the first
+    # forecast horizon begins at val_end and successive ones shift by stride.
+    starts = [split.val_end + i * stride for i in range(n_windows)]
+    out_npz = results_dir / f"{sn}_{split.label}_tensors.npz"
+    np.savez_compressed(
+        out_npz, y_pred=y_pred, y_true=y_true,
+        window_starts=np.asarray(starts, dtype=np.int64),
+        item_ids=np.asarray(split.item_ids),
+        L=L, H=H, stride=stride, model=model_id, dataset=split.label,
+    )
+    print(f"  -> {out_npz}", file=sys.stderr)
+
+    summary = (long_df
+               .groupby(["model", "dataset", "metric", "h"])["value"]
+               .agg(mean="mean", median="median",
+                    q25=lambda x: x.quantile(0.25),
+                    q75=lambda x: x.quantile(0.75),
+                    n="count")
+               .reset_index())
+    out_sum = results_dir / f"{sn}_{split.label}_summary.csv"
+    summary.to_csv(out_sum, index=False)
+    print(f"  -> {out_sum}", file=sys.stderr)
+
+    print("\n  Headline (median across channels):", file=sys.stderr)
+    print(summary.pivot_table(index="metric", columns="h",
+                              values="median").to_string(),
+          file=sys.stderr)
+
+
+def parse_patch_size(s: str):
+    if s == "auto":
+        return "auto"
+    return int(s)
+
+
+def main():
+    repo = Path(__file__).resolve().parents[1]
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default=str(repo / "data"))
+    ap.add_argument("--dataset", default="output_item50")
+    ap.add_argument("--scenario_path", default=None,
+                    help="Path to a scenario directory; "
+                         "overrides --root/--dataset when set.")
+    ap.add_argument("--label", default=None,
+                    help="Output filename label; defaults to out_dir.name.")
+    ap.add_argument("--model_id", default="Salesforce/moirai-1.1-R-base")
+    ap.add_argument("--out", default=str(
+        repo / "results" / "eval" / "baseline_and_scenarios"))
+    ap.add_argument("--L", type=int, default=1024,
+                    help="context length (Moirai recommends 512-2048)")
+    ap.add_argument("--H", type=int, default=30)
+    ap.add_argument("--stride", type=int, default=30)
+    ap.add_argument("--num_samples", type=int, default=100,
+                    help="probabilistic samples; 100 needed for stable median")
+    ap.add_argument("--batch_size", type=int, default=8,
+                    help="windows per inference batch")
+    ap.add_argument("--patch_size", type=parse_patch_size, default=32,
+                    help="'auto' or one of {8,16,32,64,128}")
+    ap.add_argument("--max_windows", type=int, default=None,
+                    help="cap for smoke testing")
+    args = ap.parse_args()
+    if args.scenario_path is not None:
+        out_dir = Path(args.scenario_path)
+    else:
+        out_dir = Path(args.root) / args.dataset
+    run(out_dir,
+        args.model_id, Path(args.out),
+        L=args.L, H=args.H, stride=args.stride,
+        num_samples=args.num_samples,
+        batch_size=args.batch_size, patch_size=args.patch_size,
+        max_windows=args.max_windows,
+        label=args.label)
+
+
+if __name__ == "__main__":
+    main()

eval/moirai_runner.py

@@ -0,0 +1,117 @@
+"""
+Moirai zero-shot rolling-origin inference.
+
+Wraps Salesforce moirai (uni2ts.model.moirai) to forecast our supply-chain
+demand release. Multivariate-native: a single forward predicts all C items.
+
+Designed to mirror chronos_runner.py's I/O contract so metrics.py can stay
+unchanged: produces y_pred of shape (n_windows, H, n_items) with point
+forecast = median over num_samples draws.
+"""
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+import pandas as pd
+import torch
+from gluonts.dataset.multivariate_grouper import MultivariateGrouper
+from gluonts.dataset.pandas import PandasDataset
+from gluonts.dataset.split import split as gluonts_split
+
+from uni2ts.model.moirai import MoiraiForecast, MoiraiModule
+
+
+def load_moirai(model_id: str, prediction_length: int, context_length: int,
+                target_dim: int, num_samples: int = 100,
+                patch_size: int | str = 32, batch_size: int = 32,
+                device: str | None = None):
+    """Build a Moirai predictor from a pretrained checkpoint."""
+    if device is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"  loading {model_id}  on {device}  "
+          f"(L={context_length}, H={prediction_length}, "
+          f"target_dim={target_dim}, patch_size={patch_size}, "
+          f"num_samples={num_samples})", file=sys.stderr)
+    module = MoiraiModule.from_pretrained(model_id)
+    model = MoiraiForecast(
+        module=module,
+        prediction_length=prediction_length,
+        context_length=context_length,
+        patch_size=patch_size,
+        num_samples=num_samples,
+        target_dim=target_dim,
+        feat_dynamic_real_dim=0,
+        past_feat_dynamic_real_dim=0,
+    )
+    predictor = model.create_predictor(batch_size=batch_size)
+    return predictor
+
+
+def build_test_data(D: np.ndarray, item_ids: list[str],
+                    val_end: int, H: int, stride: int,
+                    max_windows: int | None = None):
+    """Build a GluonTS multivariate test dataset for rolling-origin eval.
+
+    The test region is [val_end, T). Window i has its forecast horizon at
+    [val_end + i*stride, val_end + i*stride + H), with full-history input
+    (the model itself trims to the last `context_length` steps).
+    """
+    T, n_items = D.shape
+    test_len = T - val_end
+
+    # Wide DataFrame: each column is one item; daily frequency.
+    df = pd.DataFrame(
+        D,
+        columns=item_ids,
+        index=pd.date_range("2000-01-01", periods=T, freq="D"),
+    )
+    ds = PandasDataset(dict(df))
+    grouper = MultivariateGrouper(len(ds))
+    multivar_ds = grouper(ds)
+
+    train, test_template = gluonts_split(multivar_ds, offset=-test_len)
+
+    n_windows = (test_len - H) // stride + 1
+    if max_windows is not None:
+        n_windows = min(n_windows, max_windows)
+
+    test_data = test_template.generate_instances(
+        prediction_length=H,
+        windows=n_windows,
+        distance=stride,
+    )
+    return test_data, n_windows
+
+
+def predict_rolling_origin(predictor, test_data, n_windows: int,
+                           H: int, n_items: int) -> np.ndarray:
+    """Returns y_pred of shape (n_windows, H, n_items); point=median samples."""
+    y_pred = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    t0 = time.time()
+    forecasts = predictor.predict(test_data.input)
+    for wi, fc in enumerate(forecasts):
+        # fc.samples shape: (num_samples, H, target_dim)
+        samples = np.asarray(fc.samples, dtype=np.float32)
+        med = np.median(samples, axis=0)          # (H, target_dim)
+        y_pred[wi] = med
+        if wi == 0 or (wi + 1) % 10 == 0 or wi + 1 == n_windows:
+            elapsed = time.time() - t0
+            rate = (wi + 1) / max(elapsed, 1e-9)
+            eta = (n_windows - wi - 1) / max(rate, 1e-9)
+            print(f"  window {wi+1:4d}/{n_windows}  "
+                  f"elapsed={elapsed:6.1f}s  "
+                  f"rate={rate:5.2f} win/s  "
+                  f"eta={eta/60:5.1f}min", file=sys.stderr)
+    return y_pred
+
+
+def collect_y_true(test_data, n_windows: int, H: int,
+                   n_items: int) -> np.ndarray:
+    """Extract ground truth labels: shape (n_windows, H, n_items)."""
+    y_true = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    for wi, lbl in enumerate(test_data.label):
+        # lbl["target"] shape: (target_dim, H)
+        y_true[wi] = np.asarray(lbl["target"], dtype=np.float32).T
+    return y_true

eval/timesfm_run.py

@@ -0,0 +1,137 @@
+"""
+CLI driver: run TimesFM v2 zero-shot on one ISOMORPH release.
+
+Outputs (mirror Chronos / Moirai runners):
+  results/{model_short}_{dataset}.csv          per-channel long-format metrics
+  results/{model_short}_{dataset}_summary.csv  cross-channel mean/median
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from data_utils import load_dataset, iter_test_windows
+from metrics import metrics_at_horizons, to_long_dataframe, HORIZONS
+from timesfm_runner import (
+    load_timesfm, predict_rolling_origin, collect_y_true,
+)
+
+
+def short_name(model_id: str) -> str:
+    return model_id.split("/")[-1].replace("-", "_").replace(".", "_")
+
+
+def run(out_dir: Path, model_id: str, results_dir: Path,
+        L: int, H: int, stride: int,
+        per_core_batch_size: int, horizon_len: int,
+        max_windows: int | None = None,
+        label: str | None = None) -> None:
+    print(f"=== {out_dir.name}  with {model_id} ===", file=sys.stderr)
+    split = load_dataset(out_dir)
+    if label is not None:
+        split.label = label
+    print(f"  T={split.T}  n_items={split.n_items}  "
+          f"train_end={split.train_end}  val_end={split.val_end}  "
+          f"test=[{split.test_start}, {split.T})", file=sys.stderr)
+
+    starts = list(iter_test_windows(split, L=L, H=H, stride=stride))
+    if max_windows is not None:
+        starts = starts[:max_windows]
+    print(f"  rolling-origin windows: {len(starts)}  "
+          f"(L={L}, H={H}, stride={stride})", file=sys.stderr)
+
+    tfm = load_timesfm(
+        model_id=model_id,
+        context_len=L, horizon_len=horizon_len,
+        per_core_batch_size=per_core_batch_size,
+    )
+
+    t0 = time.time()
+    y_pred = predict_rolling_origin(tfm, split.D, starts, L=L, H=H)
+    y_true = collect_y_true(split.D, starts, H)
+    elapsed = time.time() - t0
+    print(f"  inference done in {elapsed/60:.1f} min", file=sys.stderr)
+
+    metric_dict = metrics_at_horizons(y_true, y_pred, split.mase_denom,
+                                      horizons=HORIZONS)
+    long_df = to_long_dataframe(metric_dict, split.item_ids,
+                                model=model_id, dataset=split.label)
+
+    sn = short_name(model_id)
+    results_dir.mkdir(parents=True, exist_ok=True)
+    out_long = results_dir / f"{sn}_{split.label}.csv"
+    long_df.to_csv(out_long, index=False)
+    print(f"  -> {out_long}", file=sys.stderr)
+
+    # Persist raw tensors for post-hoc slicing (e.g. stationary-vs-shock).
+    out_npz = results_dir / f"{sn}_{split.label}_tensors.npz"
+    np.savez_compressed(
+        out_npz, y_pred=y_pred, y_true=y_true,
+        window_starts=np.asarray(starts, dtype=np.int64),
+        item_ids=np.asarray(split.item_ids),
+        L=L, H=H, stride=stride, model=model_id, dataset=split.label,
+    )
+    print(f"  -> {out_npz}", file=sys.stderr)
+
+    summary = (long_df
+               .groupby(["model", "dataset", "metric", "h"])["value"]
+               .agg(mean="mean", median="median",
+                    q25=lambda x: x.quantile(0.25),
+                    q75=lambda x: x.quantile(0.75),
+                    n="count")
+               .reset_index())
+    out_sum = results_dir / f"{sn}_{split.label}_summary.csv"
+    summary.to_csv(out_sum, index=False)
+    print(f"  -> {out_sum}", file=sys.stderr)
+
+    print("\n  Headline (median across channels):", file=sys.stderr)
+    print(summary.pivot_table(index="metric", columns="h",
+                              values="median").to_string(),
+          file=sys.stderr)
+
+
+def main():
+    repo = Path(__file__).resolve().parents[1]
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", default=str(repo / "data"))
+    ap.add_argument("--dataset", default="output_item50")
+    ap.add_argument("--scenario_path", default=None,
+                    help="Path to a scenario directory; "
+                         "overrides --root/--dataset when set.")
+    ap.add_argument("--label", default=None,
+                    help="Output filename label; defaults to out_dir.name.")
+    ap.add_argument("--model_id", default="google/timesfm-2.0-500m-pytorch")
+    ap.add_argument("--out", default=str(
+        repo / "results" / "eval" / "baseline_and_scenarios"))
+    ap.add_argument("--L", type=int, default=2048,
+                    help="context length (TimesFM v2 trained up to 2048)")
+    ap.add_argument("--H", type=int, default=30,
+                    help="reported horizon (model decodes horizon_len, sliced)")
+    ap.add_argument("--horizon_len", type=int, default=128,
+                    help="model decode length; default 128 = one output patch")
+    ap.add_argument("--stride", type=int, default=30)
+    ap.add_argument("--per_core_batch_size", type=int, default=32,
+                    help="channels processed in parallel per forward")
+    ap.add_argument("--max_windows", type=int, default=None,
+                    help="cap for smoke testing")
+    args = ap.parse_args()
+    if args.scenario_path is not None:
+        out_dir = Path(args.scenario_path)
+    else:
+        out_dir = Path(args.root) / args.dataset
+    run(out_dir,
+        args.model_id, Path(args.out),
+        L=args.L, H=args.H, stride=args.stride,
+        per_core_batch_size=args.per_core_batch_size,
+        horizon_len=args.horizon_len,
+        max_windows=args.max_windows,
+        label=args.label)
+
+
+if __name__ == "__main__":
+    main()

eval/timesfm_runner.py

@@ -0,0 +1,87 @@
+"""
+TimesFM zero-shot rolling-origin inference.
+
+Wraps google/timesfm-2.0-500m-pytorch (univariate, like Chronos). Per
+window we hand the model a list of C univariate context arrays and it
+returns a (C, horizon_len) median-point forecast that we slice to H=30.
+
+Designed to mirror chronos_runner.py's I/O contract so metrics.py can
+stay unchanged.
+"""
+from __future__ import annotations
+
+import sys
+import time
+
+import numpy as np
+import torch
+
+import timesfm
+
+
+def load_timesfm(model_id: str = "google/timesfm-2.0-500m-pytorch",
+                 context_len: int = 2048, horizon_len: int = 128,
+                 per_core_batch_size: int = 32):
+    """Build a TimesFM v2 predictor (PyTorch backend, GPU-aware)."""
+    backend = "gpu" if torch.cuda.is_available() else "cpu"
+    print(f"  loading {model_id}  on {backend}  "
+          f"(L={context_len}, horizon_len={horizon_len}, "
+          f"per_core_batch_size={per_core_batch_size})", file=sys.stderr)
+
+    # v2-500m-pytorch hparams (per timesfm finetuning_example).
+    hparams = timesfm.TimesFmHparams(
+        backend=backend,
+        per_core_batch_size=per_core_batch_size,
+        horizon_len=horizon_len,
+        num_layers=50,
+        use_positional_embedding=False,
+        context_len=context_len,
+        # defaults: model_dims=1280, num_heads=16,
+        # input_patch_len=32, output_patch_len=128,
+        # quantiles=(.1,.2,...,.9), point_forecast_mode='median'
+    )
+    tfm = timesfm.TimesFm(
+        hparams=hparams,
+        checkpoint=timesfm.TimesFmCheckpoint(huggingface_repo_id=model_id),
+    )
+    return tfm
+
+
+def predict_rolling_origin(tfm, D: np.ndarray, window_starts: list[int],
+                           L: int, H: int) -> np.ndarray:
+    """Returns y_pred of shape (n_windows, H, n_items); point=median."""
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_pred = np.zeros((n_windows, H, n_items), dtype=np.float32)
+
+    t0 = time.time()
+    for wi, t in enumerate(window_starts):
+        ctx = D[t - L:t, :]                    # (L, n_items)
+        # forecast() takes a list of 1-D arrays, one per channel.
+        inputs = [ctx[:, j].astype(np.float32) for j in range(n_items)]
+        # freq=0 ("high frequency") matches daily; harmless either way for
+        # zero-shot eval since TimesFM uses freq only as a coarse covariate.
+        freqs = [0] * n_items
+        point_fc, _ = tfm.forecast(inputs=inputs, freq=freqs)
+        # point_fc shape: (n_items, horizon_len). Slice to first H steps.
+        y_pred[wi] = np.asarray(point_fc[:, :H], dtype=np.float32).T
+        if wi == 0 or (wi + 1) % 10 == 0 or wi + 1 == n_windows:
+            elapsed = time.time() - t0
+            rate = (wi + 1) / max(elapsed, 1e-9)
+            eta = (n_windows - wi - 1) / max(rate, 1e-9)
+            print(f"  window {wi+1:4d}/{n_windows}  "
+                  f"elapsed={elapsed:6.1f}s  "
+                  f"rate={rate:5.2f} win/s  "
+                  f"eta={eta/60:5.1f}min", file=sys.stderr)
+    return y_pred
+
+
+def collect_y_true(D: np.ndarray, window_starts: list[int],
+                   H: int) -> np.ndarray:
+    """Mirror chronos_runner.collect_y_true."""
+    n_windows = len(window_starts)
+    n_items = D.shape[1]
+    y_true = np.zeros((n_windows, H, n_items), dtype=np.float32)
+    for wi, t in enumerate(window_starts):
+        y_true[wi] = D[t:t + H]
+    return y_true

requirements.txt

@@ -0,0 +1,11 @@
+# Demo dependencies — used by app.py (Hugging Face Spaces / local run).
+# The full research pipeline (eval/, uq/, analysis/) requires additional
+# packages (torch, gluonts, chronos-forecasting, uni2ts, timesfm).
+# See the GitHub repo for the complete research requirements.
+
+gradio>=4.44
+plotly>=5.0
+numpy>=1.24
+pandas>=2.0
+kaleido>=1.0    # GIF export in the Network Map tab
+Pillow>=9.2     # GIF export in the Network Map tab

simulator/Supplychaingeo_item200.py

@@ -0,0 +1,1102 @@
+"""
+Supply Chain Simulation — Day-level, 52560-step.
+200-item.
+
+1 step = 1 day | 365 steps = 1 year | 52560 steps = 144 years
+
+logic:
+  - (s,S) inventory policy at warehouses
+  - Dijkstra routing (weight = travel_time / daily_capacity)
+  - Greedy first-fit bin packing
+  - Proactive shipping via pipeline_multiplier
+  - Streaming CSV for large runs
+
+
+Multi-echelon changes:
+  - Only source nodes (SF, StLouis, Orlando) retain magic replenishment
+  - Intermediate nodes pull inventory from upstream via network edges
+  - Per-tier (s,S) parameters calibrated to demand flow
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple, Optional, Any, Callable
+import math
+import heapq
+import random
+import os
+import csv
+import time as _time_module
+from datetime import datetime, timedelta
+import io
+import base64
+
+try:
+    import matplotlib.pyplot as plt
+    from branca.element import Element
+except ImportError:
+    pass
+
+import numpy as np
+import pandas as pd
+
+try:
+    import folium
+    from folium.plugins import TimestampedGeoJson
+    HAS_FOLIUM = True
+except ImportError:
+    HAS_FOLIUM = False
+
+
+# ============================================================================
+# Data Structures
+# ============================================================================
+
+@dataclass
+class Item:
+    item_id: str
+    volume: float
+
+
+@dataclass
+class Edge:
+    u: str
+    v: str
+    travel_time_days: float
+    container_volume: float
+    num_containers_per_day: int
+    daily_containers: List[float] = field(default_factory=list)
+
+    def reset_daily(self, capacity_factor: float = 1.0) -> None:
+        effective_vol = self.container_volume * capacity_factor
+        self.daily_containers = [effective_vol] * self.num_containers_per_day
+
+    def find_container_slot(self, item_volume: float) -> Optional[int]:
+        for idx, rem in enumerate(self.daily_containers):
+            if rem >= item_volume:
+                return idx
+        return None
+
+    def allocate_in_container(self, idx: int, item_volume: float) -> bool:
+        if 0 <= idx < len(self.daily_containers) and \
+                self.daily_containers[idx] >= item_volume:
+            self.daily_containers[idx] -= item_volume
+            return True
+        return False
+
+    @property
+    def daily_total_capacity(self) -> float:
+        return self.container_volume * max(self.num_containers_per_day, 0)
+
+
+@dataclass
+class Node:
+    node_id: str
+    lat: float
+    lon: float
+    is_destination: bool = False
+    is_source: bool = False
+    inventory: Dict[str, int] = field(default_factory=dict)
+    s_levels: Dict[str, int] = field(default_factory=dict)
+    S_levels: Dict[str, int] = field(default_factory=dict)
+    lead_time_mean: Dict[str, float] = field(default_factory=dict)
+    lead_time_std_frac: float = 0.2
+    outstanding_orders: Dict[str, Optional[Tuple[int, int]]] = \
+        field(default_factory=dict)
+    backlog: Dict[str, int] = field(default_factory=dict)
+
+    def receive_orders_today(self, day: int) -> None:
+        to_clear = []
+        for item_id, order in self.outstanding_orders.items():
+            if order is None:
+                continue
+            arrival_day, qty = order
+            if day >= arrival_day:
+                self.inventory[item_id] = \
+                    self.inventory.get(item_id, 0) + qty
+                to_clear.append(item_id)
+        for iid in to_clear:
+            self.outstanding_orders[iid] = None
+
+    def maybe_place_orders(self, day: int, rng: random.Random) -> None:
+        if self.is_destination:
+            return
+        if not self.is_source:
+            return
+        for item_id, s in self.s_levels.items():
+            on_hand = self.inventory.get(item_id, 0)
+            if on_hand < s and \
+                    self.outstanding_orders.get(item_id) is None:
+                S = self.S_levels.get(item_id, on_hand)
+                qty = max(S - on_hand, 0)
+                if qty <= 0:
+                    continue
+                mean_lt = max(self.lead_time_mean.get(item_id, 1.0), 0.1)
+                std = self.lead_time_std_frac * mean_lt
+                sampled = rng.normalvariate(mean_lt, std)
+                lt_days = max(1, int(math.ceil(sampled)))
+                self.outstanding_orders[item_id] = (day + lt_days, qty)
+
+
+# ============================================================================
+# Network + Dijkstra
+# ============================================================================
+
+class Network:
+    def __init__(self) -> None:
+        self.nodes: Dict[str, Node] = {}
+        self.edges: Dict[Tuple[str, str], Edge] = {}
+        self.adj: Dict[str, List[str]] = {}
+        self.weight_cache: Dict[Tuple[str, str], float] = {}
+        self.paths_to_dest: Dict[
+            str, Tuple[float, List[str], List[Tuple[str, str]]]] = {}
+
+    def add_node(self, node: Node) -> None:
+        self.nodes[node.node_id] = node
+        self.adj.setdefault(node.node_id, [])
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges[(edge.u, edge.v)] = edge
+        self.adj.setdefault(edge.u, []).append(edge.v)
+        cap = max(edge.daily_total_capacity, 1e-9)
+        self.weight_cache[(edge.u, edge.v)] = edge.travel_time_days / cap
+
+    def reset_daily_edges(self, capacity_factor: float = 1.0) -> None:
+        for e in self.edges.values():
+            e.reset_daily(capacity_factor)
+
+    def dijkstra(self, source: str, target: str) -> Tuple[float, List[str]]:
+        if source == target:
+            return 0.0, [source]
+        dist: Dict[str, float] = {source: 0.0}
+        prev: Dict[str, Optional[str]] = {source: None}
+        pq = [(0.0, source)]
+        visited: set = set()
+        while pq:
+            d, u = heapq.heappop(pq)
+            if u in visited:
+                continue
+            visited.add(u)
+            if u == target:
+                break
+            for v in self.adj.get(u, []):
+                w = self.weight_cache[(u, v)]
+                nd = d + w
+                if nd < dist.get(v, float('inf')):
+                    dist[v] = nd
+                    prev[v] = u
+                    heapq.heappush(pq, (nd, v))
+        if target not in dist:
+            return float('inf'), []
+        path: List[str] = []
+        cur: Optional[str] = target
+        while cur is not None:
+            path.append(cur)
+            cur = prev.get(cur)
+        path.reverse()
+        return dist[target], path
+
+    def compute_paths_to_destination(self, dest_id: str) -> None:
+        self.paths_to_dest.clear()
+        for nid in self.nodes:
+            if nid == dest_id:
+                self.paths_to_dest[nid] = (0.0, [nid], [])
+                continue
+            d, pn = self.dijkstra(nid, dest_id)
+            if not pn:
+                self.paths_to_dest[nid] = (float('inf'), [], [])
+            else:
+                pe = [(pn[i], pn[i+1]) for i in range(len(pn)-1)]
+                self.paths_to_dest[nid] = (d, pn, pe)
+
+
+# ============================================================================
+# Greedy First-Fit Bin Packing
+# ============================================================================
+
+def allocate_units_along_path_greedy(
+    item: Item,
+    max_units: int,
+    path_edges: List[Tuple[str, str]],
+    network_edges: Dict[Tuple[str, str], Edge],
+) -> int:
+    if max_units <= 0 or not path_edges:
+        return 0
+    edges_objs = [network_edges[eid] for eid in path_edges]
+    placed = 0
+    ivol = item.volume
+    for _ in range(max_units):
+        slots: List[Tuple[Edge, int]] = []
+        ok = True
+        for e in edges_objs:
+            si = e.find_container_slot(ivol)
+            if si is None:
+                ok = False
+                break
+            slots.append((e, si))
+        if not ok:
+            break
+        good = True
+        for e, si in slots:
+            if not e.allocate_in_container(si, ivol):
+                good = False
+                break
+        if not good:
+            break
+        placed += 1
+    return placed
+
+
+# ============================================================================
+# Simulation Engine
+# ============================================================================
+
+class SupplyChainSimulation:
+
+    def __init__(
+        self,
+        network: Network,
+        items: Dict[str, Item],
+        destination_id: str,
+        demand_fn: Callable[[int], Dict[str, int]],
+        horizon_days: int,
+        seed: int = 42,
+        pipeline_multiplier: float = 0.0,
+        streaming_out_dir: Optional[str] = None,
+        packing: str = "greedy",
+    ) -> None:
+        assert destination_id in network.nodes and \
+            network.nodes[destination_id].is_destination
+        self.network = network
+        self.items = items
+        self.item_order: List[str] = sorted(self.items.keys())
+        self.round_robin_items: bool = True
+        self.per_item_daily_cap_units: Optional[int] = None
+
+        self.destination_id = destination_id
+        self.demand_fn = demand_fn
+        self.horizon_days = horizon_days
+        self.rng = random.Random(seed)
+        self.packing = packing
+        self.pipeline_multiplier = pipeline_multiplier
+
+        # EMA warm-start at approximate per-day mean demand
+        self.demand_ema: Dict[str, float] = {iid: 165.0 for iid in items}
+        self.ema_alpha = 0.05
+        self.item_intransit: Dict[str, int] = {iid: 0 for iid in items}
+
+        self.streaming_out_dir = streaming_out_dir
+        self._csv_files: Dict = {}
+        self._csv_writers: Dict = {}
+        self._csv_buffers: Dict[str, list] = {}
+        self.dest_in_transit: Dict[int, Dict[str, int]] = {}
+
+        self.daily_records: list = []
+        self.shipments_log: list = []
+        self.inventory_history: list = []
+        self.backlog_history: list = []
+        self.intransit_history: list = []
+
+        self.svc_demand: Dict[str, int] = {iid: 0 for iid in items}
+        self.svc_served: Dict[str, int] = {iid: 0 for iid in items}
+        self.svc_backlog: Dict[str, int] = {iid: 0 for iid in items}
+
+        network.compute_paths_to_destination(destination_id)
+        self.sorted_warehouses = sorted(
+            [(nid, d) for nid, (d, _, _) in network.paths_to_dest.items()
+             if nid != destination_id and math.isfinite(d)],
+            key=lambda x: x[1])
+
+        # precompute supplier relationships for intermediate nodes
+        self.node_suppliers: Dict[
+            str,
+            List[Tuple[str, float, List[str], List[Tuple[str, str]]]]
+        ] = {}
+        for nid, node in network.nodes.items():
+            if node.is_destination or node.is_source:
+                continue
+            suppliers = []
+            for (u, v) in network.edges:
+                if v == nid:
+                    d, path = network.dijkstra(u, nid)
+                    if path and math.isfinite(d):
+                        pe = [(path[i], path[i + 1])
+                              for i in range(len(path) - 1)]
+                        tt = sum(network.edges[e].travel_time_days
+                                 for e in pe)
+                        suppliers.append((u, tt, path, pe))
+            suppliers.sort(key=lambda x: x[1])
+            self.node_suppliers[nid] = suppliers
+
+        # intermediate nodes ordered upstream-first for replenishment
+        self.replenish_order: List[str] = [
+            nid for nid, _ in reversed(self.sorted_warehouses)
+            if nid in self.node_suppliers]
+
+        self.avg_travel_time = 6.0
+        if self.sorted_warehouses:
+            _, _, pe = network.paths_to_dest[self.sorted_warehouses[0][0]]
+            if pe:
+                self.avg_travel_time = sum(
+                    network.edges[e].travel_time_days for e in pe)
+
+    def _total_tt(self, pe):
+        return sum(self.network.edges[e].travel_time_days for e in pe)
+
+    def _replenish_warehouses(self, day: int) -> None:
+        """Inter-warehouse replenishment: intermediate nodes pull
+        from upstream suppliers using (s,S) trigger + edge capacity."""
+        net = self.network
+
+        if self.round_robin_items and self.item_order:
+            k = day % len(self.item_order)
+            ids_today = self.item_order[k:] + self.item_order[:k]
+        else:
+            ids_today = self.item_order[:]
+
+        for nid in self.replenish_order:
+            node = net.nodes[nid]
+            for iid in ids_today:
+                on_hand = node.inventory.get(iid, 0)
+                s = node.s_levels.get(iid, 0)
+                if on_hand >= s:
+                    continue
+                if node.outstanding_orders.get(iid) is not None:
+                    continue
+                S = node.S_levels.get(iid, on_hand)
+                qty_needed = max(S - on_hand, 0)
+                if qty_needed <= 0:
+                    continue
+
+                for sup_id, tt, path, pe in \
+                        self.node_suppliers.get(nid, []):
+                    sup_node = net.nodes[sup_id]
+                    avail = sup_node.inventory.get(iid, 0)
+                    if avail <= 0:
+                        continue
+                    attempt = min(avail, qty_needed)
+                    placed = allocate_units_along_path_greedy(
+                        self.items[iid], attempt, pe, net.edges)
+                    if placed <= 0:
+                        continue
+
+                    sup_node.inventory[iid] -= placed
+                    arr = day + max(1, int(math.ceil(tt)))
+                    node.outstanding_orders[iid] = (arr, placed)
+
+                    r = [day, arr, sup_id, nid, iid, placed,
+                         str(path),
+                         str([net.edges[e].travel_time_days
+                              for e in pe])]
+                    if self.streaming_out_dir:
+                        self._csv_buffers.setdefault(
+                            'ship', []).append(r)
+                    else:
+                        self.shipments_log.append({
+                            "day": day, "arrival_day": arr,
+                            "from": sup_id, "to": nid,
+                            "item": iid, "units": placed,
+                            "path_nodes": path,
+                            "edge_times": [
+                                net.edges[e].travel_time_days
+                                for e in pe]})
+                    break
+
+    def step(self, day: int) -> None:
+        net = self.network
+        dest = net.nodes[self.destination_id]
+
+        # 1) Receive (s,S) replenishment at warehouses
+        for node in net.nodes.values():
+            node.receive_orders_today(day)
+
+        # 2) Arrivals at destination
+        arrivals = self.dest_in_transit.pop(day, {})
+        for iid, qty in arrivals.items():
+            self.item_intransit[iid] = max(
+                0, self.item_intransit.get(iid, 0) - qty)
+            bl = dest.backlog.get(iid, 0)
+            if bl > 0:
+                use = min(qty, bl)
+                dest.backlog[iid] = bl - use
+                qty -= use
+            if qty > 0:
+                dest.inventory[iid] = dest.inventory.get(iid, 0) + qty
+
+        # 3) Reset edge containers
+        net.reset_daily_edges(1.0)
+
+        # 4) Demand at destination
+        td = self.demand_fn(day)
+        for iid in self.items:
+            dq = int(td.get(iid, 0))
+            self.demand_ema[iid] = (
+                self.ema_alpha * dq +
+                (1 - self.ema_alpha) * self.demand_ema[iid])
+            oh = dest.inventory.get(iid, 0)
+            if oh >= dq:
+                served, unfilled = dq, 0
+                dest.inventory[iid] = oh - dq
+            else:
+                served, unfilled = oh, dq - oh
+                dest.inventory[iid] = 0
+                dest.backlog[iid] = dest.backlog.get(iid, 0) + unfilled
+            self.svc_demand[iid] += dq
+            self.svc_served[iid] += served
+            self.svc_backlog[iid] += unfilled
+            rec = [day, iid, dq, served, unfilled,
+                   dest.inventory.get(iid, 0), dest.backlog.get(iid, 0)]
+            if self.streaming_out_dir:
+                self._csv_buffers.setdefault('daily', []).append(rec)
+            else:
+                self.daily_records.append({
+                    "day": day, "item": iid, "demand": dq,
+                    "served_from_stock": served,
+                    "new_backlog_today": unfilled,
+                    "dest_on_hand_end_before_ship":
+                        dest.inventory.get(iid, 0),
+                    "dest_backlog_end_before_ship":
+                        dest.backlog.get(iid, 0)})
+
+        # 5) Ship
+        if self.round_robin_items and self.item_order:
+            k = day % len(self.item_order)
+            ids_today = self.item_order[k:] + self.item_order[:k]
+        else:
+            ids_today = self.item_order[:]
+
+        for iid in ids_today:
+            item = self.items[iid]
+            cb = dest.backlog.get(iid, 0)
+            it = self.item_intransit.get(iid, 0)
+            oh = dest.inventory.get(iid, 0)
+
+            if self.pipeline_multiplier > 0:
+                pt = self.demand_ema[iid] * self.pipeline_multiplier
+                ship_target = max(0, int(math.ceil(cb + pt - it - oh)))
+            else:
+                S_dest = max(1, int(self.demand_ema[iid] * 3))
+                ship_target = max(0, cb + S_dest - oh - it)
+
+            if ship_target <= 0:
+                continue
+
+            remaining = ship_target
+            shipped = 0
+            for wid, _ in self.sorted_warehouses:
+                if remaining <= 0:
+                    break
+                if self.per_item_daily_cap_units is not None and \
+                        shipped >= self.per_item_daily_cap_units:
+                    break
+                wn = net.nodes[wid]
+                avail = wn.inventory.get(iid, 0)
+                if avail <= 0:
+                    continue
+                _, pn, pe = net.paths_to_dest[wid]
+                if not pe:
+                    continue
+                attempt = min(avail, remaining)
+                if self.per_item_daily_cap_units is not None:
+                    attempt = min(attempt,
+                                  self.per_item_daily_cap_units - shipped)
+                placed = allocate_units_along_path_greedy(
+                    item, attempt, pe, net.edges)
+                if placed <= 0:
+                    continue
+                wn.inventory[iid] -= placed
+                remaining -= placed
+                shipped += placed
+                arr = day + max(1, int(math.ceil(self._total_tt(pe))))
+                self.dest_in_transit.setdefault(arr, {})
+                self.dest_in_transit[arr][iid] = \
+                    self.dest_in_transit[arr].get(iid, 0) + placed
+                self.item_intransit[iid] = \
+                    self.item_intransit.get(iid, 0) + placed
+                r = [day, arr, wid, self.destination_id, iid, placed,
+                     str(pn),
+                     str([net.edges[e].travel_time_days for e in pe])]
+                if self.streaming_out_dir:
+                    self._csv_buffers.setdefault('ship', []).append(r)
+                else:
+                    self.shipments_log.append({
+                        "day": day, "arrival_day": arr,
+                        "from": wid, "to": self.destination_id,
+                        "item": iid, "units": placed,
+                        "path_nodes": pn,
+                        "edge_times": [net.edges[e].travel_time_days
+                                       for e in pe]})
+
+        # 5b) Inter-warehouse replenishment
+        self._replenish_warehouses(day)
+
+        # 6) (s,S) orders at source warehouses
+        for node in net.nodes.values():
+            node.maybe_place_orders(day, self.rng)
+
+        # 7) Snapshots
+        did = self.destination_id
+        itc: Dict[str, int] = {}
+        for ad, im in self.dest_in_transit.items():
+            if ad > day:
+                for iid, q in im.items():
+                    itc[iid] = itc.get(iid, 0) + int(q)
+
+        if self.streaming_out_dir:
+            for node in net.nodes.values():
+                for iid in self.items:
+                    self._csv_buffers.setdefault('inv', []).append(
+                        [day, node.node_id, iid,
+                         int(node.inventory.get(iid, 0))])
+                    self._csv_buffers.setdefault('bl', []).append(
+                        [day, node.node_id, iid,
+                         int(node.backlog.get(iid, 0))])
+            for iid in self.items:
+                self._csv_buffers.setdefault('it', []).append(
+                    [day, did, iid, itc.get(iid, 0)])
+        else:
+            for node in net.nodes.values():
+                for iid in self.items:
+                    self.inventory_history.append({
+                        "day": day, "node": node.node_id, "item": iid,
+                        "on_hand": int(node.inventory.get(iid, 0))})
+                    self.backlog_history.append({
+                        "day": day, "node": node.node_id, "item": iid,
+                        "backlog": int(node.backlog.get(iid, 0))})
+            for iid in self.items:
+                self.intransit_history.append({
+                    "day": day, "node": did, "item": iid,
+                    "in_transit": itc.get(iid, 0)})
+
+    # --- CSV streaming ---
+    def _open_csv_files(self):
+        os.makedirs(self.streaming_out_dir, exist_ok=True)
+        hdrs = {
+            'daily': ["day", "item", "demand", "served_from_stock",
+                      "new_backlog_today", "dest_on_hand_end_before_ship",
+                      "dest_backlog_end_before_ship"],
+            'ship':  ["day", "arrival_day", "from", "to", "item",
+                      "units", "path_nodes", "edge_times"],
+            'inv':   ["day", "node", "item", "on_hand"],
+            'bl':    ["day", "node", "item", "backlog"],
+            'it':    ["day", "node", "item", "in_transit"],
+        }
+        fn = {'daily': 'daily_records', 'ship': 'shipments',
+              'inv': 'inventory_history', 'bl': 'backlog_history',
+              'it': 'intransit_history'}
+        for k in hdrs:
+            f = open(os.path.join(self.streaming_out_dir,
+                                  f"{fn[k]}.csv"),
+                     "w", newline="", buffering=65536)
+            w = csv.writer(f)
+            w.writerow(hdrs[k])
+            self._csv_files[k] = f
+            self._csv_writers[k] = w
+            self._csv_buffers[k] = []
+
+    def _flush_csv(self):
+        for k in self._csv_buffers:
+            if self._csv_buffers[k] and k in self._csv_writers:
+                self._csv_writers[k].writerows(self._csv_buffers[k])
+                self._csv_buffers[k] = []
+        for f in self._csv_files.values():
+            f.flush()
+
+    def _close_csv(self):
+        self._flush_csv()
+        for f in self._csv_files.values():
+            f.close()
+
+    def run(self):
+        if self.streaming_out_dir:
+            self._open_csv_files()
+        t0 = _time_module.time()
+        ri = max(1, self.horizon_days // 100)
+        for day in range(self.horizon_days):
+            self.step(day)
+            if self.streaming_out_dir and day % 500 == 0:
+                self._flush_csv()
+            if day % 5000 == 0:
+                for k in [k for k in self.dest_in_transit if k < day]:
+                    del self.dest_in_transit[k]
+            if day % ri == 0 or day == self.horizon_days - 1:
+                el = _time_module.time() - t0
+                pct = (day + 1) / self.horizon_days * 100
+                rate = (day + 1) / max(el, 0.001)
+                eta = (self.horizon_days - day - 1) / max(rate, 0.001)
+                print(f"\r  Day {day+1:>6}/{self.horizon_days} "
+                      f"({pct:5.1f}%) {rate:6.1f} days/s "
+                      f"ETA {eta:6.0f}s", end="", flush=True)
+        print(f"\n  Simulation complete in "
+              f"{_time_module.time()-t0:.1f}s")
+
+        if self.streaming_out_dir:
+            self._close_csv()
+            rows = []
+            for iid in sorted(self.items):
+                td = self.svc_demand[iid]
+                sv = self.svc_served[iid]
+                bl = self.svc_backlog[iid]
+                rows.append({
+                    "item": iid, "total_demand": td,
+                    "served_from_stock": sv,
+                    "new_backlog_added": bl,
+                    "fill_rate_stock_only":
+                        round(sv / td, 6) if td > 0 else 0.0})
+            svc = pd.DataFrame(rows)
+            svc.to_csv(os.path.join(self.streaming_out_dir,
+                                    "service_summary.csv"), index=False)
+            return (pd.DataFrame(), pd.DataFrame(), svc,
+                    pd.DataFrame(), pd.DataFrame(), pd.DataFrame())
+
+        dd = pd.DataFrame(self.daily_records)
+        ds = pd.DataFrame(self.shipments_log) if self.shipments_log \
+            else pd.DataFrame(columns=[
+                "day", "arrival_day", "from", "to",
+                "item", "units", "path_nodes", "edge_times"])
+        svc = dd.groupby("item", as_index=False).agg(
+            total_demand=("demand", "sum"),
+            served_from_stock=("served_from_stock", "sum"),
+            new_backlog_added=("new_backlog_today", "sum"))
+        svc["fill_rate_stock_only"] = (
+            svc["served_from_stock"] / svc["total_demand"]).fillna(0)
+        di = pd.DataFrame(self.inventory_history,
+                          columns=["day", "node", "item", "on_hand"])
+        db = pd.DataFrame(self.backlog_history,
+                          columns=["day", "node", "item", "backlog"])
+        dt = pd.DataFrame(self.intransit_history,
+                          columns=["day", "node", "item", "in_transit"])
+        return dd, ds, svc, di, db, dt
+
+
+# ============================================================================
+# Build network from adjacency
+# ============================================================================
+
+def build_network_from_adjacency(nodes_meta, adjacency):
+    n = len(nodes_meta)
+    assert all(len(r) == n for r in adjacency)
+    net = Network()
+    for meta in nodes_meta:
+        net.add_node(Node(
+            node_id=meta["id"],
+            lat=float(meta["lat"]), lon=float(meta["lon"]),
+            is_destination=bool(meta.get("is_destination", False)),
+            is_source=bool(meta.get("is_source", False)),
+            inventory=dict(meta.get("inventory", {})),
+            s_levels=dict(meta.get("s_levels", {})),
+            S_levels=dict(meta.get("S_levels", {})),
+            lead_time_mean=dict(meta.get("lead_time_mean", {})),
+            backlog=dict(meta.get("backlog", {}))))
+    ids = [m["id"] for m in nodes_meta]
+    for i in range(n):
+        for j in range(n):
+            s = adjacency[i][j]
+            if s is None:
+                continue
+            tt, cv, nc = s
+            net.add_edge(Edge(
+                u=ids[i], v=ids[j],
+                travel_time_days=float(tt),
+                container_volume=float(cv),
+                num_containers_per_day=int(nc)))
+    return net
+
+
+# ============================================================================
+# Demand Generator  — day-level
+# ============================================================================
+
+def build_demand_fn(
+    item_ids, n_steps, seed=42,
+    base_lambda_range=(80, 250),
+):
+    """
+
+    Structure:
+      - Yearly cycle   T=365 days  (moderate amplitude, two harmonics)
+      - Weekly cycle   T=7 days    (small texture)
+      - AR(1) drift                (dominant low-frequency, decade-scale)
+      - Per-item spikes            (sustained 1-6 months, clear amplitude)
+      - Global macro events        (rare, wide, correlated across items)
+      - Poisson sampling
+    """
+    rng = np.random.default_rng(seed)
+    n_items = len(item_ids)
+
+    spy = 365
+    spw = 7
+
+    t = np.arange(n_steps, dtype=np.float64)
+    yearly_phase = 2 * np.pi * t / spy
+    weekly_phase = 2 * np.pi * (t % spw) / spw
+
+    lam = np.zeros((n_steps, n_items), dtype=np.float64)
+
+    # Global macro events
+    gs = np.zeros(n_steps)
+    n_global = int(rng.integers(5, 12))
+    for _ in range(n_global):
+        si  = int(rng.integers(0, n_steps))
+        dur = int(rng.integers(180, 1100))
+        end = min(si + dur, n_steps)
+        h   = rng.uniform(0.20, 0.60)
+        for k in range(si, end):
+            p = (k - si) / max(dur, 1)
+            if p < 0.15:
+                gs[k] += h * (p / 0.15)
+            elif p < 0.75:
+                gs[k] += h
+            else:
+                gs[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+    for j, iid in enumerate(item_ids):
+        base = rng.uniform(*base_lambda_range)
+
+        ya1 = rng.uniform(0.12, 0.28)
+        ya2 = rng.uniform(0.04, 0.10)
+        yo  = rng.uniform(0, 2 * np.pi)
+        yr  = (ya1 * np.sin(yearly_phase + yo) +
+               ya2 * np.sin(2 * yearly_phase + yo * 0.7))
+
+        wa = rng.uniform(0.04, 0.10)
+        wo = rng.uniform(0, 2 * np.pi)
+        wy = wa * np.sin(weekly_phase + wo)
+
+        ac     = rng.uniform(0.9990, 0.9996)
+        ar_std = rng.uniform(0.008, 0.018)
+        dr = np.zeros(n_steps)
+        dr[0] = rng.normal(0, 0.10)
+        for i in range(1, n_steps):
+            dr[i] = ac * dr[i-1] + rng.normal(0, ar_std)
+        dr = np.clip(dr, -0.60, 0.60)
+
+        sr = rng.uniform(0.0002, 0.001)
+        sm = rng.random(n_steps) < sr
+        sp = np.zeros(n_steps)
+        for si in np.where(sm)[0]:
+            dur = int(rng.integers(30, 180))
+            end = min(si + dur, n_steps)
+            h   = rng.uniform(0.20, 0.70)
+            for k in range(si, end):
+                p = (k - si) / max(dur, 1)
+                if p < 0.15:
+                    sp[k] += h * (p / 0.15)
+                elif p < 0.75:
+                    sp[k] += h
+                else:
+                    sp[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+        gsens = rng.uniform(0.4, 1.2)
+        fac = 1.0 + yr + wy + dr + sp + gsens * gs
+        fac = np.clip(fac, 0.08, None)
+        lam[:, j] = base * fac
+
+    def demand_fn(day):
+        idx = day % n_steps
+        return {iid: int(rng.poisson(lam=max(0.01, lam[idx, j])))
+                for j, iid in enumerate(item_ids)}
+
+    return demand_fn, lam
+
+
+# ============================================================================
+# Build example simulation  (200-item variant)
+# ============================================================================
+
+def build_example_simulation_from_adjacency(
+    seed=123,
+    horizon_days=52560,
+    pipeline_multiplier=3.0,
+    streaming_out_dir=None,
+    packing="greedy",
+):
+    """
+    Day-level supply chain: 1 step = 1 day, 52560 days = 144 years.
+    Multi-echelon design:
+      Sources: magic replenishment (factory)
+      Intermediate nodes: pull from upstream via network edges
+      Per-tier (s,S) calibrated to flow rate and upstream lead time
+    """
+    random.seed(2025)
+    item_ids = [f"I{i:03d}" for i in range(1, 201)]              # 200 items
+    items = {iid: Item(iid, round(random.uniform(1.0, 4.0), 2))
+             for iid in item_ids}
+
+    def make_pol(inv_base=4000, inv_var=500,
+                 s_base=600,   s_var=100,
+                 S_base=6000,  S_var=500,
+                 lt_mean=5,    lt_var=1):
+        inv, s, S, lt = {}, {}, {}, {}
+        for iid in item_ids:
+            si = max(0, int(round(s_base + random.uniform(-s_var, s_var))))
+            Si = max(si + 1, int(round(
+                S_base + random.uniform(-S_var, S_var))))
+            ii = int(round(inv_base + random.uniform(-inv_var, inv_var)))
+            ii = max(si, min(Si, max(0, ii)))
+            li = max(1, int(round(
+                lt_mean + random.uniform(-lt_var, lt_var))))
+            s[iid], S[iid], inv[iid], lt[iid] = si, Si, ii, li
+        return inv, s, S, lt
+
+    nodes_meta = [
+        {"id": "NewYork",      "lat": 40.7128, "lon": -74.0060,
+         "is_destination": True,
+         "inventory": {iid: 600 for iid in item_ids},
+         "backlog":   {iid: 0   for iid in item_ids}},
+
+        {"id": "SanFrancisco", "lat": 37.7749, "lon": -122.4194,
+         "is_source": True},
+        {"id": "StLouis",      "lat": 38.6270, "lon":  -90.1994,
+         "is_source": True},
+        {"id": "Orlando",      "lat": 28.5383, "lon":  -81.3792,
+         "is_source": True},
+        {"id": "Nashville",    "lat": 36.1627, "lon":  -86.7816},
+        {"id": "Atlanta",      "lat": 33.7490, "lon":  -84.3880},
+        {"id": "Chicago",      "lat": 41.8781, "lon":  -87.6298},
+        {"id": "Charlotte",    "lat": 35.2271, "lon":  -80.8431},
+        {"id": "Columbus",     "lat": 39.9612, "lon":  -82.9988},
+        {"id": "Richmond",     "lat": 37.5407, "lon":  -77.4360},
+        {"id": "Philadelphia", "lat": 39.9526, "lon":  -75.1652},
+        {"id": "Baltimore",    "lat": 39.2904, "lon":  -76.6122},
+        {"id": "Memphis",      "lat": 35.1495, "lon":  -90.0490},
+    ]
+
+    tier_params = {
+        "SanFrancisco": dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "StLouis":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "Orlando":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "Nashville":    dict(inv_base=8000, inv_var=800,
+                             s_base=1000, s_var=150,
+                             S_base=8000, S_var=800,
+                             lt_mean=3,   lt_var=1),
+        "Atlanta":      dict(inv_base=6000, inv_var=600,
+                             s_base=500,  s_var=80,
+                             S_base=6000, S_var=600,
+                             lt_mean=1,   lt_var=0),
+        "Chicago":      dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=8,   lt_var=1),
+        "Charlotte":    dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=7,   lt_var=1),
+        "Memphis":      dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=7,   lt_var=1),
+        "Columbus":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        "Richmond":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        "Philadelphia": dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=1,   lt_var=0),
+        "Baltimore":    dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=2,   lt_var=0),
+    }
+
+    for m in nodes_meta:
+        nid = m["id"]
+        if m.get("is_destination", False):
+            continue
+        inv, s, S, lt = make_pol(**tier_params[nid])
+        m["inventory"]      = inv
+        m["s_levels"]       = s
+        m["S_levels"]       = S
+        m["lead_time_mean"] = lt
+
+    n = len(nodes_meta)
+    adj = [[None]*n for _ in range(n)]
+    idx = {m["id"]: i for i, m in enumerate(nodes_meta)}
+
+    def se(u, v, tt, cv, nc):
+        adj[idx[u]][idx[v]] = (tt, cv, nc)
+
+    # Travel times in days; upstream capacity generous (not bottleneck)
+    se("SanFrancisco", "Nashville",    4, 20000.0, 3)
+    se("StLouis",      "Nashville",    2, 20000.0, 3)
+    se("Orlando",      "Nashville",    2, 20000.0, 3)
+    se("Nashville",    "Atlanta",      1, 60000.0, 3)
+    se("Atlanta",      "Chicago",      8, 16000.0, 3)
+    se("Atlanta",      "Charlotte",    7, 16000.0, 3)
+    se("Atlanta",      "Memphis",      7, 16000.0, 3)
+    se("Chicago",      "Columbus",     2, 16000.0, 3)
+    se("Charlotte",    "Richmond",     2, 16000.0, 3)
+    se("Columbus",     "Philadelphia", 2, 16000.0, 3)
+    se("Richmond",     "Philadelphia", 1, 16000.0, 3)
+    se("Richmond",     "Baltimore",    3, 12000.0, 3)
+    se("Columbus",     "Baltimore",    3, 12000.0, 3)
+    se("Memphis",      "Baltimore",    2, 12000.0, 3)
+    # Last-mile: placeholder, overwritten dynamically below
+    se("Philadelphia", "NewYork",      1,  4000.0, 3)
+    se("Baltimore",    "NewYork",      2,  4000.0, 3)
+
+    net = build_network_from_adjacency(nodes_meta, adj)
+
+    print("Building day-level demand signals (200 items)...")
+    demand_fn, demand_signals = build_demand_fn(
+        item_ids, horizon_days, seed,
+        base_lambda_range=(80, 250))
+    print(f"  Shape: {demand_signals.shape}  "
+          f"({horizon_days} days ≈ {horizon_days/365:.0f} years)")
+    print(f"  Lambda: mean={demand_signals.mean():.1f}  "
+          f"min={demand_signals.min():.1f}  "
+          f"max={demand_signals.max():.1f}")
+
+    actual_mean_lam = float(demand_signals.mean())
+    avg_vol = 2.5
+    n_items = len(item_ids)
+    total_demand_vol = n_items * actual_mean_lam * avg_vol
+    target_ratio = 1.20
+    packing_eff   = 0.93
+    raw_needed    = total_demand_vol * target_ratio / packing_eff
+    philadelphia_cv = round(raw_needed * 0.55 / 3 / 100) * 100
+    baltimore_cv    = round(raw_needed * 0.45 / 3 / 100) * 100
+    net.edges[("Philadelphia", "NewYork")].container_volume = float(philadelphia_cv)
+    net.edges[("Baltimore",    "NewYork")].container_volume = float(baltimore_cv)
+    for eid in [("Philadelphia", "NewYork"), ("Baltimore", "NewYork")]:
+        e = net.edges[eid]
+        net.weight_cache[eid] = e.travel_time_days / max(
+            e.daily_total_capacity, 1e-9)
+    last_mile_cap = (philadelphia_cv + baltimore_cv) * 3
+    print(f"  Demand vol: {total_demand_vol:.0f}/day  "
+          f"Last-mile cap: {last_mile_cap:.0f}/day  "
+          f"Ratio: {last_mile_cap/total_demand_vol:.1%}  "
+          f"(Philadelphia={philadelphia_cv:.0f} Baltimore={baltimore_cv:.0f})")
+
+    sim = SupplyChainSimulation(
+        network=net,
+        items=items,
+        destination_id="NewYork",
+        demand_fn=demand_fn,
+        horizon_days=horizon_days,
+        seed=seed,
+        pipeline_multiplier=pipeline_multiplier,
+        streaming_out_dir=streaming_out_dir,
+        packing=packing)
+
+    return sim, net, items, demand_signals
+
+
+# ============================================================================
+# Folium helpers
+# ============================================================================
+
+def plot_network_folium(network, tiles="cartodbpositron", zoom_start=5):
+    lats = [n.lat for n in network.nodes.values()]
+    lons = [n.lon for n in network.nodes.values()]
+    c = (sum(lats)/len(lats), sum(lons)/len(lons))
+    m = folium.Map(location=c, zoom_start=zoom_start, tiles=tiles)
+    for (u, v), e in network.edges.items():
+        nu, nv = network.nodes[u], network.nodes[v]
+        folium.PolyLine(
+            [(nu.lat, nu.lon), (nv.lat, nv.lon)],
+            weight=2, opacity=0.7,
+            tooltip=f"{u}→{v} t={e.travel_time_days:.0f}d "
+                    f"cap={e.daily_total_capacity:.0f}/day").add_to(m)
+    for nid, n in network.nodes.items():
+        folium.CircleMarker(
+            (n.lat, n.lon),
+            radius=6 if n.is_destination else 4, fill=True,
+            tooltip=f"{nid} dest={n.is_destination}").add_to(m)
+    return m
+
+
+def export_map_with_animation(
+    network, sdf, inv_df=None, bl_df=None, it_df=None,
+    out_html="supply_chain_map.html", start_date="2025-01-01",
+    zoom_start=5,
+):
+    m = plot_network_folium(network, zoom_start=zoom_start)
+    m.save(out_html)
+    return out_html
+
+
+# ============================================================================
+# CLI
+# ============================================================================
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser(
+        description="Supply Chain Simulation — day-level, 52560-step, "
+                    "200-item variant")
+    ap.add_argument("--days",          type=int,   default=52560)
+    ap.add_argument("--seed",          type=int,   default=2025)
+    ap.add_argument("--out_dir",       type=str,   default="test_output")
+    ap.add_argument("--pipeline_mult", type=float, default=0.0,
+                    help="Days of EMA demand to keep in pipeline. "
+                         "0 = reactive mode (backlog + 3-day buffer).")
+    ap.add_argument("--no_streaming",  action="store_true")
+    args = ap.parse_args()
+
+    streaming = not args.no_streaming and args.days > 500
+
+    print("=== Supply Chain Simulation (Multi-Echelon, 200 items) ===")
+    print(f"  Days: {args.days:,} ({args.days/365:.1f} years)  "
+          f"Seed: {args.seed}")
+    print(f"  1 step = 1 day | 365 = 1 year | 52560 = 144 years")
+    print(f"  Items: 200  Pipeline: {args.pipeline_mult}  "
+          f"Streaming: {streaming}")
+    print()
+
+    sim, net, items, dsig = build_example_simulation_from_adjacency(
+        seed=args.seed,
+        horizon_days=args.days,
+        pipeline_multiplier=args.pipeline_mult,
+        streaming_out_dir=args.out_dir if streaming else None,
+        packing="greedy")
+
+    dd, ds, svc, di, db, dt = sim.run()
+
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    # Save demand signals
+    print("Saving demand signals...")
+    np.save(os.path.join(args.out_dir, "demand_signals.npy"),
+            dsig[:args.days])
+    with open(os.path.join(args.out_dir, "demand_signals_cols.txt"), "w") as f:
+        f.write(",".join(sorted(items.keys())) + "\n")
+    print(f"  Saved shape={dsig[:args.days].shape}")
+
+    if not streaming:
+        dd.to_csv(os.path.join(args.out_dir, "daily_records.csv"),
+                  index=False)
+        ds.to_csv(os.path.join(args.out_dir, "shipments.csv"), index=False)
+        svc.to_csv(os.path.join(args.out_dir, "service_summary.csv"),
+                   index=False)
+        if args.days <= 500:
+            di.to_csv(os.path.join(args.out_dir, "inventory_history.csv"),
+                      index=False)
+            db.to_csv(os.path.join(args.out_dir, "backlog_history.csv"),
+                      index=False)
+            dt.to_csv(os.path.join(args.out_dir, "intransit_history.csv"),
+                      index=False)
+
+    fr = svc['fill_rate_stock_only']
+    print(f"\n=== Service Summary (200 items) ===")
+    print(f"  Fill rate: mean={fr.mean():.3f}  "
+          f"median={fr.median():.3f}  "
+          f"min={fr.min():.3f}  max={fr.max():.3f}")
+    print(f"  Total demand:  {svc['total_demand'].sum():,}")
+    print(f"  Total served:  {svc['served_from_stock'].sum():,}")
+    print(f"  Total backlog: {svc['new_backlog_added'].sum():,}")
+    print(f"\nOutputs → {args.out_dir}/")

simulator/Supplychaingeo_item50.py

@@ -0,0 +1,1195 @@
+"""
+Supply Chain Simulation — Day-level, 52560-step.
+
+1 step = 1 day | 365 steps = 1 year | 52560 steps = 144 years
+
+logic:
+  - (s,S) inventory policy at warehouses
+  - Dijkstra routing (weight = travel_time / daily_capacity)
+  - Greedy first-fit bin packing
+  - Proactive shipping via pipeline_multiplier
+  - Streaming CSV for large runs
+
+Multi-echelon:
+  - Only source nodes (SF, StLouis, Orlando) retain magic replenishment
+  - Intermediate nodes pull inventory from upstream via network edges
+  - Per-tier (s,S) parameters calibrated to demand flow
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple, Optional, Any, Callable
+import math
+import heapq
+import random
+import os
+import csv
+import time as _time_module
+from datetime import datetime, timedelta
+import io
+import base64
+
+try:
+    import matplotlib.pyplot as plt
+    from branca.element import Element
+except ImportError:
+    pass
+
+import numpy as np
+import pandas as pd
+
+try:
+    import folium
+    from folium.plugins import TimestampedGeoJson
+    HAS_FOLIUM = True
+except ImportError:
+    HAS_FOLIUM = False
+
+
+# ============================================================================
+# Data Structures
+# ============================================================================
+
+@dataclass
+class Item:
+    item_id: str
+    volume: float
+
+
+@dataclass
+class Edge:
+    u: str
+    v: str
+    travel_time_days: float
+    container_volume: float
+    num_containers_per_day: int
+    daily_containers: List[float] = field(default_factory=list)
+
+    def reset_daily(self, capacity_factor: float = 1.0) -> None:
+        effective_vol = self.container_volume * capacity_factor
+        self.daily_containers = [effective_vol] * self.num_containers_per_day
+
+    def find_container_slot(self, item_volume: float) -> Optional[int]:
+        for idx, rem in enumerate(self.daily_containers):
+            if rem >= item_volume:
+                return idx
+        return None
+
+    def allocate_in_container(self, idx: int, item_volume: float) -> bool:
+        if 0 <= idx < len(self.daily_containers) and \
+                self.daily_containers[idx] >= item_volume:
+            self.daily_containers[idx] -= item_volume
+            return True
+        return False
+
+    @property
+    def daily_total_capacity(self) -> float:
+        return self.container_volume * max(self.num_containers_per_day, 0)
+
+
+@dataclass
+class Node:
+    node_id: str
+    lat: float
+    lon: float
+    is_destination: bool = False
+    is_source: bool = False                                        
+    inventory: Dict[str, int] = field(default_factory=dict)
+    s_levels: Dict[str, int] = field(default_factory=dict)
+    S_levels: Dict[str, int] = field(default_factory=dict)
+    lead_time_mean: Dict[str, float] = field(default_factory=dict)
+    lead_time_std_frac: float = 0.2
+    outstanding_orders: Dict[str, Optional[Tuple[int, int]]] = \
+        field(default_factory=dict)
+    backlog: Dict[str, int] = field(default_factory=dict)
+
+    def receive_orders_today(self, day: int) -> None:
+        to_clear = []
+        for item_id, order in self.outstanding_orders.items():
+            if order is None:
+                continue
+            arrival_day, qty = order
+            if day >= arrival_day:
+                self.inventory[item_id] = \
+                    self.inventory.get(item_id, 0) + qty
+                to_clear.append(item_id)
+        for iid in to_clear:
+            self.outstanding_orders[iid] = None
+
+    def maybe_place_orders(self, day: int, rng: random.Random) -> None:
+        if self.is_destination:
+            return
+        if not self.is_source:                                     
+            return                                                 
+        for item_id, s in self.s_levels.items():
+            on_hand = self.inventory.get(item_id, 0)
+            if on_hand < s and \
+                    self.outstanding_orders.get(item_id) is None:
+                S = self.S_levels.get(item_id, on_hand)
+                qty = max(S - on_hand, 0)
+                if qty <= 0:
+                    continue
+                mean_lt = max(self.lead_time_mean.get(item_id, 1.0), 0.1)
+                std = self.lead_time_std_frac * mean_lt
+                sampled = rng.normalvariate(mean_lt, std)
+                lt_days = max(1, int(math.ceil(sampled)))
+                self.outstanding_orders[item_id] = (day + lt_days, qty)
+
+
+# ============================================================================
+# Network + Dijkstra  
+# ============================================================================
+
+class Network:
+    def __init__(self) -> None:
+        self.nodes: Dict[str, Node] = {}
+        self.edges: Dict[Tuple[str, str], Edge] = {}
+        self.adj: Dict[str, List[str]] = {}
+        self.weight_cache: Dict[Tuple[str, str], float] = {}
+        self.paths_to_dest: Dict[
+            str, Tuple[float, List[str], List[Tuple[str, str]]]] = {}
+
+    def add_node(self, node: Node) -> None:
+        self.nodes[node.node_id] = node
+        self.adj.setdefault(node.node_id, [])
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges[(edge.u, edge.v)] = edge
+        self.adj.setdefault(edge.u, []).append(edge.v)
+        cap = max(edge.daily_total_capacity, 1e-9)
+        self.weight_cache[(edge.u, edge.v)] = edge.travel_time_days / cap
+
+    def reset_daily_edges(self, capacity_factor: float = 1.0) -> None:
+        for e in self.edges.values():
+            e.reset_daily(capacity_factor)
+
+    def dijkstra(self, source: str, target: str) -> Tuple[float, List[str]]:
+        if source == target:
+            return 0.0, [source]
+        dist: Dict[str, float] = {source: 0.0}
+        prev: Dict[str, Optional[str]] = {source: None}
+        pq = [(0.0, source)]
+        visited: set = set()
+        while pq:
+            d, u = heapq.heappop(pq)
+            if u in visited:
+                continue
+            visited.add(u)
+            if u == target:
+                break
+            for v in self.adj.get(u, []):
+                w = self.weight_cache[(u, v)]
+                nd = d + w
+                if nd < dist.get(v, float('inf')):
+                    dist[v] = nd
+                    prev[v] = u
+                    heapq.heappush(pq, (nd, v))
+        if target not in dist:
+            return float('inf'), []
+        path: List[str] = []
+        cur: Optional[str] = target
+        while cur is not None:
+            path.append(cur)
+            cur = prev.get(cur)
+        path.reverse()
+        return dist[target], path
+
+    def compute_paths_to_destination(self, dest_id: str) -> None:
+        self.paths_to_dest.clear()
+        for nid in self.nodes:
+            if nid == dest_id:
+                self.paths_to_dest[nid] = (0.0, [nid], [])
+                continue
+            d, pn = self.dijkstra(nid, dest_id)
+            if not pn:
+                self.paths_to_dest[nid] = (float('inf'), [], [])
+            else:
+                pe = [(pn[i], pn[i+1]) for i in range(len(pn)-1)]
+                self.paths_to_dest[nid] = (d, pn, pe)
+
+
+# ============================================================================
+# Greedy First-Fit Bin Packing  
+# ============================================================================
+
+def allocate_units_along_path_greedy(
+    item: Item,
+    max_units: int,
+    path_edges: List[Tuple[str, str]],
+    network_edges: Dict[Tuple[str, str], Edge],
+) -> int:
+    if max_units <= 0 or not path_edges:
+        return 0
+    edges_objs = [network_edges[eid] for eid in path_edges]
+    placed = 0
+    ivol = item.volume
+    for _ in range(max_units):
+        slots: List[Tuple[Edge, int]] = []
+        ok = True
+        for e in edges_objs:
+            si = e.find_container_slot(ivol)
+            if si is None:
+                ok = False
+                break
+            slots.append((e, si))
+        if not ok:
+            break
+        good = True
+        for e, si in slots:
+            if not e.allocate_in_container(si, ivol):
+                good = False
+                break
+        if not good:
+            break
+        placed += 1
+    return placed
+
+
+# ============================================================================
+# Simulation Engine
+# ============================================================================
+
+class SupplyChainSimulation:
+
+    def __init__(
+        self,
+        network: Network,
+        items: Dict[str, Item],
+        destination_id: str,
+        demand_fn: Callable[[int], Dict[str, int]],
+        horizon_days: int,
+        seed: int = 42,
+        pipeline_multiplier: float = 0.0,
+        streaming_out_dir: Optional[str] = None,
+        packing: str = "greedy",
+    ) -> None:
+        assert destination_id in network.nodes and \
+            network.nodes[destination_id].is_destination
+        self.network = network
+        self.items = items
+        self.item_order: List[str] = sorted(self.items.keys())
+        self.round_robin_items: bool = True
+        self.per_item_daily_cap_units: Optional[int] = None
+
+        self.destination_id = destination_id
+        self.demand_fn = demand_fn
+        self.horizon_days = horizon_days
+        self.rng = random.Random(seed)
+        self.packing = packing
+        self.pipeline_multiplier = pipeline_multiplier
+
+        # EMA warm-start at approximate per-day mean demand
+        self.demand_ema: Dict[str, float] = {iid: 165.0 for iid in items}
+        self.ema_alpha = 0.05
+        self.item_intransit: Dict[str, int] = {iid: 0 for iid in items}
+
+        self.streaming_out_dir = streaming_out_dir
+        self._csv_files: Dict = {}
+        self._csv_writers: Dict = {}
+        self._csv_buffers: Dict[str, list] = {}
+        self.dest_in_transit: Dict[int, Dict[str, int]] = {}
+
+        self.daily_records: list = []
+        self.shipments_log: list = []
+        self.inventory_history: list = []
+        self.backlog_history: list = []
+        self.intransit_history: list = []
+
+        self.svc_demand: Dict[str, int] = {iid: 0 for iid in items}
+        self.svc_served: Dict[str, int] = {iid: 0 for iid in items}
+        self.svc_backlog: Dict[str, int] = {iid: 0 for iid in items}
+
+        network.compute_paths_to_destination(destination_id)
+        self.sorted_warehouses = sorted(
+            [(nid, d) for nid, (d, _, _) in network.paths_to_dest.items()
+             if nid != destination_id and math.isfinite(d)],
+            key=lambda x: x[1])
+
+        # ── precompute supplier relationships ──────────────
+        self.node_suppliers: Dict[
+            str,
+            List[Tuple[str, float, List[str], List[Tuple[str, str]]]]
+        ] = {}
+        for nid, node in network.nodes.items():
+            if node.is_destination or node.is_source:
+                continue
+            suppliers = []
+            for (u, v) in network.edges:
+                if v == nid:
+                    d, path = network.dijkstra(u, nid)
+                    if path and math.isfinite(d):
+                        pe = [(path[i], path[i + 1])
+                              for i in range(len(path) - 1)]
+                        tt = sum(network.edges[e].travel_time_days
+                                 for e in pe)
+                        suppliers.append((u, tt, path, pe))
+            suppliers.sort(key=lambda x: x[1])
+            self.node_suppliers[nid] = suppliers
+
+        # intermediate nodes ordered upstream-first for replenishment
+        self.replenish_order: List[str] = [
+            nid for nid, _ in reversed(self.sorted_warehouses)
+            if nid in self.node_suppliers]
+
+        self.avg_travel_time = 6.0
+        if self.sorted_warehouses:
+            _, _, pe = network.paths_to_dest[self.sorted_warehouses[0][0]]
+            if pe:
+                self.avg_travel_time = sum(
+                    network.edges[e].travel_time_days for e in pe)
+
+    def _total_tt(self, pe):
+        return sum(self.network.edges[e].travel_time_days for e in pe)
+
+    def _replenish_warehouses(self, day: int) -> None:
+        """Inter-warehouse replenishment: intermediate nodes pull
+        from upstream suppliers using (s,S) trigger + edge capacity."""
+        net = self.network
+
+        # round-robin item fairness 
+        if self.round_robin_items and self.item_order:
+            k = day % len(self.item_order)
+            ids_today = self.item_order[k:] + self.item_order[:k]
+        else:
+            ids_today = self.item_order[:]
+
+        for nid in self.replenish_order:
+            node = net.nodes[nid]
+            for iid in ids_today:
+                on_hand = node.inventory.get(iid, 0)
+                s = node.s_levels.get(iid, 0)
+                if on_hand >= s:
+                    continue
+                if node.outstanding_orders.get(iid) is not None:
+                    continue
+                S = node.S_levels.get(iid, on_hand)
+                qty_needed = max(S - on_hand, 0)
+                if qty_needed <= 0:
+                    continue
+
+                for sup_id, tt, path, pe in \
+                        self.node_suppliers.get(nid, []):
+                    sup_node = net.nodes[sup_id]
+                    avail = sup_node.inventory.get(iid, 0)
+                    if avail <= 0:
+                        continue
+                    attempt = min(avail, qty_needed)
+                    placed = allocate_units_along_path_greedy(
+                        self.items[iid], attempt, pe, net.edges)
+                    if placed <= 0:
+                        continue
+
+                    sup_node.inventory[iid] -= placed
+                    arr = day + max(1, int(math.ceil(tt)))
+                    node.outstanding_orders[iid] = (arr, placed)
+
+                    # log (reuses existing shipments infrastructure)
+                    r = [day, arr, sup_id, nid, iid, placed,
+                         str(path),
+                         str([net.edges[e].travel_time_days
+                              for e in pe])]
+                    if self.streaming_out_dir:
+                        self._csv_buffers.setdefault(
+                            'ship', []).append(r)
+                    else:
+                        self.shipments_log.append({
+                            "day": day, "arrival_day": arr,
+                            "from": sup_id, "to": nid,
+                            "item": iid, "units": placed,
+                            "path_nodes": path,
+                            "edge_times": [
+                                net.edges[e].travel_time_days
+                                for e in pe]})
+                    break  
+
+    def step(self, day: int) -> None:
+        net = self.network
+        dest = net.nodes[self.destination_id]
+
+        # 1) Receive (s,S) replenishment at warehouses
+        for node in net.nodes.values():
+            node.receive_orders_today(day)
+
+        # 2) Arrivals at destination
+        arrivals = self.dest_in_transit.pop(day, {})
+        for iid, qty in arrivals.items():
+            self.item_intransit[iid] = max(
+                0, self.item_intransit.get(iid, 0) - qty)
+            bl = dest.backlog.get(iid, 0)
+            if bl > 0:
+                use = min(qty, bl)
+                dest.backlog[iid] = bl - use
+                qty -= use
+            if qty > 0:
+                dest.inventory[iid] = dest.inventory.get(iid, 0) + qty
+
+        # 3) Reset edge containers
+        net.reset_daily_edges(1.0)
+
+        # 4) Demand at destination
+        td = self.demand_fn(day)
+        for iid in self.items:
+            dq = int(td.get(iid, 0))
+            self.demand_ema[iid] = (
+                self.ema_alpha * dq +
+                (1 - self.ema_alpha) * self.demand_ema[iid])
+            oh = dest.inventory.get(iid, 0)
+            if oh >= dq:
+                served, unfilled = dq, 0
+                dest.inventory[iid] = oh - dq
+            else:
+                served, unfilled = oh, dq - oh
+                dest.inventory[iid] = 0
+                dest.backlog[iid] = dest.backlog.get(iid, 0) + unfilled
+            self.svc_demand[iid] += dq
+            self.svc_served[iid] += served
+            self.svc_backlog[iid] += unfilled
+            rec = [day, iid, dq, served, unfilled,
+                   dest.inventory.get(iid, 0), dest.backlog.get(iid, 0)]
+            if self.streaming_out_dir:
+                self._csv_buffers.setdefault('daily', []).append(rec)
+            else:
+                self.daily_records.append({
+                    "day": day, "item": iid, "demand": dq,
+                    "served_from_stock": served,
+                    "new_backlog_today": unfilled,
+                    "dest_on_hand_end_before_ship":
+                        dest.inventory.get(iid, 0),
+                    "dest_backlog_end_before_ship":
+                        dest.backlog.get(iid, 0)})
+
+        # 5) Ship
+        if self.round_robin_items and self.item_order:
+            k = day % len(self.item_order)
+            ids_today = self.item_order[k:] + self.item_order[:k]
+        else:
+            ids_today = self.item_order[:]
+
+        for iid in ids_today:
+            item = self.items[iid]
+            cb = dest.backlog.get(iid, 0)
+            it = self.item_intransit.get(iid, 0)
+            oh = dest.inventory.get(iid, 0)
+
+            if self.pipeline_multiplier > 0:
+                pt = self.demand_ema[iid] * self.pipeline_multiplier
+                ship_target = max(0, int(math.ceil(cb + pt - it - oh)))
+            else:
+                # Reactive: ship to cover backlog + 3 days of EMA demand
+                S_dest = max(1, int(self.demand_ema[iid] * 3))
+                ship_target = max(0, cb + S_dest - oh - it)
+
+            if ship_target <= 0:
+                continue
+
+            remaining = ship_target
+            shipped = 0
+            for wid, _ in self.sorted_warehouses:
+                if remaining <= 0:
+                    break
+                if self.per_item_daily_cap_units is not None and \
+                        shipped >= self.per_item_daily_cap_units:
+                    break
+                wn = net.nodes[wid]
+                avail = wn.inventory.get(iid, 0)
+                if avail <= 0:
+                    continue
+                _, pn, pe = net.paths_to_dest[wid]
+                if not pe:
+                    continue
+                attempt = min(avail, remaining)
+                if self.per_item_daily_cap_units is not None:
+                    attempt = min(attempt,
+                                  self.per_item_daily_cap_units - shipped)
+                placed = allocate_units_along_path_greedy(
+                    item, attempt, pe, net.edges)
+                if placed <= 0:
+                    continue
+                wn.inventory[iid] -= placed
+                remaining -= placed
+                shipped += placed
+                arr = day + max(1, int(math.ceil(self._total_tt(pe))))
+                self.dest_in_transit.setdefault(arr, {})
+                self.dest_in_transit[arr][iid] = \
+                    self.dest_in_transit[arr].get(iid, 0) + placed
+                self.item_intransit[iid] = \
+                    self.item_intransit.get(iid, 0) + placed
+                r = [day, arr, wid, self.destination_id, iid, placed,
+                     str(pn),
+                     str([net.edges[e].travel_time_days for e in pe])]
+                if self.streaming_out_dir:
+                    self._csv_buffers.setdefault('ship', []).append(r)
+                else:
+                    self.shipments_log.append({
+                        "day": day, "arrival_day": arr,
+                        "from": wid, "to": self.destination_id,
+                        "item": iid, "units": placed,
+                        "path_nodes": pn,
+                        "edge_times": [net.edges[e].travel_time_days
+                                       for e in pe]})
+
+        # 5b) Inter-warehouse replenishment                        
+        self._replenish_warehouses(day)                            
+
+        # 6) (s,S) orders at source warehouses
+        for node in net.nodes.values():
+            node.maybe_place_orders(day, self.rng)
+
+        # 7) Snapshots
+        did = self.destination_id
+        itc: Dict[str, int] = {}
+        for ad, im in self.dest_in_transit.items():
+            if ad > day:
+                for iid, q in im.items():
+                    itc[iid] = itc.get(iid, 0) + int(q)
+
+        if self.streaming_out_dir:
+            for node in net.nodes.values():
+                for iid in self.items:
+                    self._csv_buffers.setdefault('inv', []).append(
+                        [day, node.node_id, iid,
+                         int(node.inventory.get(iid, 0))])
+                    self._csv_buffers.setdefault('bl', []).append(
+                        [day, node.node_id, iid,
+                         int(node.backlog.get(iid, 0))])
+            for iid in self.items:
+                self._csv_buffers.setdefault('it', []).append(
+                    [day, did, iid, itc.get(iid, 0)])
+        else:
+            for node in net.nodes.values():
+                for iid in self.items:
+                    self.inventory_history.append({
+                        "day": day, "node": node.node_id, "item": iid,
+                        "on_hand": int(node.inventory.get(iid, 0))})
+                    self.backlog_history.append({
+                        "day": day, "node": node.node_id, "item": iid,
+                        "backlog": int(node.backlog.get(iid, 0))})
+            for iid in self.items:
+                self.intransit_history.append({
+                    "day": day, "node": did, "item": iid,
+                    "in_transit": itc.get(iid, 0)})
+
+    # --- CSV streaming ---
+    def _open_csv_files(self):
+        os.makedirs(self.streaming_out_dir, exist_ok=True)
+        hdrs = {
+            'daily': ["day", "item", "demand", "served_from_stock",
+                      "new_backlog_today", "dest_on_hand_end_before_ship",
+                      "dest_backlog_end_before_ship"],
+            'ship':  ["day", "arrival_day", "from", "to", "item",
+                      "units", "path_nodes", "edge_times"],
+            'inv':   ["day", "node", "item", "on_hand"],
+            'bl':    ["day", "node", "item", "backlog"],
+            'it':    ["day", "node", "item", "in_transit"],
+        }
+        fn = {'daily': 'daily_records', 'ship': 'shipments',
+              'inv': 'inventory_history', 'bl': 'backlog_history',
+              'it': 'intransit_history'}
+        for k in hdrs:
+            f = open(os.path.join(self.streaming_out_dir,
+                                  f"{fn[k]}.csv"),
+                     "w", newline="", buffering=65536)
+            w = csv.writer(f)
+            w.writerow(hdrs[k])
+            self._csv_files[k] = f
+            self._csv_writers[k] = w
+            self._csv_buffers[k] = []
+
+    def _flush_csv(self):
+        for k in self._csv_buffers:
+            if self._csv_buffers[k] and k in self._csv_writers:
+                self._csv_writers[k].writerows(self._csv_buffers[k])
+                self._csv_buffers[k] = []
+        for f in self._csv_files.values():
+            f.flush()
+
+    def _close_csv(self):
+        self._flush_csv()
+        for f in self._csv_files.values():
+            f.close()
+
+    def run(self):
+        if self.streaming_out_dir:
+            self._open_csv_files()
+        t0 = _time_module.time()
+        ri = max(1, self.horizon_days // 100)
+        for day in range(self.horizon_days):
+            self.step(day)
+            if self.streaming_out_dir and day % 500 == 0:
+                self._flush_csv()
+            if day % 5000 == 0:
+                for k in [k for k in self.dest_in_transit if k < day]:
+                    del self.dest_in_transit[k]
+            if day % ri == 0 or day == self.horizon_days - 1:
+                el = _time_module.time() - t0
+                pct = (day + 1) / self.horizon_days * 100
+                rate = (day + 1) / max(el, 0.001)
+                eta = (self.horizon_days - day - 1) / max(rate, 0.001)
+                print(f"\r  Day {day+1:>6}/{self.horizon_days} "
+                      f"({pct:5.1f}%) {rate:6.1f} days/s "
+                      f"ETA {eta:6.0f}s", end="", flush=True)
+        print(f"\n  Simulation complete in "
+              f"{_time_module.time()-t0:.1f}s")
+
+        if self.streaming_out_dir:
+            self._close_csv()
+            rows = []
+            for iid in sorted(self.items):
+                td = self.svc_demand[iid]
+                sv = self.svc_served[iid]
+                bl = self.svc_backlog[iid]
+                rows.append({
+                    "item": iid, "total_demand": td,
+                    "served_from_stock": sv,
+                    "new_backlog_added": bl,
+                    "fill_rate_stock_only":
+                        round(sv / td, 6) if td > 0 else 0.0})
+            svc = pd.DataFrame(rows)
+            svc.to_csv(os.path.join(self.streaming_out_dir,
+                                    "service_summary.csv"), index=False)
+            return (pd.DataFrame(), pd.DataFrame(), svc,
+                    pd.DataFrame(), pd.DataFrame(), pd.DataFrame())
+
+        dd = pd.DataFrame(self.daily_records)
+        ds = pd.DataFrame(self.shipments_log) if self.shipments_log \
+            else pd.DataFrame(columns=[
+                "day", "arrival_day", "from", "to",
+                "item", "units", "path_nodes", "edge_times"])
+        svc = dd.groupby("item", as_index=False).agg(
+            total_demand=("demand", "sum"),
+            served_from_stock=("served_from_stock", "sum"),
+            new_backlog_added=("new_backlog_today", "sum"))
+        svc["fill_rate_stock_only"] = (
+            svc["served_from_stock"] / svc["total_demand"]).fillna(0)
+        di = pd.DataFrame(self.inventory_history,
+                          columns=["day", "node", "item", "on_hand"])
+        db = pd.DataFrame(self.backlog_history,
+                          columns=["day", "node", "item", "backlog"])
+        dt = pd.DataFrame(self.intransit_history,
+                          columns=["day", "node", "item", "in_transit"])
+        return dd, ds, svc, di, db, dt
+
+
+# ============================================================================
+# Build network from adjacency
+# ============================================================================
+
+def build_network_from_adjacency(nodes_meta, adjacency):
+    n = len(nodes_meta)
+    assert all(len(r) == n for r in adjacency)
+    net = Network()
+    for meta in nodes_meta:
+        net.add_node(Node(
+            node_id=meta["id"],
+            lat=float(meta["lat"]), lon=float(meta["lon"]),
+            is_destination=bool(meta.get("is_destination", False)),
+            is_source=bool(meta.get("is_source", False)),          
+            inventory=dict(meta.get("inventory", {})),
+            s_levels=dict(meta.get("s_levels", {})),
+            S_levels=dict(meta.get("S_levels", {})),
+            lead_time_mean=dict(meta.get("lead_time_mean", {})),
+            backlog=dict(meta.get("backlog", {}))))
+    ids = [m["id"] for m in nodes_meta]
+    for i in range(n):
+        for j in range(n):
+            s = adjacency[i][j]
+            if s is None:
+                continue
+            tt, cv, nc = s
+            net.add_edge(Edge(
+                u=ids[i], v=ids[j],
+                travel_time_days=float(tt),
+                container_volume=float(cv),
+                num_containers_per_day=int(nc)))
+    return net
+
+
+# ============================================================================
+# Demand Generator  — day-level, 52560-step 
+# ============================================================================
+
+def build_demand_fn(
+    item_ids, n_steps, seed=42,
+    base_lambda_range=(80, 250),
+    scenario=None,
+):
+    """
+
+    Structure:
+      - Yearly cycle   T=365 days  (moderate amplitude, two harmonics)
+      - Weekly cycle   T=7 days    (small texture)
+      - AR(1) drift                (dominant low-frequency, decade-scale)
+      - Per-item spikes            (sustained 1-6 months, clear amplitude)
+      - Global macro events        (rare, wide, correlated across items)
+      - Poisson sampling
+    """
+
+    rng = np.random.default_rng(seed)
+    n_items = len(item_ids)
+
+    sc = scenario or {}
+    phi_lo             = float(sc.get("phi_lo", 0.9990))
+    phi_hi             = float(sc.get("phi_hi", 0.9996))
+    shock_count_scale  = float(sc.get("shock_count_scale", 1.0))
+    shock_height_scale = float(sc.get("shock_height_scale", 1.0))
+    seasonal_scale     = float(sc.get("seasonal_scale", 1.0))
+    burst_rate_scale   = float(sc.get("burst_rate_scale", 1.0))
+    burst_height_scale = float(sc.get("burst_height_scale", 1.0))
+
+    spy = 365   # yearly period
+    spw = 7     # weekly period
+
+    t = np.arange(n_steps, dtype=np.float64)
+    yearly_phase = 2 * np.pi * t / spy
+    weekly_phase = 2 * np.pi * (t % spw) / spw
+
+    lam = np.zeros((n_steps, n_items), dtype=np.float64)
+
+    # Global macro events: rare, long, meaningful
+    gs = np.zeros(n_steps)
+    base_n_global = rng.integers(5, 12)
+    n_global = max(0, int(round(float(base_n_global) * shock_count_scale)))
+    for _ in range(n_global):
+        si  = int(rng.integers(0, n_steps))
+        dur = int(rng.integers(180, 1100))
+        end = min(si + dur, n_steps)
+        h   = rng.uniform(0.20, 0.60) * shock_height_scale
+        for k in range(si, end):
+            p = (k - si) / max(dur, 1)
+            if p < 0.15:
+                gs[k] += h * (p / 0.15)
+            elif p < 0.75:
+                gs[k] += h
+            else:
+                gs[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+    for j, iid in enumerate(item_ids):
+        base = rng.uniform(*base_lambda_range)
+
+        # Yearly: two harmonics so shape is not a perfect sine
+        ya1 = rng.uniform(0.12, 0.28) * seasonal_scale
+        ya2 = rng.uniform(0.04, 0.10) * seasonal_scale
+        yo  = rng.uniform(0, 2 * np.pi)
+        yr  = (ya1 * np.sin(yearly_phase + yo) +
+               ya2 * np.sin(2 * yearly_phase + yo * 0.7))
+
+        # Weekly: small texture only
+        wa = rng.uniform(0.04, 0.10)
+        wo = rng.uniform(0, 2 * np.pi)
+        wy = wa * np.sin(weekly_phase + wo)
+
+        # AR(1): dominant low-frequency component
+        ac     = rng.uniform(phi_lo, phi_hi)
+        ar_std = rng.uniform(0.008, 0.018)
+        dr = np.zeros(n_steps)
+        dr[0] = rng.normal(0, 0.10)
+        for i in range(1, n_steps):
+            dr[i] = ac * dr[i-1] + rng.normal(0, ar_std)
+        dr = np.clip(dr, -0.60, 0.60)
+
+        # Per-item spikes
+        sr = rng.uniform(0.0002, 0.001) * burst_rate_scale
+        sm = rng.random(n_steps) < sr
+        sp = np.zeros(n_steps)
+        for si in np.where(sm)[0]:
+            dur = int(rng.integers(30, 180))
+            end = min(si + dur, n_steps)
+            h   = rng.uniform(0.20, 0.70) * burst_height_scale
+            for k in range(si, end):
+                p = (k - si) / max(dur, 1)
+                if p < 0.15:
+                    sp[k] += h * (p / 0.15)
+                elif p < 0.75:
+                    sp[k] += h
+                else:
+                    sp[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+        gsens = rng.uniform(0.4, 1.2)
+        fac = 1.0 + yr + wy + dr + sp + gsens * gs
+        fac = np.clip(fac, 0.08, None)
+        lam[:, j] = base * fac
+
+    def demand_fn(day):
+        idx = day % n_steps
+        return {iid: int(rng.poisson(lam=max(0.01, lam[idx, j])))
+                for j, iid in enumerate(item_ids)}
+
+    return demand_fn, lam
+
+
+# ============================================================================
+# Build example simulation
+# ============================================================================
+
+def build_example_simulation_from_adjacency(
+    seed=123,
+    horizon_days=52560,
+    pipeline_multiplier=3.0,
+    streaming_out_dir=None,
+    packing="greedy",
+    scenario=None,
+):
+    """
+    Day-level supply chain: 1 step = 1 day, 52560 days = 144 years.
+
+    Multi-echelon design:
+      Sources (SF, StLouis, Orlando): magic replenishment (factory)
+      Intermediate nodes: pull from upstream via network edges
+      Per-tier (s,S) calibrated to flow rate and upstream lead time
+    """
+    random.seed(2025)
+    item_ids = [f"I{i:02d}" for i in range(1, 51)]
+    items = {iid: Item(iid, round(random.uniform(1.0, 4.0), 2))
+             for iid in item_ids}
+
+    sc_local = scenario or {}
+    ss_scale       = float(sc_local.get("ss_scale", 1.0))
+    leadtime_scale = float(sc_local.get("leadtime_scale", 1.0))
+
+    def make_pol(inv_base=4000, inv_var=500,
+                 s_base=600,   s_var=100,
+                 S_base=6000,  S_var=500,
+                 lt_mean=5,    lt_var=1):
+        inv_base = inv_base * ss_scale
+        inv_var  = inv_var  * ss_scale
+        s_base   = s_base   * ss_scale
+        s_var    = s_var    * ss_scale
+        S_base   = S_base   * ss_scale
+        S_var    = S_var    * ss_scale
+        lt_mean  = lt_mean  * leadtime_scale
+        lt_var   = lt_var   * leadtime_scale
+        inv, s, S, lt = {}, {}, {}, {}
+        for iid in item_ids:
+            si = max(0, int(round(s_base + random.uniform(-s_var, s_var))))
+            Si = max(si + 1, int(round(
+                S_base + random.uniform(-S_var, S_var))))
+            ii = int(round(inv_base + random.uniform(-inv_var, inv_var)))
+            ii = max(si, min(Si, max(0, ii)))
+            li = max(1, int(round(
+                lt_mean + random.uniform(-lt_var, lt_var))))
+            s[iid], S[iid], inv[iid], lt[iid] = si, Si, ii, li
+        return inv, s, S, lt
+
+    nodes_meta = [
+        {"id": "NewYork",      "lat": 40.7128, "lon": -74.0060,
+         "is_destination": True,
+         "inventory": {iid: 600 for iid in item_ids},
+         "backlog":   {iid: 0   for iid in item_ids}},
+
+        {"id": "SanFrancisco", "lat": 37.7749, "lon": -122.4194,
+         "is_source": True},
+        {"id": "StLouis",      "lat": 38.6270, "lon":  -90.1994,
+         "is_source": True},
+        {"id": "Orlando",      "lat": 28.5383, "lon":  -81.3792,
+         "is_source": True},
+        {"id": "Nashville",    "lat": 36.1627, "lon":  -86.7816},
+        {"id": "Atlanta",      "lat": 33.7490, "lon":  -84.3880},
+        {"id": "Chicago",      "lat": 41.8781, "lon":  -87.6298},
+        {"id": "Charlotte",    "lat": 35.2271, "lon":  -80.8431},
+        {"id": "Memphis",      "lat": 35.1495, "lon":  -90.0490},
+        {"id": "Columbus",     "lat": 39.9612, "lon":  -82.9988},
+        {"id": "Richmond",     "lat": 37.5407, "lon":  -77.4360},
+        {"id": "Philadelphia", "lat": 39.9526, "lon":  -75.1652},
+        {"id": "Baltimore",    "lat": 39.2904, "lon":  -76.6122},
+    ]
+
+    tier_params = {
+        # Sources — magic replenishment (factory production)
+        "SanFrancisco": dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "StLouis":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "Orlando":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        # Tier-1 
+        "Nashville":    dict(inv_base=8000, inv_var=800,
+                             s_base=1000, s_var=150,
+                             S_base=8000, S_var=800,
+                             lt_mean=3,   lt_var=1),
+        # Tier-2 
+        "Atlanta":      dict(inv_base=6000, inv_var=600,
+                             s_base=500,  s_var=80,
+                             S_base=6000, S_var=600,
+                             lt_mean=1,   lt_var=0),
+        # Tier-3 
+        "Chicago":      dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=8,   lt_var=1),
+        "Charlotte":    dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=7,   lt_var=1),
+        "Memphis":      dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=7,   lt_var=1),
+        # Tier-4 
+        "Columbus":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        "Richmond":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        # Tier-5 
+        "Philadelphia": dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=1,   lt_var=0),
+        "Baltimore":    dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=2,   lt_var=0),
+    }
+
+    for m in nodes_meta:
+        nid = m["id"]
+        if m.get("is_destination", False):
+            continue
+        inv, s, S, lt = make_pol(**tier_params[nid])
+        m["inventory"]      = inv
+        m["s_levels"]       = s
+        m["S_levels"]       = S
+        m["lead_time_mean"] = lt
+
+    n = len(nodes_meta)
+    adj = [[None]*n for _ in range(n)]
+    idx = {m["id"]: i for i, m in enumerate(nodes_meta)}
+
+    def se(u, v, tt, cv, nc):
+        adj[idx[u]][idx[v]] = (tt, cv, nc)
+
+    # Travel times in days; upstream capacity generous (not bottleneck)
+    se("SanFrancisco", "Nashville",    4, 5000.0, 3)
+    se("StLouis",      "Nashville",    2, 5000.0, 3)
+    se("Orlando",      "Nashville",    2, 5000.0, 3)
+    se("Nashville",    "Atlanta",      1, 15000.0, 3)
+    se("Atlanta",      "Chicago",      8, 4000.0, 3)
+    se("Atlanta",      "Charlotte",    7, 4000.0, 3)
+    se("Atlanta",      "Memphis",      7, 4000.0, 3)
+    se("Chicago",      "Columbus",     2, 4000.0, 3)
+    se("Charlotte",    "Richmond",     2, 4000.0, 3)
+    se("Columbus",     "Philadelphia", 2, 4000.0, 3)
+    se("Richmond",     "Philadelphia", 1, 4000.0, 3)
+    se("Richmond",     "Baltimore",    3, 3000.0, 3)
+    se("Columbus",     "Baltimore",    3, 3000.0, 3)
+    se("Memphis",      "Baltimore",    2, 3000.0, 3)
+    # Last-mile: placeholder, overwritten dynamically below
+    se("Philadelphia", "NewYork",      1, 1000.0, 3)
+    se("Baltimore",    "NewYork",      2, 1000.0, 3)
+
+    net = build_network_from_adjacency(nodes_meta, adj)
+
+    sc = scenario or {}
+    containers_scale = float(sc.get("containers_scale", 1.0))
+    if containers_scale != 1.0:
+        for eid, e in net.edges.items():
+            e.num_containers_per_day = max(
+                1, int(round(e.num_containers_per_day * containers_scale)))
+
+    base_lambda_lo = float(sc.get("base_lambda_lo", 80))
+    base_lambda_hi = float(sc.get("base_lambda_hi", 250))
+
+    print("Building day-level demand signals...")
+    demand_fn, demand_signals = build_demand_fn(
+        item_ids, horizon_days, seed,
+        base_lambda_range=(base_lambda_lo, base_lambda_hi),
+        scenario=scenario)
+    print(f"  Shape: {demand_signals.shape}  "
+          f"({horizon_days} days ≈ {horizon_days/365:.0f} years)")
+    print(f"  Lambda: mean={demand_signals.mean():.1f}  "
+          f"min={demand_signals.min():.1f}  "
+          f"max={demand_signals.max():.1f}")
+
+    # Set last-mile capacity dynamically based on actual lambda mean
+    actual_mean_lam = float(demand_signals.mean())
+    avg_vol = 2.5
+    total_demand_vol = 50 * actual_mean_lam * avg_vol
+    target_ratio = 1.20
+    packing_eff   = 0.93
+    raw_needed    = total_demand_vol * target_ratio / packing_eff
+    philadelphia_cv = round(raw_needed * 0.55 / 3 / 100) * 100  
+    baltimore_cv    = round(raw_needed * 0.45 / 3 / 100) * 100  
+    net.edges[("Philadelphia", "NewYork")].container_volume = float(philadelphia_cv)
+    net.edges[("Baltimore",    "NewYork")].container_volume = float(baltimore_cv)
+    for eid in [("Philadelphia", "NewYork"), ("Baltimore", "NewYork")]:
+        e = net.edges[eid]
+        net.weight_cache[eid] = e.travel_time_days / max(
+            e.daily_total_capacity, 1e-9)
+    last_mile_cap = (philadelphia_cv + baltimore_cv) * 3
+    print(f"  Demand vol: {total_demand_vol:.0f}/day  "
+          f"Last-mile cap: {last_mile_cap:.0f}/day  "
+          f"Ratio: {last_mile_cap/total_demand_vol:.1%}  "
+          f"(Philadelphia={philadelphia_cv:.0f} Baltimore={baltimore_cv:.0f})")
+    sim = SupplyChainSimulation(
+        network=net,
+        items=items,
+        destination_id="NewYork",
+        demand_fn=demand_fn,
+        horizon_days=horizon_days,
+        seed=seed,
+        pipeline_multiplier=pipeline_multiplier,
+        streaming_out_dir=streaming_out_dir,
+        packing=packing)
+
+    return sim, net, items, demand_signals
+
+
+# ============================================================================
+# Folium helpers 
+# ============================================================================
+
+def plot_network_folium(network, tiles="cartodbpositron", zoom_start=5):
+    lats = [n.lat for n in network.nodes.values()]
+    lons = [n.lon for n in network.nodes.values()]
+    c = (sum(lats)/len(lats), sum(lons)/len(lons))
+    m = folium.Map(location=c, zoom_start=zoom_start, tiles=tiles)
+    for (u, v), e in network.edges.items():
+        nu, nv = network.nodes[u], network.nodes[v]
+        folium.PolyLine(
+            [(nu.lat, nu.lon), (nv.lat, nv.lon)],
+            weight=2, opacity=0.7,
+            tooltip=f"{u}→{v} t={e.travel_time_days:.0f}d "
+                    f"cap={e.daily_total_capacity:.0f}/day").add_to(m)
+    for nid, n in network.nodes.items():
+        folium.CircleMarker(
+            (n.lat, n.lon),
+            radius=6 if n.is_destination else 4, fill=True,
+            tooltip=f"{nid} dest={n.is_destination}").add_to(m)
+    return m
+
+
+def export_map_with_animation(
+    network, sdf, inv_df=None, bl_df=None, it_df=None,
+    out_html="supply_chain_map.html", start_date="2025-01-01",
+    zoom_start=5,
+):
+    m = plot_network_folium(network, zoom_start=zoom_start)
+    m.save(out_html)
+    return out_html
+
+
+# ============================================================================
+# CLI
+# ============================================================================
+
+if __name__ == "__main__":
+    import argparse
+    ap = argparse.ArgumentParser(
+        description="Supply Chain Simulation — day-level, 52560-step")
+    ap.add_argument("--days",          type=int,   default=52560)
+    ap.add_argument("--seed",          type=int,   default=2025)
+    ap.add_argument("--out_dir",       type=str,   default="test_output")
+    ap.add_argument("--pipeline_mult", type=float, default=0.0,
+                    help="Days of EMA demand to keep in pipeline. "
+                         "0 = reactive mode (backlog + 3-day buffer).")
+    ap.add_argument("--no_streaming",  action="store_true")
+    # Scenario / perturbation overrides (Exp C mixture). Defaults match the
+    # released baseline configuration byte-for-byte.
+    ap.add_argument("--phi_lo",             type=float, default=0.9990)
+    ap.add_argument("--phi_hi",             type=float, default=0.9996)
+    ap.add_argument("--shock_count_scale",  type=float, default=1.0)
+    ap.add_argument("--shock_height_scale", type=float, default=1.0)
+    ap.add_argument("--seasonal_scale",     type=float, default=1.0)
+    ap.add_argument("--containers_scale",   type=float, default=1.0)
+    ap.add_argument("--ss_scale",           type=float, default=1.0,
+                    help="Multiplier on (s_n, S_n) reorder/target levels "
+                         "(and initial inventory) at every non-destination "
+                         "node. 1.0 reproduces the released baseline.")
+    ap.add_argument("--leadtime_scale",     type=float, default=1.0,
+                    help="Multiplier on per-tier mean source lead time "
+                         "mu^n. 1.0 reproduces the released baseline.")
+    ap.add_argument("--burst_rate_scale",   type=float, default=1.0,
+                    help="Multiplier on per-item idiosyncratic burst "
+                         "Bernoulli rate sr. 1.0 reproduces baseline; "
+                         "values >1 increase per-item-burst frequency.")
+    ap.add_argument("--burst_height_scale", type=float, default=1.0,
+                    help="Multiplier on per-item burst height h. "
+                         "1.0 reproduces baseline.")
+    ap.add_argument("--base_lambda_lo",     type=float, default=80.0)
+    ap.add_argument("--base_lambda_hi",     type=float, default=250.0)
+    ap.add_argument("--scenario_name",      type=str,   default="baseline",
+                    help="Label written into <out_dir>/scenario.json")
+    args = ap.parse_args()
+
+    scenario = {
+        "name": args.scenario_name,
+        "phi_lo": args.phi_lo, "phi_hi": args.phi_hi,
+        "shock_count_scale": args.shock_count_scale,
+        "shock_height_scale": args.shock_height_scale,
+        "seasonal_scale": args.seasonal_scale,
+        "containers_scale": args.containers_scale,
+        "ss_scale": args.ss_scale,
+        "leadtime_scale": args.leadtime_scale,
+        "burst_rate_scale": args.burst_rate_scale,
+        "burst_height_scale": args.burst_height_scale,
+        "base_lambda_lo": args.base_lambda_lo,
+        "base_lambda_hi": args.base_lambda_hi,
+        "seed": args.seed, "days": args.days,
+    }
+
+    streaming = not args.no_streaming and args.days > 500
+
+    print("=== Supply Chain Simulation (Multi-Echelon) ===")
+    print(f"  Days: {args.days:,} ({args.days/365:.1f} years)  "
+          f"Seed: {args.seed}")
+    print(f"  1 step = 1 day | 365 = 1 year | 52560 = 144 years")
+    print(f"  Pipeline: {args.pipeline_mult}  Streaming: {streaming}")
+    print()
+
+    sim, net, items, dsig = build_example_simulation_from_adjacency(
+        seed=args.seed,
+        horizon_days=args.days,
+        pipeline_multiplier=args.pipeline_mult,
+        streaming_out_dir=args.out_dir if streaming else None,
+        packing="greedy",
+        scenario=scenario)
+
+    os.makedirs(args.out_dir, exist_ok=True)
+    import json as _json
+    with open(os.path.join(args.out_dir, "scenario.json"), "w") as _f:
+        _json.dump(scenario, _f, indent=2)
+
+    dd, ds, svc, di, db, dt = sim.run()
+
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    # Save demand signals
+    print("Saving demand signals...")
+    np.save(os.path.join(args.out_dir, "demand_signals.npy"),
+            dsig[:args.days])
+    with open(os.path.join(args.out_dir, "demand_signals_cols.txt"), "w") as f:
+        f.write(",".join(sorted(items.keys())) + "\n")
+    print(f"  Saved shape={dsig[:args.days].shape}")
+
+    if not streaming:
+        dd.to_csv(os.path.join(args.out_dir, "daily_records.csv"),
+                  index=False)
+        ds.to_csv(os.path.join(args.out_dir, "shipments.csv"), index=False)
+        svc.to_csv(os.path.join(args.out_dir, "service_summary.csv"),
+                   index=False)
+        if args.days <= 500:
+            di.to_csv(os.path.join(args.out_dir, "inventory_history.csv"),
+                      index=False)
+            db.to_csv(os.path.join(args.out_dir, "backlog_history.csv"),
+                      index=False)
+            dt.to_csv(os.path.join(args.out_dir, "intransit_history.csv"),
+                      index=False)
+
+    fr = svc['fill_rate_stock_only']
+    print(f"\n=== Service Summary ===")
+    print(f"  Fill rate: mean={fr.mean():.3f}  "
+          f"median={fr.median():.3f}  "
+          f"min={fr.min():.3f}  max={fr.max():.3f}")
+    print(f"  Total demand:  {svc['total_demand'].sum():,}")
+    print(f"  Total served:  {svc['served_from_stock'].sum():,}")
+    print(f"  Total backlog: {svc['new_backlog_added'].sum():,}")
+    print(f"\nOutputs → {args.out_dir}/")

simulator/demo_simulator.py

@@ -0,0 +1,1097 @@
+"""
+ISOMORPH Interactive Demo — Simulation Backend
+================================================
+Lightweight supply-chain simulation engine adapted from
+simulator/Supplychaingeo_item50.py for the interactive web demo.
+
+Differences from the original:
+  1. Returns a SimResult dataclass — no disk I/O.
+  2. Supports configurable T (1–1000) and C (1–5 items).
+  3. Adds a per-edge Markovian disruption mechanism (Bernoulli trigger,
+     fixed-duration capacity knockout).
+  4. Tracks per-node inflow / outflow arrays during simulation so the
+     bullwhip analysis and time-series panels can be computed without
+     post-processing the shipments log.
+  5. All core logic — AR(1) demand model, (s,S) inventory policy,
+     Dijkstra routing, greedy bin-packing — is kept identical to the
+     original simulator.
+
+Public entry point
+------------------
+    result = run_demo_simulation(config)
+
+config keys (all optional, defaults shown):
+    T                  int   365        simulation horizon in days
+    n_items            int   3          number of SKUs  (1–5)
+    seed               int   42
+    pipeline_mult      float 7.0        days of EMA demand to keep in pipeline
+    phi_lo             float 0.95       AR(1) coefficient lower bound
+    phi_hi             float 0.97       AR(1) coefficient upper bound
+    shock_count_scale  float 1.0
+    shock_height_scale float 1.0
+    burst_rate_scale   float 1.0
+    burst_height_scale float 1.0
+    seasonal_scale     float 1.0
+    base_lambda_lo     float 80.0
+    base_lambda_hi     float 250.0
+    containers_scale   float 1.0        edge capacity multiplier
+    ss_scale           float 1.0        (s, S) and initial inventory multiplier
+    leadtime_scale     float 1.0        lead-time multiplier at source nodes
+    disruption_edge    tuple|None None  (from_node, to_node) edge to disrupt
+    disruption_prob    float 0.0        per-day Bernoulli trigger probability
+    disruption_duration int  10         consecutive days edge is disabled
+    holding_cost       float 1.0        per-unit per-day cost (display only)
+    backlog_penalty    float 5.0        per-unit per-day penalty (display only)
+"""
+
+from __future__ import annotations
+
+import math
+import heapq
+import random
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, Callable
+
+import numpy as np
+
+
+# ============================================================================
+# Data Structures — verbatim from Supplychaingeo_item50.py
+# ============================================================================
+
+@dataclass
+class Item:
+    item_id: str
+    volume: float
+
+
+@dataclass
+class Edge:
+    u: str
+    v: str
+    travel_time_days: float
+    container_volume: float
+    num_containers_per_day: int
+    daily_containers: List[float] = field(default_factory=list)
+
+    def reset_daily(self, capacity_factor: float = 1.0) -> None:
+        effective_vol = self.container_volume * capacity_factor
+        self.daily_containers = [effective_vol] * self.num_containers_per_day
+
+    def find_container_slot(self, item_volume: float) -> Optional[int]:
+        for idx, rem in enumerate(self.daily_containers):
+            if rem >= item_volume:
+                return idx
+        return None
+
+    def allocate_in_container(self, idx: int, item_volume: float) -> bool:
+        if 0 <= idx < len(self.daily_containers) and \
+                self.daily_containers[idx] >= item_volume:
+            self.daily_containers[idx] -= item_volume
+            return True
+        return False
+
+    @property
+    def daily_total_capacity(self) -> float:
+        return self.container_volume * max(self.num_containers_per_day, 0)
+
+
+@dataclass
+class Node:
+    node_id: str
+    lat: float
+    lon: float
+    is_destination: bool = False
+    is_source: bool = False
+    inventory: Dict[str, int] = field(default_factory=dict)
+    s_levels: Dict[str, int] = field(default_factory=dict)
+    S_levels: Dict[str, int] = field(default_factory=dict)
+    lead_time_mean: Dict[str, float] = field(default_factory=dict)
+    lead_time_std_frac: float = 0.2
+    outstanding_orders: Dict[str, Optional[Tuple[int, int]]] = \
+        field(default_factory=dict)
+    backlog: Dict[str, int] = field(default_factory=dict)
+
+    def receive_orders_today(self, day: int) -> None:
+        to_clear = []
+        for item_id, order in self.outstanding_orders.items():
+            if order is None:
+                continue
+            arrival_day, qty = order
+            if day >= arrival_day:
+                self.inventory[item_id] = \
+                    self.inventory.get(item_id, 0) + qty
+                to_clear.append(item_id)
+        for iid in to_clear:
+            self.outstanding_orders[iid] = None
+
+    def maybe_place_orders(self, day: int, rng: random.Random) -> None:
+        if self.is_destination:
+            return
+        if not self.is_source:
+            return
+        for item_id, s in self.s_levels.items():
+            on_hand = self.inventory.get(item_id, 0)
+            if on_hand < s and \
+                    self.outstanding_orders.get(item_id) is None:
+                S = self.S_levels.get(item_id, on_hand)
+                qty = max(S - on_hand, 0)
+                if qty <= 0:
+                    continue
+                mean_lt = max(self.lead_time_mean.get(item_id, 1.0), 0.1)
+                std = self.lead_time_std_frac * mean_lt
+                sampled = rng.normalvariate(mean_lt, std)
+                lt_days = max(1, int(math.ceil(sampled)))
+                self.outstanding_orders[item_id] = (day + lt_days, qty)
+
+
+# ============================================================================
+# Network + Dijkstra — verbatim from Supplychaingeo_item50.py
+# ============================================================================
+
+class Network:
+    def __init__(self) -> None:
+        self.nodes: Dict[str, Node] = {}
+        self.edges: Dict[Tuple[str, str], Edge] = {}
+        self.adj: Dict[str, List[str]] = {}
+        self.weight_cache: Dict[Tuple[str, str], float] = {}
+        self.paths_to_dest: Dict[
+            str, Tuple[float, List[str], List[Tuple[str, str]]]] = {}
+
+    def add_node(self, node: Node) -> None:
+        self.nodes[node.node_id] = node
+        self.adj.setdefault(node.node_id, [])
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges[(edge.u, edge.v)] = edge
+        self.adj.setdefault(edge.u, []).append(edge.v)
+        cap = max(edge.daily_total_capacity, 1e-9)
+        self.weight_cache[(edge.u, edge.v)] = edge.travel_time_days / cap
+
+    def reset_daily_edges(self, capacity_factor: float = 1.0) -> None:
+        for e in self.edges.values():
+            e.reset_daily(capacity_factor)
+
+    def dijkstra(self, source: str, target: str) -> Tuple[float, List[str]]:
+        if source == target:
+            return 0.0, [source]
+        dist: Dict[str, float] = {source: 0.0}
+        prev: Dict[str, Optional[str]] = {source: None}
+        pq = [(0.0, source)]
+        visited: set = set()
+        while pq:
+            d, u = heapq.heappop(pq)
+            if u in visited:
+                continue
+            visited.add(u)
+            if u == target:
+                break
+            for v in self.adj.get(u, []):
+                w = self.weight_cache[(u, v)]
+                nd = d + w
+                if nd < dist.get(v, float('inf')):
+                    dist[v] = nd
+                    prev[v] = u
+                    heapq.heappush(pq, (nd, v))
+        if target not in dist:
+            return float('inf'), []
+        path: List[str] = []
+        cur: Optional[str] = target
+        while cur is not None:
+            path.append(cur)
+            cur = prev.get(cur)
+        path.reverse()
+        return dist[target], path
+
+    def compute_paths_to_destination(self, dest_id: str) -> None:
+        self.paths_to_dest.clear()
+        for nid in self.nodes:
+            if nid == dest_id:
+                self.paths_to_dest[nid] = (0.0, [nid], [])
+                continue
+            d, pn = self.dijkstra(nid, dest_id)
+            if not pn:
+                self.paths_to_dest[nid] = (float('inf'), [], [])
+            else:
+                pe = [(pn[i], pn[i + 1]) for i in range(len(pn) - 1)]
+                self.paths_to_dest[nid] = (d, pn, pe)
+
+
+# ============================================================================
+# Greedy First-Fit Bin Packing — verbatim from Supplychaingeo_item50.py
+# ============================================================================
+
+def allocate_units_along_path_greedy(
+    item: Item,
+    max_units: int,
+    path_edges: List[Tuple[str, str]],
+    network_edges: Dict[Tuple[str, str], Edge],
+) -> int:
+    if max_units <= 0 or not path_edges:
+        return 0
+    edges_objs = [network_edges[eid] for eid in path_edges]
+    placed = 0
+    ivol = item.volume
+    for _ in range(max_units):
+        slots: List[Tuple[Edge, int]] = []
+        ok = True
+        for e in edges_objs:
+            si = e.find_container_slot(ivol)
+            if si is None:
+                ok = False
+                break
+            slots.append((e, si))
+        if not ok:
+            break
+        good = True
+        for e, si in slots:
+            if not e.allocate_in_container(si, ivol):
+                good = False
+                break
+        if not good:
+            break
+        placed += 1
+    return placed
+
+
+# ============================================================================
+# SimResult — returned by run_demo_simulation
+# ============================================================================
+
+@dataclass
+class SimResult:
+    """All simulation outputs needed by the visualization layer."""
+
+    T: int
+    item_ids: List[str]
+    node_ids: List[str]
+    edge_ids: List[Tuple[str, str]]
+
+    # Per-node, per-item time series: dict[node_id][item_id] -> ndarray(T,)
+    inventory: Dict[str, Dict[str, np.ndarray]]
+    backlog:   Dict[str, Dict[str, np.ndarray]]
+    # inflow[n][i][t]  = units arriving AT node n for item i on day t
+    # outflow[n][i][t] = units dispatched FROM node n for item i on day t
+    inflow:    Dict[str, Dict[str, np.ndarray]]
+    outflow:   Dict[str, Dict[str, np.ndarray]]
+
+    # Realized customer demand at destination per item
+    demand: Dict[str, np.ndarray]   # item_id -> ndarray(T,)
+
+    # Demand intensity signal (before Poisson sampling)
+    demand_signals: np.ndarray      # shape (T, n_items)
+
+    # Shipment records for animation and bullwhip
+    # Each entry: {day, arrival_day, from, to, item, units,
+    #              path_nodes (list), edge_times (list)}
+    shipments: List[Dict]
+
+    # Edge utilization: fraction of daily capacity used, shape (T,)
+    edge_util: Dict[Tuple[str, str], np.ndarray]
+    edge_cap:  Dict[Tuple[str, str], float]      # cap_per_day
+
+    # Summary
+    fill_rate: Dict[str, float]    # item_id -> fill_rate_stock_only
+
+    # Tier assignment for bullwhip visualization
+    # tier 0 = destination (NewYork), higher = further upstream
+    tier: Dict[str, int]
+
+    # Coords for map visualization
+    node_coords: Dict[str, Tuple[float, float]]  # node_id -> (lat, lon)
+
+    # Log of disruption events
+    disruption_log: List[Dict]     # [{day, edge, duration}]
+
+    # Config echo
+    config: Dict
+
+
+# ============================================================================
+# Demo Simulation Engine
+# Adapted from SupplyChainSimulation in Supplychaingeo_item50.py.
+# Changes: no CSV streaming; per-edge disruption; direct inflow/outflow tracking.
+# ============================================================================
+
+class DemoSimulation:
+
+    def __init__(
+        self,
+        network: Network,
+        items: Dict[str, Item],
+        destination_id: str,
+        demand_fn: Callable[[int], Dict[str, int]],
+        T: int,
+        seed: int = 42,
+        pipeline_multiplier: float = 7.0,
+        disruption_edge: Optional[Tuple[str, str]] = None,
+        disruption_prob: float = 0.0,
+        disruption_duration: int = 10,
+    ) -> None:
+        assert destination_id in network.nodes and \
+            network.nodes[destination_id].is_destination
+
+        self.network = network
+        self.items = items
+        self.item_order: List[str] = sorted(self.items.keys())
+        self.destination_id = destination_id
+        self.demand_fn = demand_fn
+        self.T = T
+        self.rng = random.Random(seed)
+        self.pipeline_multiplier = pipeline_multiplier
+
+        # Disruption state
+        self.disruption_edge = disruption_edge
+        self.disruption_prob = disruption_prob
+        self.disruption_duration = disruption_duration
+        self._disruption_remaining: int = 0   # days remaining in current event
+        self.disruption_log: List[Dict] = []
+
+        # EMA warm-start (same default as original)
+        self.demand_ema: Dict[str, float] = {iid: 165.0 for iid in items}
+        self.ema_alpha = 0.05
+        self.item_intransit: Dict[str, int] = {iid: 0 for iid in items}
+
+        # In-transit to destination: arrival_day -> {item_id: qty}
+        self.dest_in_transit: Dict[int, Dict[str, int]] = {}
+
+        # ── Pre-allocate history arrays ───────────────────────────────────
+        node_ids = list(network.nodes.keys())
+        item_ids = self.item_order
+
+        def _zarr():
+            return np.zeros(T, dtype=np.int32)
+
+        self.inv_hist = {nid: {iid: _zarr() for iid in item_ids}
+                         for nid in node_ids}
+        self.bl_hist  = {nid: {iid: _zarr() for iid in item_ids}
+                         for nid in node_ids}
+        self.inflow   = {nid: {iid: _zarr() for iid in item_ids}
+                         for nid in node_ids}
+        self.outflow  = {nid: {iid: _zarr() for iid in item_ids}
+                         for nid in node_ids}
+        self.demand_hist = {iid: _zarr() for iid in item_ids}
+
+        # Shipments log — populated during run
+        self.shipments_log: List[Dict] = []
+
+        # Service counters
+        self.svc_demand: Dict[str, int] = {iid: 0 for iid in items}
+        self.svc_served: Dict[str, int] = {iid: 0 for iid in items}
+
+        # ── Precompute routing ────────────────────────────────────────────
+        network.compute_paths_to_destination(destination_id)
+        self.sorted_warehouses = sorted(
+            [(nid, d) for nid, (d, _, _) in network.paths_to_dest.items()
+             if nid != destination_id and math.isfinite(d)],
+            key=lambda x: x[1])
+
+        # Supplier relationships for inter-warehouse replenishment
+        self.node_suppliers: Dict[
+            str,
+            List[Tuple[str, float, List[str], List[Tuple[str, str]]]]
+        ] = {}
+        for nid, node in network.nodes.items():
+            if node.is_destination or node.is_source:
+                continue
+            suppliers = []
+            for (u, v) in network.edges:
+                if v == nid:
+                    d, path = network.dijkstra(u, nid)
+                    if path and math.isfinite(d):
+                        pe = [(path[i], path[i + 1])
+                              for i in range(len(path) - 1)]
+                        tt = sum(network.edges[e].travel_time_days for e in pe)
+                        suppliers.append((u, tt, path, pe))
+            suppliers.sort(key=lambda x: x[1])
+            self.node_suppliers[nid] = suppliers
+
+        # Intermediate nodes ordered upstream-first for replenishment
+        self.replenish_order: List[str] = [
+            nid for nid, _ in reversed(self.sorted_warehouses)
+            if nid in self.node_suppliers]
+
+    # ── helpers ──────────────────────────────────────────────────────────────
+
+    def _total_tt(self, pe: List[Tuple[str, str]]) -> float:
+        return sum(self.network.edges[e].travel_time_days for e in pe)
+
+    def _reset_edges_with_disruption(self, day: int) -> None:
+        """Reset edge containers, knocking out the disruption edge if active."""
+        ded = self.disruption_edge
+
+        if ded is not None and ded in self.network.edges:
+            # Advance disruption state machine
+            if self._disruption_remaining > 0:
+                self._disruption_remaining -= 1
+            elif self.rng.random() < self.disruption_prob:
+                self._disruption_remaining = self.disruption_duration
+                self.disruption_log.append(
+                    {"day": day, "edge": ded,
+                     "duration": self.disruption_duration})
+
+        for eid, e in self.network.edges.items():
+            if ded is not None and eid == ded and \
+                    self._disruption_remaining > 0:
+                e.reset_daily(0.0)   # capacity = 0: edge blocked
+            else:
+                e.reset_daily(1.0)
+
+    # ── replenishment ─────────────────────────────────────────────────────────
+
+    def _replenish_warehouses(self, day: int) -> None:
+        """Inter-warehouse replenishment: intermediate nodes pull
+        from upstream suppliers using (s,S) trigger + edge capacity.
+        Logic verbatim from Supplychaingeo_item50.py."""
+        net = self.network
+        k = day % len(self.item_order)
+        ids_today = self.item_order[k:] + self.item_order[:k]
+
+        for nid in self.replenish_order:
+            node = net.nodes[nid]
+            for iid in ids_today:
+                on_hand = node.inventory.get(iid, 0)
+                s = node.s_levels.get(iid, 0)
+                if on_hand >= s:
+                    continue
+                if node.outstanding_orders.get(iid) is not None:
+                    continue
+                S = node.S_levels.get(iid, on_hand)
+                qty_needed = max(S - on_hand, 0)
+                if qty_needed <= 0:
+                    continue
+
+                for sup_id, tt, path, pe in \
+                        self.node_suppliers.get(nid, []):
+                    sup_node = net.nodes[sup_id]
+                    avail = sup_node.inventory.get(iid, 0)
+                    if avail <= 0:
+                        continue
+                    attempt = min(avail, qty_needed)
+                    placed = allocate_units_along_path_greedy(
+                        self.items[iid], attempt, pe, net.edges)
+                    if placed <= 0:
+                        continue
+
+                    sup_node.inventory[iid] -= placed
+                    arr = day + max(1, int(math.ceil(tt)))
+                    node.outstanding_orders[iid] = (arr, placed)
+
+                    # Track outflow at supplier and inflow at receiver
+                    self.outflow[sup_id][iid][day] += placed
+                    if arr < self.T:
+                        self.inflow[nid][iid][arr] += placed
+
+                    self.shipments_log.append({
+                        "day": day, "arrival_day": arr,
+                        "from": sup_id, "to": nid,
+                        "item": iid, "units": placed,
+                        "path_nodes": path,
+                        "edge_times": [net.edges[e].travel_time_days
+                                       for e in pe]})
+                    break
+
+    # ── main step ─────────────────────────────────────────────────────────────
+
+    def step(self, day: int) -> None:
+        net = self.network
+        dest = net.nodes[self.destination_id]
+
+        # 1) (s,S) replenishment arrivals at warehouse nodes
+        for node in net.nodes.values():
+            node.receive_orders_today(day)
+
+        # 2) Arrivals at destination
+        arrivals = self.dest_in_transit.pop(day, {})
+        for iid, qty in arrivals.items():
+            self.item_intransit[iid] = max(
+                0, self.item_intransit.get(iid, 0) - qty)
+            # Backlog absorption
+            bl = dest.backlog.get(iid, 0)
+            if bl > 0:
+                use = min(qty, bl)
+                dest.backlog[iid] = bl - use
+                qty -= use
+            if qty > 0:
+                dest.inventory[iid] = dest.inventory.get(iid, 0) + qty
+            # Record inflow at destination
+            self.inflow[self.destination_id][iid][day] += arrivals.get(iid, 0)
+
+        # 3) Reset edge containers (with disruption)
+        self._reset_edges_with_disruption(day)
+
+        # 4) Demand at destination
+        td = self.demand_fn(day)
+        k = day % len(self.item_order)
+        ids_today = self.item_order[k:] + self.item_order[:k]
+
+        for iid in self.items:
+            dq = int(td.get(iid, 0))
+            self.demand_ema[iid] = (
+                self.ema_alpha * dq +
+                (1 - self.ema_alpha) * self.demand_ema[iid])
+            oh = dest.inventory.get(iid, 0)
+            if oh >= dq:
+                served, unfilled = dq, 0
+                dest.inventory[iid] = oh - dq
+            else:
+                served, unfilled = oh, dq - oh
+                dest.inventory[iid] = 0
+                dest.backlog[iid] = dest.backlog.get(iid, 0) + unfilled
+            self.svc_demand[iid] += dq
+            self.svc_served[iid] += served
+            self.demand_hist[iid][day] = dq
+
+        # 5) Ship from warehouses to destination
+        for iid in ids_today:
+            item = self.items[iid]
+            cb = dest.backlog.get(iid, 0)
+            it = self.item_intransit.get(iid, 0)
+            oh = dest.inventory.get(iid, 0)
+
+            if self.pipeline_multiplier > 0:
+                pt = self.demand_ema[iid] * self.pipeline_multiplier
+                ship_target = max(0, int(math.ceil(cb + pt - it - oh)))
+            else:
+                S_dest = max(1, int(self.demand_ema[iid] * 3))
+                ship_target = max(0, cb + S_dest - oh - it)
+
+            if ship_target <= 0:
+                continue
+
+            remaining = ship_target
+            for wid, _ in self.sorted_warehouses:
+                if remaining <= 0:
+                    break
+                wn = net.nodes[wid]
+                avail = wn.inventory.get(iid, 0)
+                if avail <= 0:
+                    continue
+                _, pn, pe = net.paths_to_dest[wid]
+                if not pe:
+                    continue
+                attempt = min(avail, remaining)
+                placed = allocate_units_along_path_greedy(
+                    item, attempt, pe, net.edges)
+                if placed <= 0:
+                    continue
+                wn.inventory[iid] -= placed
+                remaining -= placed
+                arr = day + max(1, int(math.ceil(self._total_tt(pe))))
+                self.dest_in_transit.setdefault(arr, {})
+                self.dest_in_transit[arr][iid] = \
+                    self.dest_in_transit[arr].get(iid, 0) + placed
+                self.item_intransit[iid] = \
+                    self.item_intransit.get(iid, 0) + placed
+
+                # Track outflow at warehouse; inflow at dest tracked in step 2
+                self.outflow[wid][iid][day] += placed
+
+                self.shipments_log.append({
+                    "day": day, "arrival_day": arr,
+                    "from": wid, "to": self.destination_id,
+                    "item": iid, "units": placed,
+                    "path_nodes": pn,
+                    "edge_times": [net.edges[e].travel_time_days for e in pe]})
+
+        # 5b) Inter-warehouse replenishment
+        self._replenish_warehouses(day)
+
+        # 6) (s,S) orders at source nodes
+        for node in net.nodes.values():
+            node.maybe_place_orders(day, self.rng)
+
+        # 7) Snapshot inventory and backlog
+        for node in net.nodes.values():
+            for iid in self.items:
+                self.inv_hist[node.node_id][iid][day] = \
+                    int(node.inventory.get(iid, 0))
+                self.bl_hist[node.node_id][iid][day] = \
+                    int(node.backlog.get(iid, 0))
+
+    # ── run ───────────────────────────────────────────────────────────────────
+
+    def run(self) -> None:
+        for day in range(self.T):
+            self.step(day)
+            # Clean up stale in-transit entries
+            if day % 200 == 0:
+                for k in [k for k in self.dest_in_transit if k < day]:
+                    del self.dest_in_transit[k]
+
+
+# ============================================================================
+# Demand Generator — same AR(1) + shocks + burst model as the original.
+# phi defaults lowered for shorter demo horizons (more visible dynamics).
+# ============================================================================
+
+def build_demand_fn(
+    item_ids: List[str],
+    n_steps: int,
+    seed: int = 42,
+    base_lambda_range: Tuple[float, float] = (80.0, 250.0),
+    scenario: Optional[Dict] = None,
+) -> Tuple[Callable[[int], Dict[str, int]], np.ndarray]:
+    """
+    Returns (demand_fn, lam) where lam has shape (n_steps, n_items).
+    demand_fn(day) -> {item_id: int} via Poisson sampling from lam[day].
+
+    AR(1) defaults are phi_lo=0.95, phi_hi=0.97 for demo horizons (300–1000
+    days); the original used 0.999 for 52560-step runs.
+    """
+    rng = np.random.default_rng(seed)
+    n_items = len(item_ids)
+
+    sc = scenario or {}
+    phi_lo             = float(sc.get("phi_lo",             0.95))
+    phi_hi             = float(sc.get("phi_hi",             0.97))
+    shock_count_scale  = float(sc.get("shock_count_scale",  1.0))
+    shock_height_scale = float(sc.get("shock_height_scale", 1.0))
+    seasonal_scale     = float(sc.get("seasonal_scale",     1.0))
+    burst_rate_scale   = float(sc.get("burst_rate_scale",   1.0))
+    burst_height_scale = float(sc.get("burst_height_scale", 1.0))
+
+    spy = 365   # yearly period in days
+    spw = 7     # weekly period in days
+
+    t = np.arange(n_steps, dtype=np.float64)
+    yearly_phase = 2 * np.pi * t / spy
+    weekly_phase = 2 * np.pi * (t % spw) / spw
+
+    lam = np.zeros((n_steps, n_items), dtype=np.float64)
+
+    # Global macro events: rare, long, correlated across items
+    gs = np.zeros(n_steps)
+    base_n_global = rng.integers(5, 12)
+    n_global = max(0, int(round(float(base_n_global) * shock_count_scale)))
+    for _ in range(n_global):
+        si  = int(rng.integers(0, n_steps))
+        dur = int(rng.integers(min(180, n_steps), max(min(1100, n_steps), min(180, n_steps) + 1)))
+        end = min(si + dur, n_steps)
+        h   = rng.uniform(0.20, 0.60) * shock_height_scale
+        for k in range(si, end):
+            p = (k - si) / max(dur, 1)
+            if p < 0.15:
+                gs[k] += h * (p / 0.15)
+            elif p < 0.75:
+                gs[k] += h
+            else:
+                gs[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+    for j, iid in enumerate(item_ids):
+        base = rng.uniform(*base_lambda_range)
+
+        # Yearly seasonality: two harmonics
+        ya1 = rng.uniform(0.12, 0.28) * seasonal_scale
+        ya2 = rng.uniform(0.04, 0.10) * seasonal_scale
+        yo  = rng.uniform(0, 2 * np.pi)
+        yr  = (ya1 * np.sin(yearly_phase + yo) +
+               ya2 * np.sin(2 * yearly_phase + yo * 0.7))
+
+        # Weekly texture
+        wa = rng.uniform(0.04, 0.10)
+        wo = rng.uniform(0, 2 * np.pi)
+        wy = wa * np.sin(weekly_phase + wo)
+
+        # AR(1) drift (dominant low-frequency component)
+        ac     = rng.uniform(phi_lo, phi_hi)
+        ar_std = rng.uniform(0.008, 0.018)
+        dr = np.zeros(n_steps)
+        dr[0] = rng.normal(0, 0.10)
+        for i in range(1, n_steps):
+            dr[i] = ac * dr[i - 1] + rng.normal(0, ar_std)
+        dr = np.clip(dr, -0.60, 0.60)
+
+        # Per-item idiosyncratic burst events
+        sr = rng.uniform(0.0002, 0.001) * burst_rate_scale
+        sm = rng.random(n_steps) < sr
+        sp = np.zeros(n_steps)
+        for si in np.where(sm)[0]:
+            dur = int(rng.integers(min(30, n_steps), max(min(180, n_steps), min(30, n_steps) + 1)))
+            end = min(si + dur, n_steps)
+            h   = rng.uniform(0.20, 0.70) * burst_height_scale
+            for k in range(si, end):
+                p = (k - si) / max(dur, 1)
+                if p < 0.15:
+                    sp[k] += h * (p / 0.15)
+                elif p < 0.75:
+                    sp[k] += h
+                else:
+                    sp[k] += h * (1.0 - (p - 0.75) / 0.25)
+
+        gsens = rng.uniform(0.4, 1.2)
+        fac = 1.0 + yr + wy + dr + sp + gsens * gs
+        fac = np.clip(fac, 0.08, None)
+        lam[:, j] = base * fac
+
+    def demand_fn(day: int) -> Dict[str, int]:
+        idx = day % n_steps
+        return {iid: int(rng.poisson(lam=max(0.01, lam[idx, j])))
+                for j, iid in enumerate(item_ids)}
+
+    return demand_fn, lam
+
+
+# ============================================================================
+# Network Builder — same fixed US topology as Supplychaingeo_item50.py,
+# scaled for n_items and demo parameters.
+# ============================================================================
+
+# Tier labeling matches Table C.4 / bullwhip_analysis.py in the paper.
+_TIER: Dict[str, int] = {
+    "NewYork":      0,   # destination
+    "Philadelphia": 1,   # last-mile
+    "Baltimore":    1,   # last-mile
+    "Columbus":     2,   # Tier-4
+    "Richmond":     2,   # Tier-4
+    "Charlotte":    3,   # Tier-3
+    "Chicago":      3,   # Tier-3
+    "Memphis":      3,   # Tier-3
+    "Atlanta":      4,   # Tier-2
+    "Nashville":    5,   # hub / Tier-1
+    "SanFrancisco": 6,   # source
+    "StLouis":      6,   # source
+    "Orlando":      6,   # source
+}
+
+# Coordinates (lat, lon)
+_COORDS: Dict[str, Tuple[float, float]] = {
+    "NewYork":      (40.7128, -74.0060),
+    "Philadelphia": (39.9526, -75.1652),
+    "Baltimore":    (39.2904, -76.6122),
+    "Columbus":     (39.9612, -82.9988),
+    "Richmond":     (37.5407, -77.4360),
+    "Charlotte":    (35.2271, -80.8431),
+    "Chicago":      (41.8781, -87.6298),
+    "Memphis":      (35.1495, -90.0490),
+    "Atlanta":      (33.7490, -84.3880),
+    "Nashville":    (36.1627, -86.7816),
+    "SanFrancisco": (37.7749, -122.4194),
+    "StLouis":      (38.6270, -90.1994),
+    "Orlando":      (28.5383, -81.3792),
+}
+
+
+def _build_demo_network(
+    n_items: int,
+    item_ids: List[str],
+    seed: int,
+    scenario: Dict,
+    demand_signals: np.ndarray,
+) -> Network:
+    """
+    Build the canonical ISOMORPH network with (s,S) parameters adapted
+    for the demo item count and scenario knobs.
+    """
+    random.seed(seed)
+
+    ss_scale       = float(scenario.get("ss_scale",       1.0))
+    leadtime_scale = float(scenario.get("leadtime_scale", 1.0))
+    containers_scale = float(scenario.get("containers_scale", 1.0))
+
+    def make_pol(inv_base=4000, inv_var=500,
+                 s_base=600,   s_var=100,
+                 S_base=6000,  S_var=500,
+                 lt_mean=5,    lt_var=1):
+        inv_base = inv_base * ss_scale
+        inv_var  = inv_var  * ss_scale
+        s_base   = s_base   * ss_scale
+        s_var    = s_var    * ss_scale
+        S_base   = S_base   * ss_scale
+        S_var    = S_var    * ss_scale
+        lt_mean  = lt_mean  * leadtime_scale
+        lt_var   = lt_var   * leadtime_scale
+        inv, s, S, lt = {}, {}, {}, {}
+        for iid in item_ids:
+            si = max(0, int(round(s_base + random.uniform(-s_var, s_var))))
+            Si = max(si + 1, int(round(
+                S_base + random.uniform(-S_var, S_var))))
+            ii = int(round(inv_base + random.uniform(-inv_var, inv_var)))
+            ii = max(si, min(Si, max(0, ii)))
+            li = max(1, int(round(lt_mean + random.uniform(-lt_var, lt_var))))
+            s[iid], S[iid], inv[iid], lt[iid] = si, Si, ii, li
+        return inv, s, S, lt
+
+    tier_params = {
+        "SanFrancisco": dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "StLouis":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "Orlando":      dict(inv_base=4000, inv_var=400,
+                             s_base=400,  s_var=60,
+                             S_base=4000, S_var=400,
+                             lt_mean=3,   lt_var=1),
+        "Nashville":    dict(inv_base=8000, inv_var=800,
+                             s_base=1000, s_var=150,
+                             S_base=8000, S_var=800,
+                             lt_mean=3,   lt_var=1),
+        "Atlanta":      dict(inv_base=6000, inv_var=600,
+                             s_base=500,  s_var=80,
+                             S_base=6000, S_var=600,
+                             lt_mean=1,   lt_var=0),
+        "Chicago":      dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=8,   lt_var=1),
+        "Charlotte":    dict(inv_base=5000, inv_var=500,
+                             s_base=1000, s_var=150,
+                             S_base=5000, S_var=500,
+                             lt_mean=7,   lt_var=1),
+        "Memphis":      dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=7,   lt_var=1),
+        "Columbus":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        "Richmond":     dict(inv_base=4000, inv_var=400,
+                             s_base=500,  s_var=80,
+                             S_base=4000, S_var=400,
+                             lt_mean=2,   lt_var=0),
+        "Philadelphia": dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=1,   lt_var=0),
+        "Baltimore":    dict(inv_base=3000, inv_var=300,
+                             s_base=500,  s_var=80,
+                             S_base=3000, S_var=300,
+                             lt_mean=2,   lt_var=0),
+    }
+
+    net = Network()
+
+    # Destination
+    net.add_node(Node(
+        node_id="NewYork",
+        lat=_COORDS["NewYork"][0], lon=_COORDS["NewYork"][1],
+        is_destination=True,
+        inventory={iid: 600 for iid in item_ids},
+        backlog={iid: 0 for iid in item_ids},
+    ))
+
+    # All other nodes
+    for nid, params in tier_params.items():
+        is_src = nid in ("SanFrancisco", "StLouis", "Orlando")
+        inv, s, S, lt = make_pol(**params)
+        lat, lon = _COORDS[nid]
+        net.add_node(Node(
+            node_id=nid,
+            lat=lat, lon=lon,
+            is_source=is_src,
+            inventory=inv, s_levels=s, S_levels=S, lead_time_mean=lt,
+            outstanding_orders={iid: None for iid in item_ids},
+            backlog={iid: 0 for iid in item_ids},
+        ))
+
+    # Edges — travel times and upstream capacities from original
+    edge_defs = [
+        ("SanFrancisco", "Nashville",     4,  5000.0, 3),
+        ("StLouis",      "Nashville",     2,  5000.0, 3),
+        ("Orlando",      "Nashville",     2,  5000.0, 3),
+        ("Nashville",    "Atlanta",       1, 15000.0, 3),
+        ("Atlanta",      "Chicago",       8,  4000.0, 3),
+        ("Atlanta",      "Charlotte",     7,  4000.0, 3),
+        ("Atlanta",      "Memphis",       7,  4000.0, 3),
+        ("Chicago",      "Columbus",      2,  4000.0, 3),
+        ("Charlotte",    "Richmond",      2,  4000.0, 3),
+        ("Columbus",     "Philadelphia",  2,  4000.0, 3),
+        ("Richmond",     "Philadelphia",  1,  4000.0, 3),
+        ("Richmond",     "Baltimore",     3,  3000.0, 3),
+        ("Columbus",     "Baltimore",     3,  3000.0, 3),
+        ("Memphis",      "Baltimore",     2,  3000.0, 3),
+        # Last-mile: placeholder container_volume, back-solved below
+        ("Philadelphia", "NewYork",       1,  1000.0, 3),
+        ("Baltimore",    "NewYork",       2,  1000.0, 3),
+    ]
+
+    for u, v, tt, cv, nc in edge_defs:
+        nc_scaled = max(1, int(round(nc * containers_scale)))
+        net.add_edge(Edge(u=u, v=v,
+                          travel_time_days=float(tt),
+                          container_volume=float(cv),
+                          num_containers_per_day=nc_scaled))
+
+    # Back-solve last-mile capacity from actual demand mean (same formula as original)
+    actual_mean_lam = float(demand_signals.mean())
+    avg_vol         = 2.5          # mean item volume
+    target_ratio    = 1.20
+    packing_eff     = 0.93
+    total_demand_vol = n_items * actual_mean_lam * avg_vol
+    raw_needed       = total_demand_vol * target_ratio / packing_eff
+    phil_cv = round(raw_needed * 0.55 / 3 / 100) * 100
+    balt_cv = round(raw_needed * 0.45 / 3 / 100) * 100
+    phil_cv = max(phil_cv, 100.0)
+    balt_cv = max(balt_cv, 100.0)
+
+    for eid, cv in [(("Philadelphia", "NewYork"), phil_cv),
+                    (("Baltimore",    "NewYork"), balt_cv)]:
+        e = net.edges[eid]
+        e.container_volume = float(cv)
+        net.weight_cache[eid] = e.travel_time_days / max(
+            e.daily_total_capacity, 1e-9)
+
+    return net
+
+
+# ============================================================================
+# Edge Utilisation — adapted from simulator/derive_edge_files.py
+# ============================================================================
+
+def _compute_edge_util(
+    shipments_log: List[Dict],
+    edge_ids: List[Tuple[str, str]],
+    edge_cap: Dict[Tuple[str, str], float],
+    T: int,
+) -> Dict[Tuple[str, str], np.ndarray]:
+    """
+    For each edge, compute fraction of daily capacity used (0=empty, 1=full).
+    Attributes each shipment's volume to every edge leg on the day that leg
+    starts — matching the convention in derive_edge_files.py.
+    """
+    edge_to_idx = {eid: i for i, eid in enumerate(edge_ids)}
+    n_edges = len(edge_ids)
+    vol = np.zeros((T, n_edges), dtype=np.float64)
+
+    for rec in shipments_log:
+        path  = rec["path_nodes"]
+        ets   = rec["edge_times"]
+        d0    = int(rec["day"])
+        units = float(rec["units"])
+        cum   = 0.0
+        for h in range(len(ets)):
+            hop       = (path[h], path[h + 1])
+            eid_idx   = edge_to_idx.get(hop)
+            start_day = d0 + int(round(cum))
+            if eid_idx is not None and 0 <= start_day < T:
+                vol[start_day, eid_idx] += units
+            cum += float(ets[h])
+
+    cap_arr = np.array([max(edge_cap.get(eid, 1.0), 1e-9)
+                        for eid in edge_ids], dtype=np.float64)
+    util_mat = vol / cap_arr[np.newaxis, :]
+
+    return {eid: util_mat[:, i] for i, eid in enumerate(edge_ids)}
+
+
+# ============================================================================
+# Public entry point
+# ============================================================================
+
+def run_demo_simulation(config: Optional[Dict] = None) -> SimResult:
+    """
+    Run one simulation and return a SimResult.
+
+    Parameters
+    ----------
+    config : dict, optional
+        See module docstring for all supported keys. Missing keys use defaults.
+    """
+    cfg = config or {}
+
+    T          = max(1, min(int(cfg.get("T",          365)),  1000))
+    n_items    = max(1, min(int(cfg.get("n_items",       3)),     5))
+    seed       = int(cfg.get("seed",      42))
+    pipe_mult  = float(cfg.get("pipeline_mult", 7.0))
+
+    scenario = {
+        "phi_lo":             float(cfg.get("phi_lo",             0.95)),
+        "phi_hi":             float(cfg.get("phi_hi",             0.97)),
+        "shock_count_scale":  float(cfg.get("shock_count_scale",  1.0)),
+        "shock_height_scale": float(cfg.get("shock_height_scale", 1.0)),
+        "burst_rate_scale":   float(cfg.get("burst_rate_scale",   1.0)),
+        "burst_height_scale": float(cfg.get("burst_height_scale", 1.0)),
+        "seasonal_scale":     float(cfg.get("seasonal_scale",     1.0)),
+        "base_lambda_lo":     float(cfg.get("base_lambda_lo",    80.0)),
+        "base_lambda_hi":     float(cfg.get("base_lambda_hi",   250.0)),
+        "containers_scale":   float(cfg.get("containers_scale",   1.0)),
+        "ss_scale":           float(cfg.get("ss_scale",           1.0)),
+        "leadtime_scale":     float(cfg.get("leadtime_scale",     1.0)),
+    }
+
+    disruption_edge     = cfg.get("disruption_edge",     None)
+    disruption_prob     = float(cfg.get("disruption_prob",    0.0))
+    disruption_duration = int(cfg.get("disruption_duration", 10))
+
+    # Normalize disruption_edge: accept "NodeA,NodeB" string or (A,B) tuple
+    if isinstance(disruption_edge, str) and "," in disruption_edge:
+        parts = disruption_edge.split(",")
+        disruption_edge = (parts[0].strip(), parts[1].strip())
+
+    item_ids = [f"I{i:02d}" for i in range(1, n_items + 1)]
+
+    # Build demand signals
+    demand_fn, demand_signals = build_demand_fn(
+        item_ids, T, seed=seed,
+        base_lambda_range=(scenario["base_lambda_lo"],
+                           scenario["base_lambda_hi"]),
+        scenario=scenario,
+    )
+
+    # Build network
+    net = _build_demo_network(n_items, item_ids, seed, scenario,
+                               demand_signals)
+
+    items = {iid: Item(iid, round(random.uniform(1.0, 4.0), 2))
+             for iid in item_ids}
+    # Use deterministic volumes (same as original: seeded separately)
+    random.seed(seed)
+    for iid in item_ids:
+        items[iid] = Item(iid, round(random.uniform(1.0, 4.0), 2))
+
+    # Run simulation
+    sim = DemoSimulation(
+        network=net,
+        items=items,
+        destination_id="NewYork",
+        demand_fn=demand_fn,
+        T=T,
+        seed=seed,
+        pipeline_multiplier=pipe_mult,
+        disruption_edge=disruption_edge,
+        disruption_prob=disruption_prob,
+        disruption_duration=disruption_duration,
+    )
+    sim.run()
+
+    # Edge identifiers and capacities
+    edge_ids = list(net.edges.keys())
+    edge_cap = {eid: net.edges[eid].daily_total_capacity for eid in edge_ids}
+
+    # Edge utilization
+    edge_util = _compute_edge_util(
+        sim.shipments_log, edge_ids, edge_cap, T)
+
+    # Fill rates
+    fill_rate = {}
+    for iid in item_ids:
+        td = sim.svc_demand[iid]
+        sv = sim.svc_served[iid]
+        fill_rate[iid] = round(sv / td, 6) if td > 0 else 0.0
+
+    node_ids = list(net.nodes.keys())
+
+    return SimResult(
+        T=T,
+        item_ids=item_ids,
+        node_ids=node_ids,
+        edge_ids=edge_ids,
+        inventory=sim.inv_hist,
+        backlog=sim.bl_hist,
+        inflow=sim.inflow,
+        outflow=sim.outflow,
+        demand=sim.demand_hist,
+        demand_signals=demand_signals,
+        shipments=sim.shipments_log,
+        edge_util=edge_util,
+        edge_cap=edge_cap,
+        fill_rate=fill_rate,
+        tier=_TIER,
+        node_coords=_COORDS,
+        disruption_log=sim.disruption_log,
+        config=cfg,
+    )

simulator/derive_edge_files.py

@@ -0,0 +1,210 @@
+"""Derive edge_list.csv, edge_utilisation.npy, edge_saturation.npy from
+a finished scenario directory's shipments.csv + demand_signals.npy +
+scenario.json.
+
+The original exp_d_edge_utilisation.py source is lost (only a stale
+.pyc survives); this is a clean re-implementation matching the cap
+convention used by the existing 13 scenarios (verified by spot-checking
+baseline / cap_0.3 / cap_2.5 edge_list.csv values).
+
+Edge capacities follow the simulator's two-tier convention:
+  - Upstream edges (15 entries): STATIC_EDGES with num_containers
+    multiplied by scenario['containers_scale'] (rounded, min 1), and
+    container_volume held fixed.
+  - Last-mile edges (PHL->NYC, BAL->NYC): back-solved from the
+    realized demand mean using the same formula as the simulator
+    (simulate_item50.py).
+
+Daily edge utilisation is computed by streaming shipments.csv and, for
+each shipment record, walking its path_nodes/edge_times to attribute
+the shipment volume to each (from, to) hop on the day that hop
+starts.
+
+Outputs:
+  <scenario_dir>/edge_list.csv         per-edge cap_per_day table
+  <scenario_dir>/edge_utilisation.npy  shape (T, |E|) float32 in [0, *)
+  <scenario_dir>/edge_saturation.npy   shape (T, |E|) uint8 = (util >= tau)
+
+Usage:
+    python derive_edge_files.py --scenario_dir <path> [--tau 0.9]
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+# Static upstream graph (matches simulate_item50.py).
+# Each entry: (from, to, travel_time_days, container_volume, num_containers).
+STATIC_UPSTREAM_EDGES: list[tuple[str, str, int, float, int]] = [
+    ("SanFrancisco", "Nashville",     4,  5000.0, 3),
+    ("StLouis",      "Nashville",     2,  5000.0, 3),
+    ("Orlando",      "Nashville",     2,  5000.0, 3),
+    ("Nashville",    "Atlanta",       1, 15000.0, 3),
+    ("Atlanta",      "Chicago",       8,  4000.0, 3),
+    ("Atlanta",      "Charlotte",     7,  4000.0, 3),
+    ("Atlanta",      "Memphis",       7,  4000.0, 3),
+    ("Chicago",      "Columbus",      2,  4000.0, 3),
+    ("Charlotte",    "Richmond",      2,  4000.0, 3),
+    ("Columbus",     "Philadelphia",  2,  4000.0, 3),
+    ("Richmond",     "Philadelphia",  1,  4000.0, 3),
+    ("Richmond",     "Baltimore",     3,  3000.0, 3),
+    ("Columbus",     "Baltimore",     3,  3000.0, 3),
+    ("Memphis",      "Baltimore",     2,  3000.0, 3),
+]
+
+LAST_MILE_EDGES: list[tuple[str, str, int]] = [
+    ("Philadelphia", "NewYork", 1),
+    ("Baltimore",    "NewYork", 2),
+]
+
+ITEM_AVG_VOL = 2.5
+TARGET_RATIO = 1.20
+PACKING_EFF = 0.93
+PHIL_SHARE = 0.55
+BALT_SHARE = 0.45
+
+
+def back_solve_last_mile_cv(
+    n_items: int, demand_signals_path: Path,
+) -> tuple[float, float]:
+    """Reproduce the simulator's last-mile container_volume back-solve.
+
+    See simulate_item50.py.
+    """
+    lam = np.load(demand_signals_path)
+    actual_mean_lam = float(lam.mean())
+    total_demand_vol = n_items * actual_mean_lam * ITEM_AVG_VOL
+    raw_needed = total_demand_vol * TARGET_RATIO / PACKING_EFF
+    phil_cv = round(raw_needed * PHIL_SHARE / 3 / 100) * 100
+    balt_cv = round(raw_needed * BALT_SHARE / 3 / 100) * 100
+    return float(phil_cv), float(balt_cv)
+
+
+def build_edge_df(scenario_dir: Path,
+                  scenario: dict,
+                  n_items: int = 50) -> pd.DataFrame:
+    containers_scale = float(scenario.get("containers_scale", 1.0))
+    phil_cv, balt_cv = back_solve_last_mile_cv(
+        n_items, scenario_dir / "demand_signals.npy")
+
+    rows = []
+    edge_id = 0
+    for frm, to, tt, cv, nc in STATIC_UPSTREAM_EDGES:
+        nc_scaled = max(1, int(round(nc * containers_scale)))
+        rows.append({
+            "edge_id": edge_id, "from": frm, "to": to,
+            "travel_time_days": tt,
+            "container_volume": cv,
+            "num_containers": nc_scaled,
+            "cap_per_day": cv * nc_scaled,
+        })
+        edge_id += 1
+    for (frm, to, tt), cv in zip(LAST_MILE_EDGES, [phil_cv, balt_cv]):
+        nc_scaled = max(1, int(round(3 * containers_scale)))
+        rows.append({
+            "edge_id": edge_id, "from": frm, "to": to,
+            "travel_time_days": tt,
+            "container_volume": cv,
+            "num_containers": nc_scaled,
+            "cap_per_day": cv * nc_scaled,
+        })
+        edge_id += 1
+    return pd.DataFrame(rows)
+
+
+def compute_utilisation(shipments_path: Path,
+                        edge_df: pd.DataFrame,
+                        n_days: int,
+                        chunksize: int = 500000) -> np.ndarray:
+    """Stream shipments.csv and accumulate per-edge daily volume.
+
+    For each shipment row, walks (path_nodes[h], path_nodes[h+1]) and
+    attributes its `units` to that edge on the day the hop starts.
+    Hop start day = dispatch day + cumulative edge_times of prior hops.
+    """
+    edge_to_id = {(r["from"], r["to"]): int(r["edge_id"])
+                  for _, r in edge_df.iterrows()}
+    n_edges = len(edge_df)
+    vol = np.zeros((n_days, n_edges), dtype=np.float32)
+
+    rows_seen = 0
+    hops_seen = 0
+    hops_dropped = 0
+
+    for chunk in pd.read_csv(
+        shipments_path,
+        usecols=["day", "units", "path_nodes", "edge_times"],
+        dtype={"day": np.int32, "units": np.float32},
+        chunksize=chunksize,
+    ):
+        days = chunk["day"].to_numpy()
+        units = chunk["units"].to_numpy()
+        path_strs = chunk["path_nodes"].to_numpy()
+        et_strs = chunk["edge_times"].to_numpy()
+        for i in range(len(chunk)):
+            path = ast.literal_eval(path_strs[i])
+            ets = ast.literal_eval(et_strs[i])
+            d0 = int(days[i])
+            u = float(units[i])
+            cum = 0.0
+            for h in range(len(ets)):
+                hop = (path[h], path[h + 1])
+                eid = edge_to_id.get(hop)
+                start_day = d0 + int(round(cum))
+                if eid is not None and 0 <= start_day < n_days:
+                    vol[start_day, eid] += u
+                    hops_seen += 1
+                else:
+                    hops_dropped += 1
+                cum += float(ets[h])
+        rows_seen += len(chunk)
+        print(f"  processed {rows_seen} rows ({hops_seen} hops, "
+              f"{hops_dropped} dropped)", flush=True)
+
+    return vol
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scenario_dir", required=True,
+                    help="Path to <output_mixture>/<name>/seed<seed>/")
+    ap.add_argument("--n_days", type=int, default=52560)
+    ap.add_argument("--n_items", type=int, default=50)
+    ap.add_argument("--tau", type=float, default=0.9,
+                    help="Saturation threshold; matches the convention "
+                         "used by the existing 13 scenarios.")
+    args = ap.parse_args()
+
+    sdir = Path(args.scenario_dir)
+    if not sdir.is_dir():
+        sys.exit(f"scenario_dir not found: {sdir}")
+    sc = json.loads((sdir / "scenario.json").read_text())
+
+    print(f"=== {sdir.name} (containers_scale="
+          f"{sc.get('containers_scale', 1.0)}) ===")
+
+    edge_df = build_edge_df(sdir, sc, n_items=args.n_items)
+    edge_df.to_csv(sdir / "edge_list.csv", index=False)
+    print(f"  wrote edge_list.csv  (|E|={len(edge_df)})")
+
+    vol = compute_utilisation(
+        sdir / "shipments.csv", edge_df, args.n_days)
+    cap = edge_df["cap_per_day"].to_numpy(dtype=np.float32)
+    util = vol / np.maximum(cap, 1e-9)
+    sat = (util >= args.tau).astype(np.uint8)
+
+    np.save(sdir / "edge_utilisation.npy", util.astype(np.float32))
+    np.save(sdir / "edge_saturation.npy", sat)
+    print(f"  saved edge_utilisation.npy  shape={util.shape}")
+    print(f"  saved edge_saturation.npy  shape={sat.shape}  "
+          f"saturated_frac={sat.mean():.4f}")
+
+
+if __name__ == "__main__":
+    main()

uq/plot_uq_envelope.py

@@ -0,0 +1,327 @@
+"""§4 UQ forecast-envelope figure: parameter UQ propagated to forecaster output.
+
+For each model with K=20 LHS perturbation tensors, plots median + 10/90
+band of y_true (input) and y_pred (output) across K, at one or three
+forecast windows for one item. The grey band is the band of physical
+realisations the network produces under demand-side parameter perturbation;
+the coloured band is the band of zero-shot forecasts of those realisations.
+
+  python plot_uq_envelope.py                          # 2x2, deterministic mid window
+  python plot_uq_envelope.py --multi                  # 3x4 multi-window grid
+  python plot_uq_envelope.py --window 25              # explicit single window
+  python plot_uq_envelope.py --item I05 chronos       # subset of models
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+REPO = Path(__file__).resolve().parents[1]
+RESULT_DIR = REPO / "results" / "eval" / "uq"
+FIG_DIR = REPO / "results" / "uq" / "figures"
+
+MODELS = {
+    "chronos":  {"prefix": "chronos_t5_base",
+                 "fill": "#9BB0CC", "line": "#2F4A75",
+                 "display": "Chronos"},
+    "moirai":   {"prefix": "moirai_1_1_R_base",
+                 "fill": "#A8BFA0", "line": "#345531",
+                 "display": "Moirai"},
+    "timesfm":  {"prefix": "timesfm_2_0_500m_pytorch",
+                 "fill": "#D7A992", "line": "#693220",
+                 "display": "TimesFM"},
+    "lagllama": {"prefix": "lag_llama",
+                 "fill": "#C2A8CC", "line": "#4D2752",
+                 "display": "Lag-Llama"},
+}
+TRUTH_BAND_COLOR = "#9CA3AF"
+TRUTH_LINE_COLOR = "#374151"
+AXES_FACE = "#FFFFFF"
+SPINE_COLOR = "#374151"
+
+
+def load_K_tensors(prefix: str, K: int = 20):
+    yp_list, yt_list = [], []
+    item_ids = window_starts = None
+    for k in range(1, K + 1):
+        p = RESULT_DIR / f"{prefix}_perturb_k{k:02d}_tensors.npz"
+        if not p.exists():
+            return None
+        d = np.load(p)
+        yp_list.append(d["y_pred"])
+        yt_list.append(d["y_true"])
+        if item_ids is None:
+            item_ids, window_starts = d["item_ids"], d["window_starts"]
+    y_pred = np.stack(yp_list, axis=0)   # (K, W, H, C)
+    y_true = np.stack(yt_list, axis=0)
+    return y_pred, y_true, item_ids, window_starts
+
+
+def deterministic_windows(W: int, n: int) -> list[int]:
+    """Evenly-spaced windows inside the test split, avoiding the edges."""
+    if n == 1:
+        return [W // 2]
+    return [int(round(W * (i + 1) / (n + 1))) for i in range(n)]
+
+
+def draw_band(ax, arr_kh: np.ndarray, fill_color: str, line_color: str,
+              label: str, fill_alpha: float, lw: float, z_base: int):
+    h = np.arange(1, arr_kh.shape[1] + 1)
+    med = np.median(arr_kh, axis=0)
+    q10 = np.percentile(arr_kh, 10, axis=0)
+    q90 = np.percentile(arr_kh, 90, axis=0)
+    ax.fill_between(h, q10, q90, color=fill_color, alpha=fill_alpha,
+                    linewidth=0, zorder=z_base)
+    ax.plot(h, med, color=line_color, lw=lw, label=label, zorder=z_base + 2)
+
+
+def style_axes(ax):
+    ax.set_facecolor(AXES_FACE)
+    for side in ("top", "right", "left", "bottom"):
+        ax.spines[side].set_color(SPINE_COLOR)
+        ax.spines[side].set_linewidth(0.7)
+    ax.tick_params(colors=SPINE_COLOR, length=3, width=0.7)
+    for label in ax.get_xticklabels() + ax.get_yticklabels():
+        label.set_color(SPINE_COLOR)
+    ax.grid(True, linestyle=':', alpha=0.35, linewidth=0.5,
+            color=SPINE_COLOR)
+
+
+def _draw_main(ax, yp_kh, yt_kh, model_key, draw_legend):
+    draw_band(ax, yt_kh,
+              fill_color=TRUTH_BAND_COLOR, line_color=TRUTH_LINE_COLOR,
+              label=r"truth $y_{i,t}$",
+              fill_alpha=0.30, lw=1.0, z_base=1)
+    draw_band(ax, yp_kh,
+              fill_color=MODELS[model_key]["fill"],
+              line_color=MODELS[model_key]["line"],
+              label=r"forecast $\hat y_{i,t}$",
+              fill_alpha=0.30, lw=1.8, z_base=3)
+    style_axes(ax)
+    if draw_legend:
+        leg = ax.legend(loc="upper left", fontsize=8.5, frameon=True,
+                        facecolor=AXES_FACE, edgecolor=SPINE_COLOR)
+        leg.get_frame().set_linewidth(0.6)
+        for txt in leg.get_texts():
+            txt.set_color(SPINE_COLOR)
+
+
+def _zoom_ylim(yp_kh, yt_kh, pad_frac: float = 0.08):
+    yt_med = np.median(yt_kh, axis=0)
+    yp_med = np.median(yp_kh, axis=0)
+    y_lo = float(min(yt_med.min(), yp_med.min()))
+    y_hi = float(max(yt_med.max(), yp_med.max()))
+    span = max(y_hi - y_lo, 1e-6)
+    pad = pad_frac * span
+    return y_lo - pad, y_hi + pad
+
+
+def _draw_zoom(zoom_ax, main_ax, yp_kh, yt_kh, model_key):
+    """Sibling axes below `main_ax` with the same bands and medians, but
+    y-axis tightened to the median range. Also shades the corresponding
+    horizontal slice on `main_ax` so the link is explicit.
+    """
+    h = np.arange(1, yp_kh.shape[1] + 1)
+    yt_med = np.median(yt_kh, axis=0)
+    yp_med = np.median(yp_kh, axis=0)
+    yt_q10 = np.percentile(yt_kh, 10, axis=0)
+    yt_q90 = np.percentile(yt_kh, 90, axis=0)
+    yp_q10 = np.percentile(yp_kh, 10, axis=0)
+    yp_q90 = np.percentile(yp_kh, 90, axis=0)
+    y_lo, y_hi = _zoom_ylim(yp_kh, yt_kh)
+
+    zoom_ax.fill_between(h, yt_q10, yt_q90, color=TRUTH_BAND_COLOR,
+                         alpha=0.30, linewidth=0, zorder=1)
+    zoom_ax.plot(h, yt_med, color=TRUTH_LINE_COLOR, lw=1.0, zorder=3)
+    zoom_ax.fill_between(h, yp_q10, yp_q90,
+                         color=MODELS[model_key]["fill"],
+                         alpha=0.30, linewidth=0, zorder=2)
+    zoom_ax.plot(h, yp_med, color=MODELS[model_key]["line"], lw=1.6, zorder=4)
+    zoom_ax.set_xlim(int(h[0]), int(h[-1]))
+    zoom_ax.set_ylim(y_lo, y_hi)
+    style_axes(zoom_ax)
+    zoom_ax.tick_params(axis="y", labelsize=8)
+
+    # Mark the zoom y-slice on the parent so the reader sees exactly which
+    # part of the main panel is being zoomed.
+    main_ax.axhspan(y_lo, y_hi, color=SPINE_COLOR, alpha=0.10,
+                    linewidth=0, zorder=0.5)
+    main_ax.axhline(y_lo, color=SPINE_COLOR, lw=0.5, ls=":",
+                    alpha=0.7, zorder=0.6)
+    main_ax.axhline(y_hi, color=SPINE_COLOR, lw=0.5, ls=":",
+                    alpha=0.7, zorder=0.6)
+
+
+def plot_2x2(data: dict, item_id: str, item_idx: int, w: int,
+             window_start: int, fig_path: Path, with_zoom: bool = True):
+    fig_h = 8.4 if with_zoom else 5.6
+    fig = plt.figure(figsize=(9.6, fig_h))
+    fig.patch.set_facecolor("white")
+    outer = fig.add_gridspec(2, 2, hspace=0.30, wspace=0.18,
+                             left=0.07, right=0.99, top=0.94, bottom=0.07)
+    items = list(data.items())
+    placements = [(0, 0), (0, 1), (1, 0), (1, 1)]
+    for (ri, ci), (model_key, (yp, yt)) in zip(placements, items):
+        yp_kh = yp[:, w, :, item_idx]
+        yt_kh = yt[:, w, :, item_idx]
+        if with_zoom:
+            inner = outer[ri, ci].subgridspec(
+                2, 1, height_ratios=[2.6, 1.9], hspace=0.06)
+            main_ax = fig.add_subplot(inner[0])
+            zoom_ax = fig.add_subplot(inner[1], sharex=main_ax)
+        else:
+            main_ax = fig.add_subplot(outer[ri, ci])
+            zoom_ax = None
+        _draw_main(main_ax, yp_kh, yt_kh, model_key,
+                   draw_legend=(ri == 0 and ci == 0))
+        main_ax.set_title(MODELS[model_key]["display"], fontsize=11,
+                          color=SPINE_COLOR)
+        if zoom_ax is not None:
+            _draw_zoom(zoom_ax, main_ax, yp_kh, yt_kh, model_key)
+            plt.setp(main_ax.get_xticklabels(), visible=False)
+        if ri == 1:
+            (zoom_ax if zoom_ax is not None else main_ax).set_xlabel(
+                r"forecast horizon $h$ (time units)", color=SPINE_COLOR)
+        if ci == 0:
+            main_ax.set_ylabel(f"item {item_id} demand",
+                               color=SPINE_COLOR)
+            if zoom_ax is not None:
+                zoom_ax.set_ylabel("zoom (medians)", fontsize=8.5,
+                                   color=SPINE_COLOR)
+    fig.savefig(fig_path, bbox_inches="tight", facecolor="white")
+    fig.savefig(fig_path.with_suffix(".png"), bbox_inches="tight",
+                dpi=160, facecolor="white")
+    plt.close(fig)
+
+
+def plot_multi(data: dict, item_id: str, item_idx: int,
+               windows: list[int], window_starts_arr: np.ndarray,
+               fig_path: Path):
+    """Grid: rows = windows, cols = models. Each cell is a (main, zoom)
+    vertical pair sharing x; the zoom row uses tightened y-limits."""
+    n_rows = len(windows)
+    n_cols = len(data)
+    fig = plt.figure(figsize=(3.2 * n_cols, 4.0 * n_rows))
+    fig.patch.set_facecolor("white")
+    outer = fig.add_gridspec(n_rows, n_cols, hspace=0.32, wspace=0.20,
+                             left=0.06, right=0.99, top=0.95, bottom=0.06)
+    model_items = list(data.items())
+    for r, w in enumerate(windows):
+        t0 = int(window_starts_arr[w])
+        for c, (model_key, (yp, yt)) in enumerate(model_items):
+            inner = outer[r, c].subgridspec(
+                2, 1, height_ratios=[2.6, 1.9], hspace=0.06)
+            main_ax = fig.add_subplot(inner[0])
+            zoom_ax = fig.add_subplot(inner[1], sharex=main_ax)
+            yp_kh = yp[:, w, :, item_idx]
+            yt_kh = yt[:, w, :, item_idx]
+            _draw_main(main_ax, yp_kh, yt_kh, model_key,
+                       draw_legend=(r == 0 and c == 0))
+            if r == 0:
+                main_ax.set_title(MODELS[model_key]["display"], fontsize=11,
+                                  color=SPINE_COLOR)
+            _draw_zoom(zoom_ax, main_ax, yp_kh, yt_kh, model_key)
+            plt.setp(main_ax.get_xticklabels(), visible=False)
+            if c == 0:
+                main_ax.set_ylabel(f"$t_0{{=}}{t0}$", fontsize=10,
+                                   color=SPINE_COLOR)
+                zoom_ax.set_ylabel("zoom", fontsize=8.5, color=SPINE_COLOR)
+            if r == n_rows - 1:
+                zoom_ax.set_xlabel(r"forecast horizon $h$ (time units)",
+                                   color=SPINE_COLOR)
+    fig.text(0.005, 0.5, f"item {item_id} demand",
+             rotation="vertical", va="center", ha="left",
+             fontsize=10.5, color=SPINE_COLOR)
+    fig.savefig(fig_path, bbox_inches="tight", facecolor="white")
+    fig.savefig(fig_path.with_suffix(".png"), bbox_inches="tight",
+                dpi=160, facecolor="white")
+    plt.close(fig)
+
+
+def main():
+    args = sys.argv[1:]
+    item = "I01"
+    window_arg: int | None = None
+    multi = False
+    narrowest = False
+    if "--item" in args:
+        i = args.index("--item"); item = args[i + 1]; args = args[:i] + args[i + 2:]
+    if "--window" in args:
+        i = args.index("--window"); window_arg = int(args[i + 1])
+        args = args[:i] + args[i + 2:]
+    if "--multi" in args:
+        multi = True; args.remove("--multi")
+    if "--narrowest" in args:
+        narrowest = True; args.remove("--narrowest")
+    no_zoom = False
+    if "--no-zoom" in args:
+        no_zoom = True; args.remove("--no-zoom")
+    requested = args if args else list(MODELS.keys())
+    bad = [m for m in requested if m not in MODELS]
+    if bad:
+        sys.exit(f"unknown model(s): {bad}; choose from {list(MODELS.keys())}")
+
+    FIG_DIR.mkdir(parents=True, exist_ok=True)
+    data: dict = {}
+    item_ids = window_starts = None
+    for m in requested:
+        out = load_K_tensors(MODELS[m]["prefix"])
+        if out is None:
+            print(f"[{m}] missing tensors, skipping")
+            continue
+        yp, yt, ids, ws = out
+        if item_ids is None:
+            item_ids, window_starts = ids, ws
+        data[m] = (yp, yt)
+        print(f"[{m}] y_pred={yp.shape}, y_true={yt.shape}")
+    if not data:
+        sys.exit("no models loaded")
+
+    item_idx = list(item_ids).index(item)
+    W_total = next(iter(data.values()))[0].shape[1]
+
+    if multi:
+        windows = deterministic_windows(W_total, 3)
+        print(f"item {item} (idx={item_idx}); multi-window grid w={windows} "
+              f"(t0={[int(window_starts[w]) for w in windows]})")
+        out = FIG_DIR / f"uq_envelope_{item}_multi.pdf"
+        plot_multi(data, item, item_idx, windows,
+                   np.asarray(window_starts), out)
+        print(f"wrote {out}")
+        return
+
+    if window_arg is None:
+        if narrowest:
+            yt_any = next(iter(data.values()))[1]
+            win_mean = yt_any[:, :, :, item_idx].mean(axis=-1)  # (K, W)
+            spread = win_mean.std(axis=0)                       # (W,)
+            w = int(spread.argmin())
+            print(f"min cross-K spread window: w={w}, "
+                  f"spread={spread[w]:.2f} "
+                  f"(min={spread.min():.2f}, max={spread.max():.2f})")
+        else:
+            w = 12
+            print(f"default window: w={w}")
+    else:
+        w = window_arg
+    t0 = int(window_starts[w])
+    print(f"item {item} (idx={item_idx}); window w={w}, t_start={t0}")
+
+    if window_arg is not None:
+        suffix = f"{item}_w{w:02d}"
+    elif narrowest:
+        suffix = f"{item}_narrowest"
+    else:
+        suffix = item
+    if no_zoom:
+        suffix = f"{suffix}_nozoom"
+    out = FIG_DIR / f"uq_envelope_{suffix}.pdf"
+    plot_2x2(data, item, item_idx, w, t0, out, with_zoom=not no_zoom)
+    print(f"wrote {out}")
+
+
+if __name__ == "__main__":
+    main()

uq/sample_lhs.py

@@ -0,0 +1,71 @@
+"""Latin hypercube sample of K=20 demand-side perturbation configurations
+for the §4.4 UQ experiment.
+
+Three demand-side knobs, perturbed jointly around the §4 baseline:
+  phi_AR  in [0.95, 0.999]   AR(1) drift coefficient (used directly)
+  rho_G   in [0.5,  2.0  ]   macro-shock multiplier (applied jointly to
+                             shock_count_scale and shock_height_scale)
+  rho_B   in [0.5,  2.0  ]   burst multiplier (applied jointly to
+                             burst_rate_scale and burst_height_scale)
+
+Writes output_uq/manifest.csv with columns (k, phi_AR, rho_G, rho_B).
+The submit script reads this and launches one simulator job per row.
+
+Synchronous scaling for shock and burst matches the §3.3 axis convention
+(shock axis = N x h^G; burst axis = r x h^P). Drift is a single scalar
+per run, replacing the per-item U[phi_lo, phi_hi] draw with phi_lo =
+phi_hi = phi_AR_k (matching the §3.3 drift sweep convention).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from scipy.stats import qmc
+
+
+K = 20
+SEED = 2025
+
+# (lo, hi) for each of the three demand-side knobs
+RANGES = {
+    "phi_AR": (0.95, 0.999),
+    "rho_G":  (0.5,  2.0),
+    "rho_B":  (0.5,  2.0),
+}
+
+REPO = Path(__file__).resolve().parents[1]
+OUT_DIR = REPO / "data" / "output_uq"
+
+
+def main() -> None:
+    sampler = qmc.LatinHypercube(d=len(RANGES), seed=SEED)
+    unit = sampler.random(n=K)                         # (K, 3) in [0, 1)
+
+    los = np.array([RANGES[k][0] for k in RANGES])
+    his = np.array([RANGES[k][1] for k in RANGES])
+    scaled = los + unit * (his - los)                  # (K, 3) in ranges
+
+    df = pd.DataFrame({
+        "k":      np.arange(1, K + 1),
+        "phi_AR": np.round(scaled[:, 0], 6),
+        "rho_G":  np.round(scaled[:, 1], 6),
+        "rho_B":  np.round(scaled[:, 2], 6),
+    })
+
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+    out_path = OUT_DIR / "manifest.csv"
+    df.to_csv(out_path, index=False)
+    print(f"Wrote {out_path}")
+    print(df.to_string(index=False))
+
+    print("\nRange checks:")
+    for col in ["phi_AR", "rho_G", "rho_B"]:
+        lo, hi = RANGES[col]
+        print(f"  {col:7s}: [{df[col].min():.4f}, {df[col].max():.4f}]  "
+              f"(target [{lo}, {hi}])")
+
+
+if __name__ == "__main__":
+    main()