Skip to content

Naga

Naga is a simulation engine for Python, built on SimPy. A model is a JSON file: blocks (create, process, seize, batch, decide, transport, ...) joined by links, with resources, schedules, failures and costs. The engine runs it for a number of replications and returns the statistics as pandas frames, with confidence intervals. The same file can also hold stocks and flows (system dynamics), rate-based quantities such as tanks and batteries, and populations of agents, all on one clock. An MCP server offers the same operations to an LLM agent.

What goes into the engine, what it does, and what comes out

pip install nagasim
naga --help

Python 3.11 or later. It depends on SimPy, NumPy, pandas, SciPy and openpyxl.

What it is not

  • Not an editor. There is no window, no canvas and no animation here. naga run --player writes one HTML file that replays a run in a browser, and naga viewer one in which a reader re-runs the model; those are the only pictures.
  • Not SimPy with helpers. You do not write generator functions. A model is data, and what a block can do is fixed by its type and its expressions. When the logic you need is not a block, raw SimPy is the better tool: see Coming from SimPy.
  • Not stable yet. Before 1.0 the Python API may change between minor versions. Model files always migrate forward, and agent tool names and problem codes are permanent.

Where to go

You want to Read
run something in a minute Quick start
see what a model looks like and what it gives Gallery
check the engine against models with a known answer Reference models
map what you know onto this Coming from SimPy, Arena, AnyLogic, Vensim, NetLogo
write a model file Model file format, Blocks
know what a part of a model does when it runs Modelling guide
compare, search and check models Experiments, Model assertions, Semantic diff
call it from a script or a notebook Python API
let an agent build and run models Use with an agent
give someone a model they can run in a browser Sharing a model
follow a plant and forecast from its state Digital twin
know what a model file can and cannot do to your machine Security

An LLM agent reading this site can start from llms.txt.

Apache License 2.0. Source and issues: github.com/TheMattHub/naga.