Experimental. Stock & Flow is an experimental research project, not a production modeling tool. For real system dynamics work, use Simlin (source). Simlin's engine is written in Rust, and Simlin is faster, more complete and much better than this project.
This repository is still worth visiting for its library of 1,000 example models.
A browser-based stock-and-flow modeler with Euler, RK4 and Radau simulation, AI-assisted model drafting, an example model library and a Model Context Protocol (MCP) server.
Simulator · Model library · Usage and MCP guide · Documentation · Changelog
The library has 1,000 examples, 997 dynamic models and three labeled static calculators, in 26 subject areas from economics and climate to epidemiology, physics and ecology.
- Each model is one JSON file in
models/<subject>/, with its stocks, flows, variables, time settings, units and source reference. - Browse them at stockandflow.org, or fetch them through the API:
GET /api/models/catalogfor the index,GET /api/models/{id}for one model. - To use a model in another tool such as Simlin, export it as XMILE. Export covers a scalar subset and refuses conversions that would lose information.
A model that runs to completion is not a validated model. Check its source before relying on it. How the library was built and checked: curation decisions, reconstructions and the failure register.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 3250AI drafting is optional. Provider settings are described in .env.example and app/llm/; keep keys out of Git. The numerical engine never sends equations to a provider, and every numerical tool works without one. requirements-lock.txt records the tested development environment.
- Editor: diagrams, saved models, JSON and XMILE import and export, conservative Vensim MDL import, scenario comparison, four chart types, statistics and mobile panels.
- Engine: Euler and RK4, opt-in Radau for stiff systems, arrays and reusable modules, dimensional checks, feedback analysis and local parameter sensitivity.
- Checks: Settings → Check inputs or
POST /api/validateinspects names, references, syntax, initial values, flow endpoints, tables, settings and a short run. These checks do not establish scientific validity. - Limits: 500 explicit elements, 100,000 intervals and one million retained values per run. Unsupported constructs, such as XMILE queues, conveyors and nested models, are rejected rather than silently dropped.
Simlin remains faster on every workload measured in the engine comparison. Pinned Simlin observations record where the two engines agree and where they differ. This project has no Simlin runtime dependency and does not claim full Simlin or Vensim parity.
- REST: model catalog and CRUD under
/api/models, MDL import at/api/models/import/mdl, and/api/simulate,/api/validate,/api/compile,/api/units,/api/feedback,/api/analyzeand/api/analyze/statistics. - Hosted MCP: connect an HTTP-capable client to
https://stockandflow.live/mcp/. Legacy SSE is at/mcp/sse, and/mcp/infolists transports. - Local MCP (stdio):
.venv/bin/python -m app.mcp_serverfrom the repository directory. - Tools:
list_models,get_model,validate_model,simulate_model,compare_scenarios,analyze_model,export_model_xmile,generate_model_from_descriptionandmodify_existing_model, plus native engine tools. - Agent workspaces: over HTTP or SSE, an agent can open a private page, edit and run a model, and show the result. See the page protocol.
Numerical tools never save models. AI tools return unsaved drafts.
pip install -r requirements-dev.txt
python -m pytest -q
node scripts/check_frontend.cjs
node scripts/check_simulation_state.cjs
node scripts/check_workbench_v15.cjs
node scripts/check_series_controls.cjs
PYTHONPATH=. python scripts/check_mcp.py --stdio
PYTHONPATH=. python scripts/audit_library.py --full --tracked-only --output operations/library-full.jsonStart the application before the MCP client check. The JavaScript checks need Node.js. Offline pytest collection is limited to tests/. The test_*.py files at the top level are manual provider probes, not part of the suite.
Every active library model must pass its full default run. Model repairs and retirements need exact file hashes and backups. Never sync model directories, databases, credentials or configuration over production.
Architecture · Testing · Operations · All documentation
The code is released under the MIT License. Third-party model sources bundled under operations/*/sources/ keep their own license files.