L3 Risk & Monte Carlo
Relevant source files
The following files were used as context for generating this wiki page:
L3 Risk & Monte Carlo represents the third layer of the ZINC-Fusion-V15 hierarchical ensemble forecasting system. Its primary purpose is to provide institutional-grade risk assessment for CBOT Soybean Oil (ZL) futures by generating barrier probabilities, time-to-touch metrics, and Value at Risk (VaR) summaries. It transforms calibrated probabilistic forecasts into actionable risk intelligence, supporting procurement timing and hedging decisions.
The system operates by consuming calibrated P10/P50/P90 quantiles from the L2 Calibration layer and simulating thousands of potential price paths. These simulations account for asymmetric volatility and current market regimes to ensure that uncertainty ranges widen appropriately across different forecast horizons (1W, 1M, 3M, 6M).
Sources: README.md:16-32, AGENTS.md:14-18, scripts/run_monte_carlo.py:1-25
Architecture and System Flow
The Risk Engine is designed as a deterministic pipeline that consumes upstream data and produces structured risk artifacts. It utilizes asymmetric path simulation and regime-adjusted volatility multipliers to model reality without manual bias.
The diagram above illustrates the flow from L2 calibrated quantiles through the simulation engine to final risk metrics.
Sources: scripts/run_monte_carlo.py:27-40, README.md:79-81
Simulation Methodologies
The engine supports two primary simulation methods to ensure robust risk modeling under different data conditions.
Asymmetric Diffusion
This method uses the quantile spread (P90-P10) to define an uncertainty envelope. It extracts implied volatilities based on the distance between the median (P50) and the outer tails, allowing for different volatilities in upward versus downward movements.
Sources: scripts/run_monte_carlo.py:192-210
GJR-GARCH Modeling
The enhanced simulation uses GJR-GARCH to forecast volatility with proper clustering and "leverage effects" (asymmetry). This model fits historical returns to project volatility into the forecast horizon, providing a more statistically rigorous view of potential price action.
Sources: scripts/run_monte_carlo.py:246-265
Volatility Regime Adjustments
The engine applies multipliers based on the current market regime stored in the analytics.vol_regimes table.
| Regime | Volatility Multiplier | Description |
|---|---|---|
| High | 1.5x | Extreme market stress/volatility |
| Elevated | 1.25x | Heightened uncertainty |
| Normal | 1.0x | Standard market conditions |
| Low | 0.7x | Suppressed volatility |
| Suppressed | 0.5x | Minimal price movement |
Sources: scripts/run_monte_carlo.py:64-70, scripts/run_monte_carlo.py:175-188
Risk Metrics and Data Model
The Monte Carlo runs produce a specific set of risk metrics used for dashboard rendering and strategy development.
Key Risk Metrics
- VaR (Value at Risk): Calculated at 1%, 5%, and 10% levels to estimate potential losses at various confidence intervals.
- CVaR (Conditional VaR): Also known as Expected Shortfall, this measures the average loss in the worst-case tail (beyond the VaR threshold).
- Zone Probabilities: The probability of price entering specific forecast zones (e.g., the P30-P70 "central band") or touching specific barriers like the P10 floor or P90 ceiling.
- Prob Up/Down: The percentage of simulations resulting in positive returns or moves exceeding ±5%.
Sources: scripts/run_monte_carlo.py:53-61, scripts/run_monte_carlo.py:328-356, scripts/run_monte_carlo.py:488-500
Database Artifacts
| Table | Schema | Description |
|---|---|---|
monte_carlo_runs | forecasts | Stores full path percentiles and metadata for each run. |
risk_metrics | analytics | Summarized VaR, CVaR, and probability flags. |
probability_distributions | forecasts | Terminal values for probability density functions. |
production_1d | forecasts | Updated with zone touch/enter probabilities for the UI. |
Sources: scripts/run_monte_carlo.py:397-440, README.md:189-205
Integration with Strategy and Synthesis
The outputs from L3 are consumed by the L5 Synthesis engine (generate_synthesis.py) to produce natural language market briefings.
The sequence shows how Monte Carlo data becomes qualitative intelligence for the end-user.
Sources: scripts/generate_synthesis.py:58-85, frontend/src/app/strategy/page.tsx:88-105
Technical Constraints and Guardrails
The Risk Engine is governed by strict "non-negotiable" rules defined in the system architecture:
- Quantile Monotonicity: Uncertainty ranges must widen with longer horizons; a 1W range cannot be wider than a 3M range.
- Staleness Guard: The engine rejects production forecasts older than 5 business days to prevent stale risk modeling.
- Deterministic Nature: No user "sliders" are allowed; simulations must be purely data-driven from calibrated inputs.
- Quantile Ordering: Strict ordering (P10 < P50 < P90) is enforced; crossing quantiles will raise a
ValueErrorand halt the simulation.
Sources: scripts/run_monte_carlo.py:15-25, scripts/run_monte_carlo.py:153-165, cubic.yaml:184-192
Summary
L3 Risk & Monte Carlo provides the statistical backbone for the ZINC-Fusion-V15 platform's decision support. By simulating 10,000 paths per horizon using asymmetric and GARCH-informed models, it quantifies the probability of price outcomes. This allows the system to identify tail risks (e.g., VaR/CVaR) and zone probabilities, which are then used to inform the high-level procurement posture (BUY, WAIT, ACCUMULATE) displayed on the strategy dashboard.