SimEngine

A domain-agnostic Monte Carlo simulation and decision intelligence system.

Zero dependencies. Pure Python stdlib. Local web UI. Runs anywhere Python runs.

SimEngine turns uncertainty into numbers you can act on. Define your variables, your logic, and your risk tolerances in a JSON config. The engine runs thousands of simulated futures, scores them, and — if you ask — evolves toward the best strategy that still respects your safety constraints.

Think of it as a calculator for uncertainty.

Quick Start

# 1. Clone the repository
git clone <repo-url> ~/projects/simengine
cd ~/projects/simengine

# 2. Start the web UI
cd v3 && python3 server.py

# 3. Open your browser
#    http://localhost:8420

That is it. No pip install, no Docker, no Node, no build step. Python 3.8+ is the only requirement.

Install as an MCP server

uvx simengine-mcp

Listed on the official MCP registry. Hosted, no-install endpoint: join the waitlist.

Optional Native Acceleration

The default engine remains pure Python. A Rust workspace now lives at the repo root for optional acceleration of metric reducers, trajectory bands, risk evaluation, histograms, and native pre-sampling of simple numeric variable distributions.

This is opt-in and does not change the baseline workflow above.

Workspace layout

Cargo.toml
crates/
├── simengine-core/   # pure Rust numeric kernels
└── simengine-py/     # PyO3 extension module: simengine_native
v3/native.py          # optional loader + Python fallback glue

Build the native extension

cd crates/simengine-py
python3 -m venv ../../.venv
source ../../.venv/bin/activate
pip install maturin
maturin develop --release

After that, the existing Python engine will automatically use the native reducers and the native batch sampler when simengine_native is importable. If the module is missing or fails, SimEngine falls back to the existing Python implementation.

The batch sampler is conservative:

• it only activates for plain numeric variable params
• it stays off for correlated configs
• it can be disabled explicitly with SIMENGINE_DISABLE_NATIVE_SAMPLING=1

This keeps the expression engine, accumulators, and metrics in Python while moving a larger chunk of the Monte Carlo loop into Rust.

There is also a narrower native fast path for stochastic expressions:

• binomial(n, p) can be delegated to Rust when the extension is installed
• it can be disabled explicitly with SIMENGINE_DISABLE_NATIVE_EXPR_SAMPLING=1

This helps domains whose step_logic relies heavily on binomial(...) while still leaving general expression evaluation in Python.

On the Python side, repeated expressions are now compiled once and reused across Monte Carlo runs. That cache can be disabled explicitly with SIMENGINE_DISABLE_EXPR_CACHE=1 for benchmarking or troubleshooting.

The diagnostics module applies the same idea to its AST-only safe evaluator: parsed trees are reused across calls, and that cache can be disabled with SIMENGINE_DISABLE_SAFE_EXPR_CACHE=1.

What It Does

• Monte Carlo simulation -- Run 5,000+ parallel futures for any domain you can describe in JSON.
• Safety constraints -- Chance constraints ("at most 15% probability of going broke") and CVaR constraints ("the average worst-case loss must not exceed $X").
• Genetic optimizer -- Evolve control parameters toward the best outcome while respecting safety bounds. Crossover, mutation, elitism, tournament selection.
• Bayesian updating -- Feed observed data back into your model. Conjugate priors (Beta-Binomial, Gamma-Poisson, Normal-Normal) tighten distributions as evidence arrives.
• Diagnostics -- Convergence analysis (proves your sample size is sufficient), sensitivity analysis (ranks which inputs drive the output), deterministic baseline comparison (quantifies the value of simulation over spreadsheet math).
• Web UI -- Histograms, trajectory fans, risk gauges, scenario comparison with control sweeps and input diffs, domain wizard, Bayesian update modal, export to standalone HTML report.
• AI agent integration -- POST a config inline to /api/simulate and get structured results back. No files needed. LLMs can use SimEngine as a tool (llms.txt at the repo root and GET /llms.txt orient them).
• Validated calibration -- A sqlite forecast ledger scores predictions with proper scoring rules (Brier / log-loss / CRPS), and the pipeline is backtested on ~2,800 walk-forward monthly forecasts over decades of public FRED data. Run it yourself: cd v3 && python3 backtest.py (offline, from committed snapshots). Results: docs/backtests/.

Architecture

All production code lives in v3/.

v3/
├── kernel.py          Monte Carlo engine, distributions, safety evaluation,
│                      fitness scoring, genetic optimizer, experiment manifests
├── server.py          HTTP server (port 8420), all API endpoints, report generation
├── bayesian.py        Conjugate prior updates for calibrating parameters from data
├── diagnostics.py     Convergence, sensitivity (OAT), baseline comparison, AST evaluator
├── static/
│   └── index.html     Single-page web UI (vanilla HTML/JS/CSS, no framework)
└── domains/
    ├── _template.json              Annotated starter config
    ├── business_pipeline_v3.json   B2B sales pipeline
    ├── investment_portfolio.json   Portfolio allocation
    ├── investment_portfolio_v2.json  Fat-tailed returns (Student's t)
    ├── job_search.json             Job search decision model
    ├── project_timeline.json       Software project estimation
    ├── real_estate_rental.json     Rental property analysis
    └── saas_startup.json           SaaS MRR growth and runway

Domain Config Schema

A domain config is a single JSON file that fully describes the simulation. The v3 schema separates variables into three semantic categories, which matters for Bayesian updating and optimization.

Published contract: the machine-readable JSON Schema (Draft 2020-12) is served live at GET /api/schema — hand it to any AI to author a valid config in one shot. A plain-language field reference is in docs/schema-reference.md. The schema is verified against every shipped domain in the test suite.

Top-Level Fields

Variable Definition

All three variable categories (parameters, controls, exogenous) share the same structure:

{
  "monthly_churn_rate": {
    "distribution": "triangular",
    "params": {"low": 0.02, "mode": 0.05, "high": 0.12},
    "calibration": {
      "source": "Baremetrics Open Benchmarks: median monthly churn 5-8%",
      "updatable": true,
      "update_method": "Beta-Binomial conjugate from observed monthly cancellations"
    }
  }
}

Available Distributions

Step Logic

An ordered list of computations executed each time step. Each entry has a target name and either an expr (expression string) or a sample (inline distribution):

"step_logic": [
  {"target": "new_leads",    "expr": "binomial(round(demand), conversion_rate)"},
  {"target": "revenue",      "expr": "new_leads * price_per_unit"},
  {"target": "costs",        "expr": "fixed_cost + variable_cost * new_leads"},
  {"target": "net_income",   "expr": "revenue - costs"},
  {"target": "shock_event",  "sample": {"distribution": "bernoulli", "params": {"p": 0.02}}}
]

Available expression functions: min, max, abs, round, sum, len, int, float, sqrt, log, exp, ceil, floor, pow, random(), gauss(mu, sigma), binomial(n, p), clamp(val, lo, hi), range(). Ternary expressions work: 100 if x > 0 else 0.

Accumulators

Running state that persists across time steps: