simpy

Files (16)

• SKILL.md
• cli-guide.md · references/
• events.md · references/
• monitoring.md · references/
• process-interaction.md · references/
• real-time.md · references/
• resources.md · references/
• simulation-methodology.md · references/
• sources.md · references/
• _common.py · scripts/
• basic_simulation_template.py · scripts/
• bounded_queue_scenario.py · scripts/
• event_trace_summary.py · scripts/
• replication_runner.py · scripts/
• resource_monitor.py · scripts/
• validate_simulation_config.py · scripts/

SKILL.md (first lines)

# 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:

```bash
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

```python
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
concurrency, but callbacks execute sequentially and deterministically.

This orders the events currently queued. A callback can insert an urgent event at
the current time, so a valid processing trace need not have globally increasing
priority or event IDs within a timestamp.

- `env.now`: unitless simulation clock; choose and document one unit.
- `env.peek()`: next event time or infinity.
- `env.step()`: process one event; raises `EmptySchedule` when empty.

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills