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/real-time.md
View on GitHub# Real-time simulation
Reviewed 2026-10-01 against SimPy 4.1.2.
`simpy.rt.RealtimeEnvironment` retains the Event/Process API but delays event
processing so simulation time tracks wall-clock time.
```python
from simpy.rt import RealtimeEnvironment
env = RealtimeEnvironment(
initial_time=0,
factor=0.1,
strict=True,
)
```
## Parameters
- `initial_time`: starting simulation clock.
- `factor`: wall-clock seconds per simulation time unit; validate it as finite and
strictly positive in model code (4.1.2 does not enforce this in its constructor).
- `1.0`: one simulation unit takes one second;
- `0.1`: one simulation unit takes 0.1 seconds;
- `60.0`: one simulation unit takes one minute.
- `strict=True`: raise `RuntimeError` when processing falls more than the allotted
factor behind.
`strict=False` suppresses deadline failure. It permits drift; it does not make an
overloaded simulation accurately synchronized.
If initialization takes a long time between construction and the first `run()`,
call `env.sync()` immediately before that first run. It resets the real-time origin
without changing simulation time. It is not a general checkpoint/resume mechanism:
the mapping still uses the original `initial_time`.
## Minimal bounded example
```python
import time
from simpy.rt import RealtimeEnvironment
def ticker(env, count):
for index in range(count):
before = time.monotonic()
yield env.timeout(1)
elapsed = time.monotonic() - before
print(index, env.now, elapsed)
env = RealtimeEnvironment(factor=0.05, strict=True)
process = env.process(ticker(env, count=3))
env.run(until=process)
```
Use `time.monotonic()` for elapsed wall time. Calendar time can jump.
## Strict-mode behavior
Callbacks and generator code execute synchronously on the simulation thread. Slow
computation, blocking I/O, logging, garbage collection, OS scheduling, and loaded
CI hosts all consume the real-time budget.
```python
import time
import simpy.rt
def slow(env):
time.sleep(0.02)
yield env.timeout(1)
env = simpy.rt.RealtimeEnvironment(factor=0.01, strict=True)
env.process(slow(env))
try:
env.run()
except RuntimeError:
print("simulation missed its real-time budget")
```
This `sleep()` intentionally demonstrates a missed deadline. Do not put blocking
sleep in ordinary SimPy process logic to represent simulated delay; use
`env.timeout()`.
## Appropriate use
Real-time execution is useful when wall-clock synchronization is intrinsic:
- hardware- or software-in-the-loop tests;
- human-paced demonstrations;
- interactive controllers;
- adapters to an external system with explicit timing contracts.
It is usually inappropriate for Monte Carlo replications: normal `Environment`
runs faster, is less affected by host load, and preserves the same model-time
logic.
## External I/O boundary
SimPy itself is single-threaded and does not make external I/O asynchronous.
Integrating devices or services requires an explicit adapter and failure model.
Document:
- blocking/nonblocking behavior;
- timeout and retry policy;
- conversion between wall and simulation timestamps;
- thread-safety and event handoff;
- late/out-of-order data behavior;
- shutdown and exception propagation.
The bundled skill CLIs intentionally provide no device, network, plugin, or
external-service integration.
## Drift measurement
Choose a real origin and compare expected elapsed wall time with actual monotonic
elapsed time:
```python
import time
origin_real = time.monotonic()
origin_sim = env.now
def drift_seconds(env, factor):
expected = (env.now - origin_sim) * factor
actual = time.monotonic() - origin_real
return actual - expected
```
Define sign, sampling instant, percentile, maximum allowed lag, and platform before
testing. A mean near zero can hide large deadline misses.
## Testing strategy
1. Test model logic with normal `Environment`.
2. Test deterministic ordering and interrupts independently of wall time.
3. Keep real-time tests short and separately marked.
4. Use `time.monotonic()` and broad platform-aware bounds.
5. Test both `strict=True` deadline detection and intentional `strict=False` lag.
6. Avoid exact-duration assertions.
7. Record Python/SimPy version, OS, architecture, host load assumptions, and factor.
Example tolerant assertion:
```python
start = time.monotonic()
env = RealtimeEnvironment(factor=0.02, strict=False)
env.run(until=env.timeout(2))
elapsed = time.monotonic() - start
assert elapsed >= 0.02
assert elapsed < 1.0
```
The upper bound is deliberately generous; tune it for controlled hardware, not a
busy shared runner.
## Boundaries and stopping
Real-time environments inherit `Environment.run()` semantics:
- no `until` can run forever;
- numeric `until` excludes normal events at the boundary;
- Event `until` returns the Event value;
- `peek()`/`step()` remain available.
Always bound real-time runs. A tiny factor combined with a huge event count can
still consume substantial CPU, and a huge factor can make a short model wait for a
long wall duration.
## Limitations
- Wall-clock results are not bit-for-bit timing reproducible across hosts.
- Python/OS timer granularity and scheduling affect jitter.
- One slow callback delays all later events.
- Real-time synchronization does not make simulated processes parallel.
- `strict=False` can accumulate unbounded lag.
- Real-time agreement is not model validation.
## Sources
See `sources.md` for the 4.1.2 real-time topical guide and `simpy.rt` API.
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 |