Shock Simulator

Shock Simulator is an evolving Python research prototype for studying oil-supply resilience under production and maritime disruptions. It combines national energy statistics, documented disruption estimates, deterministic simulation, and an interactive Streamlit dashboard.

Research status: The project is an exploratory, data-informed what-if framework. The current simulations use normalized units and simplified assumptions. They are not a global oil-market forecast or an operational policy tool.

Research question

How do disruptions to critical maritime energy routes and regional oil production affect supply availability, and how do inventory releases and temporary demand responses change the resulting shortages?

The current empirical focus is the 2026 Strait of Hormuz disruption. The project distinguishes production shut-ins, maritime transit disruption, national trade observations, inventory records, and simulated outcomes rather than treating them as interchangeable measures.

Current capabilities

• Deterministic day-by-day supply and demand simulation.
• Configurable supply disruption magnitude, timing, and duration.
• Reserve release constrained by starting inventory and a daily release limit, with optional piecewise drawdown-rate schedules indexed from first delivery.
• Gradual post-shock supply recovery.
• Demand reduction with configurable start day and duration.
• Daily unmet-demand and shortage-severity calculations.
• Six empirical/hypothetical scenario definitions and three response strategies (18 experiments).
• Sensitivity analysis for recovery, shock magnitude, reserve capacity, release limits, and demand reduction.
• JODI-Oil data loading and processing.
• EIA-based maritime-flow and production-shut-in reference datasets.
• Initial source-backed reserve profiles for the United States, Japan, South Korea, and Germany.
• Separate records for Japan's 2026 announced reserve releases and stockholding-obligation change.
• Reserve dataset schema validation and automated tests.
• Unit-checked U.S. SPR calibration adapter requiring an analyst-supplied physical daily-flow denominator and applying the DOE mobilisation lead time.
• Optional historical DOE 2016 SPR design-reference taper (4.4, 3.8, 3.4 and 1.9 million barrels/day bands), with the post-day-180 extension identified as an extrapolation.
• Separate Japan announcement denominator cross-check that does not mislabel equivalent-day calculations as release rates.
• Deterministic full-factorial uncertainty envelope covering six factors and 729 low/reference/high design points per selected scenario/strategy.
• Main-effect ranking for the six uncertainty factors, with full design-point and summary CSV exports.
• Country-specific importer stress tests using 2025 destination flow estimates for crude oil and condensates transiting Hormuz (China, India, South Korea and Japan).
• Separate LNG importer resilience scenarios using ACER/ICIS 2025 Hormuz destination-flow estimates for Bangladesh, Pakistan, India, China, South Korea and Japan.
• LNG response levers for alternative cargo availability, assumed finite buffer days and demand reduction, using separate million-cubic-metre units.
• Explicit alternative-supply delay, inventory-buffer assumptions, daily residual-gap calculations and CSV exports for importer scenarios.
• Streamlit dashboard with Plotly visualizations and CSV exports.

Research evidence and interpretation

The project uses several different evidence types:

Evidence	What it represents	What it does not establish
JODI country statistics	Reported national production, imports, exports, refinery intake and stocks	The maritime route used by a specific shipment
EIA chokepoint estimates	Estimated total oil flows through selected maritime routes	An equivalent loss of global oil supply
EIA production shut-ins	Estimated production unavailable in specified producer countries	A directly observed production series
Reserve profile sources	Inventory snapshots, capacities, stock categories and release procedures	That all recorded inventory is immediately deliverable
Reserve response events	Officially announced release plans or stockholding-policy changes	Verified physical withdrawals unless separately measured
Simulation output	Consequences under explicit model rules and assumptions	Causal proof or real-world predictive accuracy

The EIA-derived March–July 2026 benchmark is calculated from estimated regional production shut-ins divided by the February baseline for covered Gulf producers. It is not a global supply-loss percentage. The model currently applies this benchmark to a normalized system for comparative experiments.

Dashboard

Launch the application:

streamlit run app.py

The dashboard currently contains:

1. Simulation — configurable supply, demand, reserve and recovery parameters.
2. Scenario comparison — compare no intervention, reserve release and a combined response.
3. Sensitivity analysis — inspect how demand-reduction assumptions affect outcomes.
4. Empirical scenarios — compare six scenarios under three response strategies, inspect individual runs, and export the 18-experiment results.
5. Reserve calibration — translate a compatible dated U.S. SPR record into normalized inventory and release parameters after the user supplies a matching physical daily-flow denominator; apply the mobilisation delay and export calibration and simulation outputs.
6. Uncertainty analysis — run 729 combinations across six low/reference/high assumptions, inspect outcome ranges and main-effect rankings, and export all design points.
7. Importer resilience — select China, India, South Korea or Japan; stress-test the 2025 estimated Hormuz crude-flow baseline under disruption and analyst-defined replacement-supply and buffer assumptions.
8. LNG resilience — run a separate gas-volume stress test for Bangladesh, Pakistan, India, China, South Korea or Japan; vary disruption, replacement LNG, assumed buffer cover and demand response.

The empirical scenario experiments restrict the 10% demand-reduction response to the disruption window. Demand returns to baseline during recovery. Reserve releases may continue during recovery while a deficit remains and reserve stock is available.

Current model assumptions

The simulation is deterministic. It advances one day at a time:

1. Apply the specified supply loss during the disruption window.
2. Calculate demand, including any active demand-reduction policy.
3. Release reserves if enabled, limited by both the daily cap and remaining stock.
4. Calculate unmet demand and shortage severity.
5. After the supply shock ends, recover supply gradually toward baseline.

Important assumptions and limitations:

• Supply, demand and reserve quantities must use consistent units.
• The current empirical experiments use normalized units, not million barrels or barrels per day.
• Reserve capacity and daily release limits in the original 18 empirical experiments remain illustrative assumptions. The separate Reserve calibration tab translates only compatible U.S. SPR records using an explicitly user-supplied physical daily-flow denominator.
• Crude oil and refined-product inventories are not interchangeable without considering refining, quality, transport and distribution.
• The model does not yet explicitly represent oil prices, refinery constraints, alternative shipping routes, country-level trade networks or market substitution.
• The U.S. SPR calibration uses a country-specific reserve profile inside a normalized wider supply-disruption model; it is not a full U.S. oil-market, global trade, or Hormuz-importer model.
• Importer destination-flow estimates are rounded Vortexa estimates reproduced in a secondary visualization; they do not establish national import shares or total national import dependency.
• Importer alternative-supply and buffer inputs are scenario assumptions, not measured spare capacity, observed cargo substitution, or verified national strategic-stock volumes. Shared Saudi/UAE pipeline capacity is not allocated to importing countries.
• The crude importer panel covers crude oil and condensates only. The separate LNG panel uses annual ACER/ICIS destination-flow estimates and gas-volume units; its alternative LNG, buffer and demand-response inputs are analyst assumptions, not measured capability.
• The LNG destination-flow estimates do not represent total national LNG imports or import-dependency percentages. The IEA reports almost two-thirds of total LNG supplies in Bangladesh, India and Pakistan came via Hormuz in 2025; that contextual indicator is not substituted for missing national demand series in the simulator.
• The DOE 2016 drawdown schedule is a historical design reference, not current effective capacity. GAO reported effective aggregate drawdown capability of 2.700 million barrels/day versus a 4.415 design rate as of December 2025 (61%). The model keeps these dated measures separate; it does not infer a current site-level rate curve.
• Uncertainty-envelope minimum, median and maximum values summarize deterministic design points. They are not confidence intervals, probabilities, or expected values.
• The uncertainty design uses analyst-defined ranges and does not yet model correlated inputs or statistically estimated distributions.
• The model does not establish that observed national changes were caused solely by the Hormuz disruption.
• Severity thresholds are configurable assumptions, not empirically validated thresholds.

Data and research files

• data/raw/jodi/ — original JODI-Oil downloads.
• data/raw/other/eia_chokepoint_flows.csv — manually transcribed EIA route-flow estimates.
• data/raw/other/eia_production_shutins.csv — manually transcribed EIA production shut-in estimates.
• data/raw/other/reserve_response_events.csv — manually structured official Japanese reserve-response announcements.
• data/processed/reserve_profiles_initial.csv — source-backed reserve profile snapshots, preserving native units and stock definitions.
• data/processed/hormuz_importer_flows_2025.csv — 2025 destination estimates for crude oil and condensates transiting Hormuz, with source provenance and limitations.
• data/processed/hormuz_importer_lng_flows_2025.csv — ACER/ICIS 2025 LNG destination-flow estimates via Hormuz, in bcm/year.
• research/methodology.md — research and simulation methodology.
• research/data_dictionary.md — data fields and measurement units.
• research/source_register.md — source register.
• research/findings.md — descriptive results and scenario experiments.
• research/scenario_design.md — empirical and hypothetical scenario definitions.
• research/reserve_data_assessment.md — reserve-source assessment, comparability cautions and data gaps.
• research/reserve_calibration_method.md — unit-compatible conversion, lead-time treatment, and calibration limitations.
• research/uncertainty_analysis.md — bounded uncertainty factors, full-factorial design, main-effect method and interpretation.
• src/importer_resilience.py — crude-oil importer-country disruption, replacement-supply and buffer model.
• src/importer_lng_resilience.py — separate LNG importer volume-gap model in mcm/day and mcm.
• research/methodology.md, research/data_dictionary.md and research/source_register.md — importer/LNG evidence, model equations, source definitions and limitations.

