AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

simpy

Builds, 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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--simpy at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/real-time.md

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.

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

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.

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:

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:

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.