Utopia

Traditional macroeconomic simulations are black boxes that take hours to run and cannot be optimized; Utopia is an end-to-end differentiable macroeconomic engine that runs 100K agents in 0.3 seconds and trains directly against historical crises.

By combining stock-flow consistency (SFC) with end-to-end differentiability via JAX, Utopia allows gradients to flow backward through the entire simulated economy—from a macroeconomic loss function through firm policies, credit markets, labor matching, and consumption.

The Benchmark: Empirically Validated

Our core claim is falsifiable and empirically validated. By training a Differentiable Firm Policy Network via backpropagation-through-simulation, Utopia achieves tight tracking error against actual historical GDP and unemployment figures during the three major modern macroeconomic shocks:

• 2008 Financial Crisis: 6.74 pts GDP tracking error, 8.94 pts Unemployment tracking error.
• 2020 Covid Shock: 12.26 pts GDP tracking error, 14.73 pts Unemployment tracking error.
• 2021 Supply Chain Crunch: 0.53 pts GDP tracking error, 1.43 pts Unemployment tracking error.

Run the reproducible benchmark yourself:

utopia train --scenario 2008 --seed 42

Who is Utopia For?

Utopia is built for quantitative researchers, policy analysts, and catastrophe modelers who require structural financial realism (no money is ever magically created or destroyed without central bank action) without sacrificing modern machine learning optimization and execution speed.

What's Live vs. Simulated

To remain perfectly honest about our current stage, here is what is actively running in the engine vs. what is currently simulated for integration planning:

Component	Status	Description
Core Engine	🟢 Live	JAX/Autodiff engine enforcing tick-by-tick Stock-Flow Consistency (Δ < $0.01).
LMM Policy	🟢 Live	Transformer-based Firm Policy Network trained via backprop-through-simulation.
Data Ingestion	🟢 Live	Direct pipeline to the St. Louis FRED API for historical macro data (GDP, Unemployment).
ERP Connectors	🟡 Simulated	SAP/Oracle mock connectors demonstrating structured auth/pagination; live integration planned.
Climate Models	🟡 Simulated	NOAA/USITC mock data; live integration planned for catastrophe modeling.

Roadmap

• Q1: Real-time ERP Connector Integrations (SAP, Oracle) for live supply chain data.
• Q2: Multi-region trade blocks, tariffs, and exchange rate dynamics.
• Q3: Scaling the JAX compilation to handle 1M+ agents across distributed TPU clusters.

---

View Architecture & Technical Details (Below the Fold)

The Edge: Full Differentiability + Stock-Flow Consistency

Our primary innovation is structural financial realism. jax.grad flows from the macroeconomic objective backward through the entire economy into a Learned Firm Policy Network.

Feature	Classical ABM	Utopia
Gradient through economy	❌ Not possible	✅ jax.value_and_grad end-to-end
Stock-flow consistency	❌ Rarely checked	✅ Enforced every tick (Δ < $0.01)
Learned agent policy	❌ Hand-coded rules	✅ Transformer trained via backprop-through-simulation
100K agents × 50 ticks	~180s (Python)	~0.3s (XLA-compiled)
Empirical validation	❌ Typically absent	✅ Calibrated against FRED 2008 GDP/unemployment

The Learned Macroeconomic Model (LMM) is a small, fully differentiable transformer (~26K params). The innovation isn't model size — it's that gradients flow through a strict, stock-flow-consistent economic environment into the network's policy weights.

Architecture

┌─────────────┐     ┌────────────────┐     ┌──────────────────┐
│  config.py  │────▶│ engine_jax.py  │────▶│ simulation_jax.py│
│  Parameters │     │ JAX Simulation │     │    Main Loop     │
│             │     │      Core      │     │    + Metrics     │
└─────────────┘     └────────────────┘     └─────────┬────────┘
                                                     │
                                           ┌─────────▼────────┐
                                           │    server.py     │
                                           │   FastAPI Node   │
                                           └──────────────────┘

Quick Start

Native Installation

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

utopia run --seed 42 --ticks 120

Docker Deployment

docker-compose up --build
docker-compose --profile dashboard up --build

CLI Commands (Requires Native Installation)

utopia run --seed 42 --ticks 120
utopia train --seed 42 --epochs 100 --ticks 50
utopia demo --seed 42 --ticks 30
utopia experiment --scenario-a baseline --scenario-b tariffs --ticks 120

Components

• config.py: Central SimulationConfig dataclass.
• engine_jax.py: Cobb-Douglas agents, producing firms, fractional matching markets, and SFC Engine.
• simulation_jax.py: Phased differentiable execution per tick.
• server.py: FastAPI server exposing asynchronous endpoints and a modern React-based dashboard.

Guardrails

1. Simulation only. Every result is about the simulation's internal dynamics. No predictions about real companies, markets, or events.
2. No narrative violence. Disasters, wars, and conflicts are implemented purely as numeric shocks to supply, demand, or trade cost parameters.
3. No alpha claims. This is a decision-support tool, not a trading system.

License

MIT