K-Dense-AI/scientific-agent-skills / skills/simpy
simpy
VerifiedBuilds, inspects, tests, and analyzes bounded process-based discrete-event simulations with SimPy. Use for event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up, and reproducible output analysis.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.1 KB |
| references/cli-guide.md | markdown | 9.3 KB |
| references/events.md | markdown | 7.5 KB |
| references/monitoring.md | markdown | 8.8 KB |
| references/process-interaction.md | markdown | 7.5 KB |
| references/real-time.md | markdown | 5.4 KB |
| references/resources.md | markdown | 8.6 KB |
| references/simulation-methodology.md | markdown | 11.7 KB |
| references/sources.md | markdown | 12.7 KB |
| scripts/_common.py | script | 15.0 KB |
| scripts/basic_simulation_template.py | script | 14.1 KB |
| scripts/bounded_queue_scenario.py | script | 3.5 KB |
| scripts/event_trace_summary.py | script | 10.9 KB |
| scripts/replication_runner.py | script | 6.3 KB |
| scripts/resource_monitor.py | script | 16.3 KB |
| scripts/validate_simulation_config.py | script | 3.6 KB |
references/resources.md
View on GitHub# Shared resources
Reviewed 2026-10-01 against SimPy 4.1.2.
All resource operations return Events. An operation that cannot complete waits in
the corresponding queue; yielding the Event suspends the process. Resource events
are context managers so exception/interrupt unwinding can release an acquired
request or cancel a pending operation.
## Choose by modeled quantity
| Primitive | Modeled state | Waiting operation |
|---|---|---|
| `Resource` | limited concurrent users | `request()` |
| `PriorityResource` | users plus priority queue | `request(priority=...)` |
| `PreemptiveResource` | priority users that may be displaced | `request(..., preempt=...)` |
| `Container` | homogeneous numeric level | `put(amount)`, `get(amount)` |
| `Store` | FIFO concrete objects | `put(item)`, `get()` |
| `FilterStore` | objects selected by predicate | `get(filter)` |
| `PriorityStore` | comparable/priority-wrapped objects | `put(item)`, `get()` |
These primitives implement synchronization and congestion. They do not decide
whether a queue discipline or capacity assumption is valid for the real system.
## Resource
`Resource(env, capacity=1)` is semaphore-like. `capacity` must be positive.
Observable state:
- `count`: allocated slots;
- `users`: granted request events;
- `queue`: pending request events;
- `capacity`: maximum simultaneous users.
```python
import simpy
def user(env, resource, duration):
with resource.request() as request:
yield request
yield env.timeout(duration)
env = simpy.Environment()
server = simpy.Resource(env, capacity=2)
for duration in (2, 3, 4):
env.process(user(env, server, duration))
env.run()
```
The context manager calls `release(request)` after an acquired request and
`cancel()` for an abandoned pending request. With manual management, always release
the exact request token:
```python
request = resource.request()
try:
yield request
yield env.timeout(2)
finally:
if request in resource.users:
resource.release(request)
elif not request.triggered:
request.cancel()
```
`release()` succeeds immediately, even if passed a request that is not a current
user; such a call does not make the model logically correct. Prefer the context
manager.
## PriorityResource
`PriorityResource` orders pending `PriorityRequest`s by smaller numeric priority,
then request time, then `not preempt` (preempting first). Exact key ties retain
insertion order in the stable sorted queue. `PriorityResource` itself never
preempts current users; the shared request key still includes the flag.
```python
def prioritized(env, resource, name, priority):
with resource.request(priority=priority) as request:
yield request
print(name, "started", env.now)
yield env.timeout(2)
env = simpy.Environment()
resource = simpy.PriorityResource(env, capacity=1)
env.process(prioritized(env, resource, "routine", 10))
env.process(prioritized(env, resource, "urgent", 0))
env.run()
```
Priority does not preempt a current user. A later high-priority request only
overtakes queued lower-priority requests.
## PreemptiveResource
`PreemptiveResource` extends `PriorityResource`. A request accepts:
- `priority`: lower number means higher priority;
- `preempt=True`: permit displacement of a lower-priority current user.
```python
def task(env, resource, name, priority, duration):
with resource.request(priority=priority, preempt=True) as request:
try:
yield request
started = env.now
yield env.timeout(duration)
except simpy.Interrupt as interrupt:
cause = interrupt.cause
used = env.now - cause.usage_since
print(name, "preempted by", cause.by.name, "after", used)
env = simpy.Environment()
cpu = simpy.PreemptiveResource(env, capacity=1)
env.process(task(env, cpu, "background", 5, 10))
def urgent(env):
yield env.timeout(2)
yield env.process(task(env, cpu, "urgent", 0, 1))
env.process(urgent(env))
env.run()
```
The preempted process receives `simpy.Interrupt`. Its `cause` is
`simpy.resources.resource.Preempted`:
- `cause.by`: Process that made the preempting request;
- `cause.usage_since`: time the displaced request began using the resource;
- `cause.resource`: resource involved.
The timeout representing interrupted work is not canceled; the process's callback
is removed from it. Track completed work and schedule a new timeout to resume.
Priority outranks the preempt flag. A queued request with higher priority and
`preempt=False` can prevent a lower-priority preempting request from displacing a
user. Do not mix policies without a tested discipline specification.
## Container
`Container(env, capacity=float("inf"), init=0)` models homogeneous matter. Current
state is `level`.
- `put(amount)` waits until `level + amount <= capacity`;
- `get(amount)` waits until `level >= amount`;
- amounts must be strictly positive;
- `0 <= init <= capacity`.
```python
env = simpy.Environment()
tank = simpy.Container(env, capacity=100, init=40)
def transfer(env):
yield tank.put(30)
assert tank.level == 70
yield tank.get(20)
assert tank.level == 50
env.process(transfer(env))
env.run()
```
Pending operations are visible through `put_queue` and `get_queue`. A blocked put
or get can deadlock the model if no future process can change the level. Bound
execution and assert conservation:
`initial + completed_puts - completed_gets == final_level`.
## Store
`Store(env, capacity=float("inf"))` holds concrete Python objects. `put(item)` waits
when full; `get()` waits when empty. Available objects are in `items`; pending
operations are in `put_queue` and `get_queue`.
```python
env = simpy.Environment()
buffer = simpy.Store(env, capacity=2)
def producer(env):
for item in ("a", "b", "c"):
yield buffer.put(item)
def consumer(env):
for _ in range(3):
item = yield buffer.get()
print(item)
env.process(producer(env))
env.process(consumer(env))
env.run()
```
Store is FIFO for available items and ordinary pending requests.
## FilterStore
`FilterStore.get(predicate)` takes the first available item for which the predicate
returns truthy:
```python
env = simpy.Environment()
machines = simpy.FilterStore(env, capacity=2)
machines.items = [
{"id": "small", "size": 1},
{"id": "large", "size": 2},
]
def borrow_large(env):
machine = yield machines.get(lambda item: item["size"] >= 2)
yield env.timeout(1)
yield machines.put(machine)
env.process(borrow_large(env))
env.run()
```
Unlike a plain FIFO get queue, a later FilterStore request can complete before an
earlier request when only the later predicate matches. Predicates execute inside
resource processing: keep them deterministic, fast, side-effect-free, and defined
in trusted model code. The bundled JSON CLIs do not accept predicate code.
## PriorityStore
`PriorityStore` returns the smallest item according to comparison. Prefer
`simpy.PriorityItem(priority, item)` so payloads need not be comparable:
```python
env = simpy.Environment()
work = simpy.PriorityStore(env)
def schedule(env):
yield work.put(simpy.PriorityItem(10, "routine"))
yield work.put(simpy.PriorityItem(1, "urgent"))
first = yield work.get()
assert first.item == "urgent"
env.process(schedule(env))
env.run()
```
Equal-priority `PriorityItem` objects do not guarantee FIFO order: the heap compares
priorities without a stable insertion tie-breaker. If policy requires FIFO ties,
use `simpy.PriorityItem((priority, sequence_number), payload)` with a unique
monotonically increasing sequence number and test it. PriorityStore's `items` is a
heap, not a fully sorted list; retrieve through `get()`.
## Waiting, cancellation, and reneging
Use a condition to race a request against patience:
```python
def customer(env, resource, patience):
with resource.request() as request:
result = yield request | env.timeout(patience)
if request not in result:
return "reneged" # Pending request canceled on context exit.
yield env.timeout(2)
return "served"
```
If retaining resource events outside a context manager:
- re-yield after a temporary interrupt if still waiting;
- call `cancel()` when permanently abandoning a pending put/get/request;
- release only an acquired Resource request;
- account for losing timeouts that remain in the event queue.
## Monitoring caveat
Resource state may change synchronously when an operation is created and again when
its callbacks are processed. Label whether a sample is pre-call, post-call, grant,
release, or final. Time-weight state paths; do not average event samples. See
`monitoring.md`.
## Sources
See `sources.md` for the 4.1.2 shared-resource guide and API reference.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |