monte-carlo

Monte Carlo Simulation

Overview

This stage is stochastic — it samples from bounds many times. Contrast with run-scenarios, which evaluates the model deterministically at three points only.

The simulation itself is performed by a Python script (experiments/napkin_math/run_monte_carlo.py), not by the LLM. The script imports calculations.py, draws samples with a seeded NumPy RNG, runs the loop, and writes montecarlo.json. The script is authoritative; this skill is a thin wrapper that locates inputs, builds an optional settings file, and invokes the runner.

Stage 7 of the pipeline described in planexe_simulator/README.md.

When to Use

• User asks to "run Monte Carlo", "sample the bounds", "compute distributions", "estimate gate-pass probability", or "find which inputs drive uncertainty"
• User wants percentile bands (p05/p50/p95) or threshold pass rates (e.g. P(avoided_events ≥ 10))
• Final stage in the pipeline; only run after run-scenarios already shows a sane deterministic model

Not for: regenerating any prior artifact, replacing the deterministic scenario table (use run-scenarios), or claiming causality from sensitivity correlations.

Workflow

1. Get the inputs. Three required, one optional:

   • parameters JSON (e.g. output/v12/parameters.json)
   • bounds JSON (e.g. output/v12/bounds.json)
   • calculations Python module (e.g. output/v12/calculations.py)
   • settings JSON (optional — n_runs, seed, distribution_default, outputs_of_interest, thresholds, gate_probabilities, correlation_groups)

   If any required input is missing, ask. If the user wants thresholds or non-default settings, write them to a small JSON file and pass --settings.

2. Invoke the runner. Requires Python 3.11+ with NumPy:

   /opt/homebrew/bin/python3.11 experiments/napkin_math/run_monte_carlo.py \
     --parameters   <path>/parameters.json \
     --bounds       <path>/bounds.json \
     --calculations <path>/calculations.py \
     [--settings   <path>/settings.json] \
     [--output     <path>/montecarlo.json]