The reserve data is an initial source inventory, not a calibrated cross-country reserve dataset. Missing values mean not reported or not established; they are not zero.

Repository structure

shock-simulator/
├── src/
│   ├── simulation.py
│   ├── scenarios.py
│   ├── empirical_scenarios.py
│   ├── sensitivity.py
│   ├── data_loader.py
│   ├── reserve_data.py
│   ├── reserve_calibration.py
│   ├── uncertainty.py
│   ├── importer_resilience.py
│   └── importer_lng_resilience.py
├── scripts/
│   └── validate_reserve_data.py
├── tests/
│   ├── test_simulation.py
│   ├── test_sensitivity.py
│   ├── test_empirical_scenarios.py
│   ├── test_reserve_data.py
│   ├── test_reserve_calibration.py
│   ├── test_uncertainty.py
│   ├── test_importer_resilience.py
│   └── test_importer_lng_resilience.py
├── data/
│   ├── raw/
│   │   ├── jodi/
│   │   └── other/
│   └── processed/
│       ├── hormuz_importer_flows_2025.csv
│       └── hormuz_importer_lng_flows_2025.csv
├── research/
├── app.py
├── main.py
├── requirements.txt
└── README.md

The virtual environment directory (usually .venv/) should remain local and should not be committed.

Setup

Python 3.10 or later is recommended.

Windows PowerShell

git clone https://github.com/udefusr/shock-simulator.git
cd shock-simulator
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

macOS / Linux

git clone https://github.com/udefusr/shock-simulator.git
cd shock-simulator
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Validation commands

Run all automated tests from the repository root:

python -m pytest -v

Validate the source-backed reserve profile and response-event files:

python -m scripts.validate_reserve_data

Run the built-in scenario comparison:

python -m src.scenarios

Run the sensitivity experiments:

python -m src.sensitivity

Development roadmap

• Basic daily supply-and-demand simulation.
• Reserve-release response and finite stock constraint.
• Gradual post-shock supply recovery.
• Severity classification and configurable thresholds.
• One-factor-at-a-time sensitivity analysis.
• JODI and EIA source data processing.
• Empirical scenario definitions and dashboard comparison.
• Time-bounded demand-response policy in empirical experiments.
• Initial national reserve profiles and response-event records.
• Reserve schema validation and automated tests.
• Reconcile and extend dated reserve inventory time series.
• Harmonize reserve categories and country-level demand denominators.
• Add an evidence-aware U.S. SPR calibration adapter with explicit demand denominator and mobilisation lead time.
• Extend reserve calibration with dated compatible inventory and release-rate series for Japan, South Korea, and Germany.
• Implement an optional DOE 2016 historical design-reference drawdown-rate schedule after day 90.
• Obtain a current, dated, site-level effective drawdown schedule before claiming current operational release capability.
• Calibrate deliverable reserve release constraints by country.
• Model production disruption separately from maritime transit disruption and rerouting.
• Add an initial importer-country flow stress-test model with explicit alternative-supply and buffer assumptions.
• Add country total-import denominators and matching trade-route/origin evidence before estimating national dependency shares.
• Model producer-country rerouting and shared pipeline capacity separately from importer replacement sourcing.
• Add a separate LNG importer volume-gap model with consistent gas-volume units; do not mix LNG data into crude-oil barrels/day.
• Add country-level total LNG import and gas-demand time series, storage and regasification constraints before treating the stress test as a national gas-system model.
• Add deterministic 729-point uncertainty envelope and main-effect screening for six model assumptions.
• Estimate defensible statistical distributions and correlated uncertainty from data before adding probabilistic forecasts.
• Complete research report, figures and portfolio demonstration.

Disclaimer

Shock Simulator is an educational and experimental research project. Its outputs depend on simplified assumptions and source limitations. They should not be used as forecasts, investment guidance, emergency-planning instructions or operational policy recommendations.

License

No license has been selected yet. Unless a license is added to this repository, the project remains under its default copyright and reuse is not automatically granted.