simpy

SimPy

Scope

Use this skill for process-based discrete-event models where active entities yield events and contend for resources: queues, production systems, logistics, networks, service operations, inventory, and other event-driven systems.

SimPy supplies an event scheduler and modeling primitives. It does not choose a scientifically valid conceptual model, input distribution, warm-up, run length, replication count, estimand, or causal interpretation. Treat those as simulation-study methodology, not SimPy API behavior.

Current release and installation

Verified 2026-07-23:

• Latest stable: SimPy 4.1.2, released on PyPI 2026-05-24; source tag 4.1.2 points to commit f4381649.
• Package metadata requires Python >=3.8 and classifies CPython 3.8-3.14 plus PyPy. SimPy has no runtime dependencies.
• 4.1.2 adds Python 3.13/3.14 support and modern-interpreter test fixes.
• Upstream and this skill are MIT-licensed.

Create a reproducible environment:

uv venv --python 3.13
source .venv/bin/activate
uv pip install "simpy==4.1.2"
python -c "import importlib.metadata; print(importlib.metadata.version('simpy'))"

Do not silently substitute the latest documentation build: it may describe an unreleased development revision. Use the versioned 4.1.2 links in references/sources.md.

Model workflow

1. Define purpose and estimands. State the decision/question, system boundary, entities, resources, state, outputs, time units, and terminating event or steady-state target.
2. Write a conceptual model first. Record assumptions, distributions, routing, priorities, initial conditions, and omitted mechanisms.
3. Implement generators. A SimPy process is an event-yielding Python generator. Register the generator object with env.process(...).
4. Bound execution. Give every production run explicit time, entity, event, and replication caps. Never call env.run() on a model containing an endless process.
5. Separate random streams. Use local RNG instances for logically distinct stochastic sources; retain a seed manifest.
6. Instrument deliberately. Observe state after the transition of interest, close time-weighted intervals at the horizon, and test that monitoring does not alter event order.
7. Verify and validate. Test deterministic edge cases, conservation identities, traces, queue discipline, and analytical benchmarks; compare against system or expert evidence for the stated purpose.
8. Run independent replications. Make intervals from replication-level estimates, not correlated entities within one run.
9. Report limitations. Include initialization, unfinished entities, run length, seeds/streams, precision, sensitivity, and validation evidence. Never convert simulation association into a causal claim.