Bundled CLI guide

Reviewed 2026-10-01 for skill version 1.6 and SimPy 4.1.2.

The scripts implement one transparent finite-horizon exponential arrival/exponential service multi-server queue. They are examples and diagnostics, not a generic model execution platform.

Safety contract

All scripts:

• use only SimPy and the Python standard library;
• build --help when SimPy is absent, so options remain inspectable before installation;
• make no network or external-service calls;
• accept only local regular files with fixed suffixes;
• reject URLs, symlinks, duplicate JSON keys, NaN/infinity, unknown keys, and oversized inputs;
• never evaluate configuration text, run user Python, resolve callables, or import plugins;
• enforce time, event, entity, queue, trace, and replication caps;
• emit strict deterministic JSON (allow_nan=False);
• write explicit outputs atomically with mode 0600;
• refuse overwrite unless --force is supplied.

Run from the repository root after the pinned install:

uv pip install "simpy==4.1.2"

Commands that execute a simulation gate SimPy through a shared dependency loader. If it is absent, they exit without a traceback and print the pinned installation command above. They also reject a different installed version because scheduler instrumentation is release-specific. Configuration validation and artifact summarization remain usable without SimPy.

Queue configuration schema

Every field is optional; defaults are shown:

{
  "analysis_mode": "terminating",
  "base_seed": 20260723,
  "horizon": 480.0,
  "max_entities": 10000,
  "max_events": 200000,
  "mean_interarrival": 4.0,
  "mean_service": 6.0,
  "queue_capacity": 20,
  "servers": 2,
  "warm_up": 0.0
}

Semantics:

• arrival and service durations are exponential means in the declared model time unit;
• there are servers simultaneous slots and at most queue_capacity waiting entities;
• an arrival seeing servers + queue_capacity admitted entities is rejected;
• arrivals and services use separate deterministic stream seeds;
• arrivals occur strictly before horizon;
• numeric horizon excludes ordinary events exactly at that time;
• completed-customer metrics exclude unfinished entities and disclose their count.

Bounds:

• 0 < horizon <= 1,000,000;
• 1 <= servers <= 10,000;
• 0 <= queue_capacity <= 100,000;
• positive finite means no greater than 1,000,000;
• 1 <= max_entities <= 100,000;
• 10 <= max_events <= 1,000,000;
• base seed from 0 through 2^63 - 1.

For analysis_mode="terminating", warm_up must be zero. For analysis_mode="steady_state", warm-up must be positive and less than horizon. This validates consistency only; it does not establish that steady state was reached.

Report schema 1.2 separates the measurement rules:

• window_arrivals and window_rejected count events in [warm_up, horizon); loss_probability is their ratio (null when there are no window arrivals).
• window_departures counts all completions in that time window, including customers arriving before warm-up; throughput divides this by horizon - warm_up.
• observed_completed and customer means use customers arriving at/after warm-up and completed before the horizon; unfinished customer paths are excluded.
• Queue length and utilization are time-weighted over [warm_up, horizon).
• The original arrivals/admitted/rejected/completed counters span the full run.
• event_processing.processed includes the step whose callback stops the run.

These synthetic exponential inputs demonstrate event mechanics; they are not calibrated estimates of a real queue. Record the time unit and justify inputs before using scenario contrasts. The report records simpy_version and metric_windows.

Basic template

python skills/simpy/scripts/basic_simulation_template.py --help
python skills/simpy/scripts/basic_simulation_template.py
python skills/simpy/scripts/basic_simulation_template.py \
  --config queue.json --output run.json

--replication INDEX selects deterministic derived arrival/service seeds. It does not itself create a confidence interval.

Library use:

from basic_simulation_template import QueueConfig, run_simulation

config = QueueConfig.from_mapping({"horizon": 120, "servers": 3})
report = run_simulation(config, replication=0)

Bounded queue scenario and trace

python skills/simpy/scripts/bounded_queue_scenario.py \
  --config queue.json \
  --output scenario.json \
  --trace-output trace.jsonl \
  --trace-max-records 50000

The trace is capped and contains no event repr:

{
  "event_id": 0,
  "event_type": "Initialize",
  "priority": 0,
  "queue_size_before": 1,
  "time": 0.0
}

