Stochastic Warfare¶
High-fidelity stochastic wargame simulator -- multi-scale, multi-domain, multi-era.
What Is This?¶
Stochastic Warfare is a headless Python simulation engine that models warfare across multiple scales -- from individual unit engagements up through tactical battles, operational battlefields, and multi-day strategic campaigns. Every outcome is driven by stochastic and signal-processing-inspired models: Markov chains, Monte Carlo methods, Kalman filters, Poisson processes, queueing theory, and SNR-based detection theory.
Key Capabilities¶
- Multi-scale simulation -- strategic (hours), operational (minutes), and tactical (seconds) resolution with automatic scale switching
- Multi-domain warfare -- ground, air, naval (surface + subsurface), space, electronic warfare, cyber, and CBRN effects fully integrated
- Multi-era coverage -- Modern (Cold War--present), WW2, WW1, Napoleonic, and Ancient/Medieval eras with era-specific mechanics
- Stochastic models throughout -- 10+ mathematical models (Markov, Monte Carlo, Kalman, Poisson, queueing, Lanchester, Wayne Hughes salvo, Boyd OODA, Beer-Lambert DEW)
- AI commanders -- 9 doctrinal schools (Clausewitz, Maneuver, Attrition, AirLand Battle, Air Power, Sun Tzu, Deep Battle, Mahanian, Corbettian) with OODA decision cycles
- Validated against history -- 73 Easting, Falklands Naval, Golan Heights engagements and campaigns with Monte Carlo statistical comparison
Architecture at a Glance¶
The engine is composed of 12 top-level modules with a strict one-way dependency graph:
core -> coordinates -> terrain -> environment -> entities -> movement
-> detection -> combat -> morale -> c2 -> logistics -> simulation
Dependencies flow downward only. Entities hold data; modules implement behavior (ECS-like separation). All randomness flows through per-module PRNG streams for deterministic reproducibility.
Getting Started¶
Prerequisites¶
- Python >= 3.12 (pinned to 3.12.10 via
.python-version) - uv -- used exclusively for package management
Quick Setup¶
uv sync --extra dev # creates .venv, installs all deps including pytest/matplotlib
uv run python -m pytest --tb=short -q # run the test suite
See the Getting Started Guide for a complete tutorial including running your first scenario.
Explore the Documentation¶
| Section | What You'll Find |
|---|---|
| Getting Started | Installation, first scenario run, understanding output |
| Web UI Guide | Running the web application, browsing scenarios, viewing results, editing configs |
| Scenario Library | Complete scenario catalog, YAML format reference |
| Architecture | Module design, simulation loop, spatial model, engine wiring |
| Mathematical Models | All 10 stochastic models with formulas and worked examples |
| API Reference | Key classes, methods, configuration, usage patterns |
| Era Reference | All 5 eras with mechanics, units, and scenarios |
| Units & Equipment | Unit data model, modern + historical unit catalogs |
Project Status¶
| Block | Phases | Focus | Status |
|---|---|---|---|
| MVP | 0--10 | Core engine (terrain through campaign validation) | Complete |
| Post-MVP | 11--24 | Fidelity, EW, Space, CBRN, AI schools, 4 historical eras, unconventional warfare | Complete |
| Block 2 | 25--30 | Integration, polish, data expansion, scenarios | Complete |
| Block 3 | 31--36 | Documentation site, API, frontend, visualization | Complete |
| Block 4 | 37--39 | Integration fixes, map enhancements, packaging | Complete |
| Block 5 | 40--48 | Core combat fidelity — battle loop wiring, terrain interaction, ROE, composite victory, deficit resolution | Complete |
| Block 6 | 49--57 | Final tightening — calibration hardening, combat polish, engine wiring, validation | Complete |
| Block 7 | 58--67 | Final engine hardening — structural verification, environment wiring, engine integration | Complete |
| Block 8 | 68--82 | Consequence enforcement, scenario expansion, postmortem & documentation | Complete |
| Block 9 | 83--91 | Performance at scale — profiling, spatial culling, LOD, parallelism | Complete |
| Block 10 | 92--97 | UI depth & engine exposure — analytics, frame enrichment, metadata | In Progress |
~10,694 tests (~10,322 Python + 372 frontend) across ~400 test files. ~748 YAML data files defining units, weapons, ammunition types, sensors, signatures, doctrines, commanders, and 46 scenarios across 5 eras.
License¶
PolyForm Noncommercial License 1.0.0 -- free for personal, academic, and research use. Commercial/institutional use requires a separate license (claymsmith1@gmail.com).