# stockandflow.live — Full Documentation for LLMs

> See also: [llms.txt](https://stockandflow.live/llms.txt) for a concise overview.

## About

Stock & Flow is a free, browser-based systems dynamics simulator. It provides a visual drag-and-drop editor for building stock-and-flow diagrams, runs simulations in real time, and includes a library of 1,082 pre-built models across 27 categories. Models can be generated from natural language using AI, exported in XMILE format for use with Vensim/Stella/iThink, and accessed programmatically via REST API or MCP server.

The companion site [stockandflow.org](https://stockandflow.org/) provides a browsable model library with XMILE and JSON download links for every model.

## Pages

- https://stockandflow.live/ — Main simulator application (D3.js canvas editor, real-time simulation, AI model generation)
- https://stockandflow.org/ — Model library and documentation site (browse by category, search, download XMILE/JSON)

## Features

- Visual stock-and-flow diagram editor built with D3.js
- Drag-and-drop stocks, flows, variables, and connectors
- Real-time simulation with adjustable time settings
- Two integration methods: Euler and Runge-Kutta 4th order (RK4)
- AI-powered model generation from natural language descriptions
- AI-powered model modification (add components to existing models)
- AI-powered simulation analysis with pattern recognition
- Scenario comparison (run multiple parameter sets side by side)
- Sensitivity analysis and equilibrium detection
- XMILE import and export (compatible with Vensim, Stella, iThink)
- JSON model import/export
- 1,082 pre-built models in 27 categories

## Model Categories (27)

| Category | Count | Description |
|----------|-------|-------------|
| economics | 261 | Macro/microeconomics, market dynamics, supply/demand, trade, monetary policy |
| climate | 123 | Carbon cycles, temperature models, greenhouse gas dynamics, sea level |
| social | 117 | Population dynamics, social networks, opinion formation, cultural change |
| healthcare | 75 | Disease progression, hospital capacity, drug pharmacokinetics, public health |
| epidemiology | 74 | SIR/SEIR models, disease spread, vaccination strategies, pandemic modeling |
| physics | 64 | Thermodynamics, mechanics, electrical circuits, wave dynamics |
| education | 40 | Learning models, student retention, knowledge transfer, skill acquisition |
| other | 39 | Miscellaneous systems not fitting other categories |
| finance | 36 | Investment models, portfolio dynamics, banking systems, debt cycles |
| management | 36 | Project management, organizational dynamics, supply chains, inventory |
| agriculture | 34 | Crop growth, soil dynamics, pest management, irrigation, livestock |
| classic | 29 | Foundational SD models (bathtub, exponential growth, S-curve, oscillator) |
| technology | 27 | Technology adoption, software development, innovation diffusion |
| energy | 24 | Energy production, grid dynamics, renewable transitions, storage |
| psychology | 20 | Cognitive models, motivation, habit formation, stress dynamics |
| biology | 16 | Cell dynamics, gene regulation, metabolic pathways, organ systems |
| transportation | 14 | Traffic flow, fleet management, congestion, transit systems |
| evolution | 11 | Natural selection, genetic drift, speciation, adaptation |
| environment | 9 | Water systems, pollution, waste management, biodiversity |
| neuroscience | 9 | Neural firing, neurotransmitter dynamics, brain region interactions |
| political | 8 | Governance models, policy feedback, voting dynamics, conflict |
| marine | 6 | Ocean ecosystems, fisheries, coral reefs, marine food webs |
| urban | 5 | City growth, housing markets, infrastructure, land use |
| engineering | 2 | Control systems, structural dynamics |
| ecology | 1 | Predator-prey, ecosystem dynamics |
| test | 1 | Test models |
| uncategorized | 1 | Unclassified models |

## REST API

Base URL: `https://stockandflow.live`

### Models API (prefix: /api/models)

#### GET /api/models
List all models in the library.

Response: JSON array of model objects. Each model includes:
- `id` (string): Unique model identifier (e.g. "predator-prey-stable")
- `name` (string): Display name
- `description` (string): What the model represents
- `category` (string): Category name (see table above)
- `stocks` (array): Stock definitions with id, name, initial_value, equation, position
- `flows` (array): Flow definitions with id, name, equation, from_stock, to_stock, position
- `variables` (array): Auxiliary variable definitions with id, name, equation, position
- `connectors` (array): Information links between elements
- `time_settings` (object, optional): Default simulation parameters

#### GET /api/models/{model_id}
Get a single model by ID.

Parameters:
- `model_id` (path, string, required): The model's unique ID

Response: Full model object (same structure as list items).

#### POST /api/models
Create a new model.

Body: JSON model object with stocks, flows, variables, connectors.

Response: Created model object with assigned ID.

#### PUT /api/models/{model_id}
Update an existing model.

Parameters:
- `model_id` (path, string, required): Model ID to update

Body: Full model object.

#### DELETE /api/models/{model_id}
Delete a model.

Parameters:
- `model_id` (path, string, required): Model ID to delete

#### POST /api/models/import/xmile
Import a model from XMILE XML format.

Body: `{ "xmile": "<xmile xml string>" }`

Response: Parsed model object.

#### GET /api/models/{model_id}/export/xmile
Export a model to XMILE XML format.

Parameters:
- `model_id` (path, string, required): Model ID to export

Response: XMILE XML string (compatible with Vensim, Stella, iThink).

### Simulation API (prefix: /api)

#### POST /api/simulate
Run a simulation.

Body:
- `model_id` (string, optional): ID of a library model to simulate
- `model` (object, optional): Full model object to simulate directly
- `time_settings` (object, optional): Override default time settings
  - `start` (float, default 0): Start time
  - `end` (float, default 100): End time
  - `dt` (float, default 0.25): Time step
  - `integration_method` (string, default "euler"): "euler" or "rk4"

Response:
- `time` (array of float): Time points
- `values` (object): Map of variable name → array of values at each time point

### AI/LLM API (prefix: /api/llm)

Requires ANTHROPIC_API_KEY or OPENAI_API_KEY configured on the server.

#### GET /api/llm/status
Check if AI generation is available.

Response: `{ "available": true/false }`

#### POST /api/llm/generate
Generate a new model from a natural language description.

Body: `{ "description": "Population growth with births and deaths" }`

Response: Generated model object.

#### POST /api/llm/modify
Modify an existing model using natural language.

Body:
- `model_id` (string, optional): Library model to modify
- `model` (object, optional): Custom model to modify
- `modification` (string): What to change (e.g. "Add a vaccination flow")

Response: Modified model object.

#### POST /api/llm/find-equilibrium
Find equilibrium values for a model.

Body:
- `model` (object): The model to analyze
- `target_stocks` (array of string, optional): Specific stocks to find equilibrium for
- `max_iterations` (int, default 100): Maximum iterations

#### POST /api/llm/fit-to-data
Fit model parameters to historical data.

Body:
- `model` (object): The model to fit
- `historical_data` (object): Map of variable name → array of observed values
- `time_points` (array of float): Time points for the data
- `max_iterations` (int, default 200): Maximum iterations

#### POST /api/llm/refine-model
Refine a model based on simulation results and feedback.

Body:
- `model` (object): Current model
- `simulation_results` (object): Results from a simulation run
- `feedback` (string): What should be improved

#### POST /api/llm/tune
Auto-tune model parameters for better behavior.

### Analysis API (prefix: /api)

#### GET /api/analyze/status
Check if AI analysis is available (requires GEMINI_API_KEY).

#### POST /api/analyze
AI-powered analysis of simulation results. Returns pattern recognition, insights, and recommendations.

Body:
- `model_id` (string, optional): Model ID for context
- `model` (object, optional): Model object for context
- `simulation_results` (object, required): Must contain `time` and `values`
- `question` (string, optional): Specific question about the results

#### POST /api/analyze/statistics
Pure statistical analysis without AI.

Body:
- `simulation_results` (object, required): Must contain `time` and `values`

Response: Statistical measures (min, max, mean, standard deviation, trends, peaks, correlations).

#### POST /api/analyze/ask
Ask a natural language question about simulation results.

### Other Endpoints

#### GET /health
Health check endpoint.

#### GET /sitemap.xml
XML sitemap.

#### GET /robots.txt
Robots.txt with sitemap reference.

## MCP Server

Stock & Flow includes an MCP (Model Context Protocol) server for AI agent integration.

### Connection

SSE transport at: `https://stockandflow.live/mcp/sse`
Info endpoint: `https://stockandflow.live/mcp/info`

### Claude Code Configuration

```json
{
  "mcpServers": {
    "systems-modeler": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://stockandflow.live/mcp/sse"]
    }
  }
}
```

### MCP Tools (7)

#### list_models
Browse the model library. Filter by category or search by keyword.
- `category` (string, optional): Filter by category name
- `search` (string, optional): Search keyword in names and descriptions
- `limit` (int, default 20): Maximum results

#### get_model
Get full model definition including stocks, flows, variables, equations, and time settings.
- `model_id` (string, required): Model ID to retrieve

#### simulate_model
Run a simulation and get time series results with summary statistics.
- `model_id` (string, optional): Library model ID
- `model_json` (object, optional): Custom model JSON
- `start_time` (float, default 0): Start time
- `end_time` (float, default 100): End time
- `dt` (float, default 0.25): Time step
- `integration_method` (string, default "euler"): "euler" or "rk4"

#### generate_model_from_description
Create a new model from natural language using AI.
- `description` (string, required): What system to model

#### modify_existing_model
Modify an existing model using natural language instructions.
- `model_id` (string, optional): Library model to modify
- `model_json` (object, optional): Custom model to modify
- `modification` (string, required): What to change

#### compare_scenarios
Run multiple simulations with different parameters and compare.
- `model_id` (string, required): Base model ID
- `scenarios` (string, required): JSON array of scenario objects with `name` and `parameters`

#### export_model_xmile
Export a model to XMILE format for Vensim/Stella/iThink.
- `model_id` (string, required): Model ID to export

## Model Structure

Each model contains:

```json
{
  "id": "model-id",
  "name": "Model Name",
  "description": "What this model represents",
  "category": "economics",
  "stocks": [
    { "id": "stock-1", "name": "Population", "initial_value": 100.0, "equation": "", "position": {"x": 200, "y": 200} }
  ],
  "flows": [
    { "id": "flow-1", "name": "Births", "equation": "birth_rate * Population", "from_stock": null, "to_stock": "stock-1", "position": {"x": 100, "y": 200} }
  ],
  "variables": [
    { "id": "var-1", "name": "birth_rate", "equation": "0.03", "position": {"x": 200, "y": 100} }
  ],
  "connectors": [
    { "id": "conn-1", "from_element": "birth_rate", "to_element": "Births" }
  ],
  "time_settings": {
    "start": 0, "end": 100, "dt": 0.25, "integration_method": "euler"
  }
}
```

- *Stocks* accumulate values over time (levels, populations, inventories)
- *Flows* change stock values per time step (rates, transfers)
- *Variables* are auxiliary calculations used in flow equations
- *Connectors* show information dependencies between elements
- Flow equations reference stock and variable names directly

## Technical Details

- Built with: Python, FastAPI, D3.js
- Simulation: Custom Euler and RK4 integrators
- Model storage: JSON file-based (1,082 pre-built models)
- AI: Anthropic Claude / OpenAI for model generation; Google Gemini for analysis
- MCP: FastMCP with SSE transport
- Hosted on: Dedicated VPS with nginx reverse proxy, systemd service

## FAQ

Q: Is Stock & Flow free to use?
A: Yes, the simulator and all 1,082 models are completely free with no signup required.

Q: What is systems dynamics?
A: Systems dynamics is a methodology for understanding complex systems using stocks (accumulations), flows (rates of change), and feedback loops. It was developed by Jay Forrester at MIT in the 1950s.

Q: Can I export models to other tools?
A: Yes, models can be exported in XMILE format, which is compatible with Vensim, Stella, iThink, and other systems dynamics software. JSON export is also available.

Q: How does AI model generation work?
A: Describe a system in natural language (e.g. "pandemic spread with vaccination") and the AI generates a complete stock-and-flow model with appropriate stocks, flows, variables, equations, and initial values.

Q: What integration methods are available?
A: Euler (fast, first-order) and RK4 (Runge-Kutta 4th order, more accurate for stiff systems). Default is Euler with dt=0.25.

Q: Can I use Stock & Flow from my AI agent?
A: Yes, connect via the MCP server at stockandflow.live/mcp/sse to browse models, run simulations, generate new models, and compare scenarios directly from Claude, ChatGPT, or other MCP-compatible agents.

## Related Sites

- https://stockandflow.org/ — Model library with XMILE/JSON downloads
- https://helloandy.net/ — Developer tools and articles
- https://launch.pics/ — AI image pipeline builder with public API
- https://everyone.food/ — Recipe site with kitchen tools and calorie API
- https://contextwire.dev/ — Search API, MCP server, and SDK
- https://mcp.vin/ — VIN decoder with MCP server
- https://qrmcp.dev/ — QR code generator with MCP server
- https://webmcplist.com/ — WebMCP directory
- https://qrcode.host/ — AI microsite builder with QR codes
- https://croton.news/ — Hyperlocal news for Croton-on-Hudson, NY