Verified 2026-07-23. This guide applies established discrete-event simulation methods to SimPy models. SimPy schedules events; it does not perform these study design decisions automatically.
Before code, specify:
Robinson defines conceptual modeling as abstraction from a real or proposed system and emphasizes validity, credibility, utility, feasibility, and the simplest model adequate for purpose. Sargent frames validity relative to the intended application and domain, not as a universal property.
Use a unit table:
| Quantity | Unit | Convention |
|---|---|---|
env.now |
minutes | starts at opening |
| interarrival | minutes/entity | strictly positive |
| service | minutes | sampled at service start |
| throughput | entities/hour | convert from minute horizon |
SimPy time is unitless. Unit inconsistency can produce a perfectly executable but invalid model.
A terminating simulation has a natural, predeclared endpoint: closing time, completion of an order, end of a mission, or another event relevant to the purpose. Initial conditions are part of the estimand and should normally be identical across replications.
Decide how to handle entities still present at a fixed clock horizon:
These answer different questions. Numeric env.run(until=horizon) is half-open and
does not drain.
A nonterminating system has no natural endpoint and targets a long-run parameter. Arbitrary initialization creates transient bias. A finite warm-up deletion may reduce that bias, but neither a warm-up nor a long run proves stationarity or convergence.
Use a declared replication/deletion design:
Do not label a finite-horizon operating-day model "steady state" merely because it has many events.
Pseudo-random generation is deterministic given algorithm, state, and consumption order. Reproducibility requires recording:
Use separate local RNG objects for distinct sources:
arrival_rng = random.Random(arrival_seed)
service_rng = random.Random(service_seed)
Avoid module-global random.seed() in reusable models: unrelated code can consume
or reset the shared stream.
L'Ecuyer recommends independent streams/substreams, often one stream per stochastic source and one substream per replication. Distinct hash-derived seeds, as used by the bundled scripts, provide deterministic separation for a compact standard-library example; they do not mathematically prove stream independence. For high-stakes or large parallel experiments, use a generator/package with explicit tested stream and jump/substream facilities and document it.
For paired alternatives, intentionally using the same source-specific random numbers can reduce variance of differences. Keep replication pairs aligned and use separate source streams so a demand draw in one alternative does not become a service draw in another. Analyze paired replication differences. Common random numbers are a designed variance-reduction method, not independent streams across alternatives.
Within-run entity outcomes are usually dependent: customers share queues and system state. The basic independent unit is a complete replication using an independent stream set.
For each replication:
Law's output-analysis tutorial stresses that one run does not produce "the answer." Use at least two replications to estimate variance; practical counts should be chosen from desired precision, distribution shape, computational cost, and a pilot, not a universal magic number.
The bundled replication runner caps counts and records every derived seed. It does not automatically choose a sufficient replication count.
Given independent replication estimates X_1, ..., X_n, a common two-sided
Student-t interval for their mean is:
mean(X) +/- t_(n-1, 1-alpha/2) * s(X) / sqrt(n).
State:
Conditions and caveats:
n gives unstable variance and distribution diagnostics;Do not feed all customer waits from one run to an IID t interval. Positive serial dependence can severely understate variance. Law (2020) illustrates dramatic undercoverage from this approach.
For one long steady-state run, use a justified output-analysis method such as batch means, spectral methods, or regenerative analysis with diagnostics. The bundled CLI deliberately implements independent replications, not a naive single-run CI.
Warm-up is an estimand/study-design issue, not an Environment option. SimPy has no
automatic steady-state detector.
Good practice:
Schruben developed tests for initialization bias; Robinson and Hoad et al. developed warm-up selection procedures. No method makes every model stationary, and visual flattening is not proof.
Choose the measurement-window rule before analysis:
[warm_up, horizon).These estimate different quantities. The bundled queue scripts use completed entities whose arrival is at or after warm-up plus clipped time-weighted resource metrics, and disclose unfinished entities.
Sargent distinguishes:
Use:
Passing tests establishes implementation evidence, not real-world validity.
Use evidence appropriate to purpose:
Predeclare acceptable accuracy where possible. Validation is iterative and domain-specific; failure in a required operating condition invalidates use there.
Vary uncertain inputs, structural assumptions, warm-up, run length, capacities, queue discipline, and initial conditions over defensible ranges. Preserve paired random streams for alternative comparisons when intentionally using common random numbers.
Separate:
A replication CI addresses only the first under the configured model.
The STRESS-DES guidelines organize complete reporting around objectives, model logic, data, experimentation, implementation, and code access. At minimum retain:
Reproducibility of the program is not validity of the model.
A simulation computes implications of encoded assumptions. Changing a parameter and observing an output difference is a model-based scenario contrast, not an identified causal effect in the real system. Causal language requires defensible causal assumptions/design, calibrated interventions, and validation beyond SimPy.
Use phrasing such as:
Under the specified arrival, service, routing, and capacity assumptions, the simulated scenario produced ...
See sources.md for full dated notes.