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

Reviewed 2026-10-01 against current official documentation and the released source:

• 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. A time horizon alone cannot stop an endless yield env.timeout(0) loop: events keep running at the same simulation time. Add an event-count or no-time-progress guard, and wait on state-change events instead of zero-delay busy polling.
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.

Read references/simulation-methodology.md before making inferential claims.

Minimal bounded model

import random
import simpy

HORIZON = 480.0
arrival_rng = random.Random(101)
service_rng = random.Random(202)
env = simpy.Environment()
server = simpy.Resource(env, capacity=2)
completed = []

def customer(arrival):
    with server.request() as request:
        yield request
        wait = env.now - arrival
        yield env.timeout(service_rng.expovariate(1 / 6.0))
    completed.append((env.now, wait))

def arrivals():
    for _ in range(10_000):  # Entity cap.
        delay = arrival_rng.expovariate(1 / 4.0)
        if env.now + delay >= HORIZON:
            return
        yield env.timeout(delay)
        env.process(customer(env.now))

env.process(arrivals())
env.run(until=HORIZON)

The numeric horizon is half-open: normal events scheduled exactly at 480.0 are not processed. Report unfinished entities rather than silently treating them as completed observations.

Core semantics

Environment and deterministic ordering

Environment is single-threaded. The queue is ordered by simulation time, event priority, then a strictly increasing event ID. Same-time, same-priority events are therefore processed FIFO in scheduling order. Model processes may represent

…