The .jsonl file has one compact object per line. A trace can truncate while the bounded simulation completes; the report discloses trace.truncated.

Replication configuration schema

{
  "confidence": 0.95,
  "model": {
    "analysis_mode": "terminating",
    "base_seed": 20260723,
    "horizon": 480,
    "max_entities": 10000,
    "max_events": 200000,
    "mean_interarrival": 4,
    "mean_service": 6,
    "queue_capacity": 20,
    "servers": 2,
    "warm_up": 0
  },
  "replications": 20
}

Additional experiment bounds:

• 2-1,000 replications; one-run confidence intervals are rejected;
• confidence strictly greater than 0.50 and at most 0.999;
• replications * max_events <= 5,000,000;
• replications * max_entities <= 2,000,000.

python skills/simpy/scripts/replication_runner.py --help
python skills/simpy/scripts/replication_runner.py \
  --config experiment.json --output intervals.json

The runner makes a two-sided Student-t interval from independent replication-level estimates. A metric undefined in any run is marked unavailable instead of dropping that run. It never constructs a CI from individual customers within one run.

The seed manifest uses stable BLAKE2b derivation for separate arrival/service RNG objects. This is deterministic stream separation for the bundled example, not a formal proof of independent substreams. See simulation-methodology.md.

Configuration validator

Validation performs no simulation:

python skills/simpy/scripts/validate_simulation_config.py queue.json
python skills/simpy/scripts/validate_simulation_config.py \
  experiment.json --schema replication

Schemas are queue, replication, or auto. Auto identifies the replication schema by any top-level model, replications, or confidence key. There are no custom model names, module paths, class names, predicates, or callable fields.

Unknown keys such as the following are rejected:

{
  "plugin": "package.module",
  "python": "print('run me')"
}

Event/resource artifact summarizer

Summarize a trace without importing or executing its originating model:

python skills/simpy/scripts/event_trace_summary.py trace.jsonl

Generate the separate, fixed ResourceMonitor demonstration and its CSV, then summarize it (--samples is an output path, not an input):

python skills/simpy/scripts/resource_monitor.py \
  --samples resource.csv --output monitor.json
python skills/simpy/scripts/event_trace_summary.py resource.csv

Accepted trace fields are exactly:

event_id, event_type, priority, queue_size_before, time.

Accepted resource CSV fields are exactly:

time, event, count, queue_length, utilization.

The summarizer reports decreasing event times and computes resource time averages by carrying each post-transition state forward to the next sample. Same-time priority/event-ID decreases are valid when callbacks insert new urgent events; the processing trace alone cannot prove scheduler heap ordering. It does not infer queue semantics from arbitrary column names.

The replication runner consumes the replication JSON configuration and runs fresh model instances. It does not consume trace.jsonl or resource.csv. Each run provides one estimate per metric; the Student-t interval is across those estimates, not a separate confidence interval for each run.

Resource monitor library

from resource_monitor import EventTraceRecorder, ResourceMonitor

monitor = ResourceMonitor(env, server, "server")
trace = EventTraceRecorder(env, max_records=10_000)
env.run(until=100)
trace.detach()
monitor.finalize(at=100)

print(monitor.summary(start=20, end=100))
monitor.export_csv("resource.csv")
trace.export_jsonl("trace.jsonl")

The monitor patches one resource instance. Do not attach multiple wrappers to the same resource. Its queue timing and private-API caveats are in monitoring.md.

Exit behavior

Expected validation failures use argparse errors and nonzero exit status:

• malformed/unknown config;
• unsafe path or overwrite;
• event/entity/replication budget violation;
• event limit reached during the run;
• invalid trace/resource artifact.

An event-budget error is a failed/incomplete simulation, not a valid censored result. Increase a cap only after diagnosing why it was reached.

Exact pinned tests

PYTHONDONTWRITEBYTECODE=1 uv run --isolated --no-project \
  --python 3.13 --with "simpy==4.1.2" --with pytest \
  python -m pytest tests/simpy -q

Tests cover scheduler boundaries, deterministic ties, Conditions, all resource families, preemption causes, monitor time weighting, trace round-trip, config/path safety, hard limits, seed determinism, and Student-t calculations.