What (One-liner)

Epicenter asset + initial shock → multi-step propagation through a cross-asset graph (7 nodes / 10 edges) with damping + recovery → per-node time series, peaks, and a Chinese causal explanation. Two entry points: NVIDIA preset scenario, or arbitrary symbol (yfinance real correlations or static fallback).

How to use

Canvas preset scenario:

  contagion_sim_v1 (scenario='nvidia_earnings_paradox', shock=100, steps=20)
  → peak_impacts {nvda, semi, cloud, energy, finance, treasury, crypto}
  → logic_lineage Chinese causal chain

Symbol-driven (upstream connected to price_factor):

  price_factor (AMD) → contagion_sim_v1 (shock=150)
  → automatically computes AMD vs SOXX/XLK/XLE/XLF/TLT/BTC correlations via yfinance
  → on failure falls back to SECTOR_EDGE_WEIGHTS['semiconductor']

Core formulas

See frontmatter formula. Four key steps:

1. Initial shock: impacts[epicenter] = shock_magnitude
2. Propagation: nodes with impact > 1 → outgoing × weight × damping → pending (with delay)
3. Arrivals: pending items firing this step → target = max(cur, cur + amount × 0.5)
4. Recovery: every node × (1 − recovery)

Assumptions & applicability

Assumptions: preset topology / SECTOR_EDGE_WEIGHTS US-only + stylized propagation + pinned Python float.

Applies to: cross-asset stress tests, NVIDIA demos, arbitrary-symbol epicenter scenarios.

Does not apply to: live trading, intraday, non-US markets, precise magnitude forecasting.

Known limitations

See frontmatter limitations. Seven key items: hard-coded topology / yfinance non-deterministic / SECTOR US-only / stylized amount×0.5 / recovery 5% / damping 0.85 / rounding locked.

References

• Elliott-Golub-Jackson (2014) AER — financial-network contagion
• Gai-Kapadia (2010) Proc Royal Society A — threshold contagion model
• Pangura Research Note 2026-03 (pending) — NVIDIA 7-node curation

Golden Test

tests/golden/fixtures/tier4/contagion_sim/ — captured_snapshot (3 entry points), 1e-10 tolerance. 12 tests:

6 Scenarios

• nvidia_default_shock / nvidia_small_shock / nvidia_large_shock
• symbol_fallback_nvda / symbol_fallback_amd
• simulate_contagion_direct

6 Contract tests

• result_structure_nvidia (7 nodes + 10 edges + key set)
• nvidia_graph_deterministic (two builds byte-identical)
• symbol_fallback_labels_data_source (_data_source='static_fallback')
• determinism (5 reruns byte-identical)
• recovery_monotonic_decay (isolated node decays monotonically)
• peak_impacts_match_timeseries (peak = max(timeseries) contract)

Changelog

• 1.0.0 (2026-04-21) — First Active (Tier 4 batch 3.1)