How to Simulate a Single-Server Queue with SimPy: Discrete-Event Simulation Tutorial

Table of contents

• Scientific introduction
• Test progress
• Prerequisites and validated installation
• Demo user request
• Demo data
• Workflow and implementation logic
• Results and artifacts
• Interpretation and practical use
• Failures, repairs, and alternatives
• Reproducibility
• Limitations
• References
• Try this workflow

Four customers arriving at times 0, 1, 2, and 3 to one server, with deterministic two-time-unit service, produce waits of 0, 1, 2, and 3 time units. A real SimPy 4.1.1 execution therefore measured a mean wait of 1.5, a maximum wait of 3, and final completion at simulation time 8. These values passed native execution, chat-driven execution, CSV-schema checks, and independent semantic validation. This small deterministic case is useful because every event can be audited by hand while still exercising SimPy's actual environment, process, resource-request, and timeout machinery.

Scientific introduction

Discrete-event simulation (DES) represents a system as state changes occurring at distinct event times. Unlike fixed-step simulation, a DES engine advances its clock directly to the next scheduled event. This is efficient for queues, laboratories, factories, clinical pathways, communication networks, and transport systems in which long quiet intervals separate arrivals, departures, failures, or repairs. The foundational event-scheduling worldview and its statistical requirements are described in Law's simulation text and in the official SimPy documentation.

A queueing model separates an arrival process, a service mechanism, a queue discipline, and a resource capacity. Here the arrivals and service durations are deliberately deterministic. The notation resembles a D/D/1 queue: deterministic interarrival pattern, deterministic service, and one server. The four specified arrival times are an explicit finite schedule rather than a stationary stochastic process. Consequently, this demonstration estimates no steady-state distribution and makes no general claim about long-run performance. Its purpose is functional verification and transparent reasoning about event order.

SimPy models active components as Python generator processes. A process yields events to an Environment; the environment resumes it when those events trigger. Resource(capacity=1) represents the server. A customer records its arrival, yields a resource request, begins service when that request succeeds, and yields env.timeout(2) to represent service. Releasing the request lets the next queued customer start. These are not decorative API calls: the retained test requires them and rejects a precomputed substitute table.

Event ordering matters when two events share a timestamp. At time 2, for example, customer 1 completes just as customer 3 arrives. A reproducible model must state its scheduling semantics and should not infer causality from row ordering alone. In this case, the observable service schedule is unambiguous: customer 1 occupies [0,2], customer 2 [2,4], customer 3 [4,6], and customer 4 [6,8]. Waiting time is service_start - arrival, while time in system would additionally include service duration.

Verification asks whether the program correctly implements the intended conceptual model; validation asks whether that conceptual model adequately represents the real system. The deterministic queue is strongly verifiable because all expected timestamps have closed-form values. It is not validated as a model of any particular clinic, instrument, or facility because no empirical arrival or service data were supplied. This distinction prevents a successful software test from becoming an unsupported operational recommendation.

Stochastic production studies need substantially more work. Analysts should select distributions from evidence, run independent replications, manage random-number seeds, define warm-up deletion for non-terminating systems, inspect autocorrelation, and report confidence intervals. Rare congestion may require variance reduction or longer horizons. Sensitivity analysis should vary arrival intensity, service variability, priority rules, downtime, balking, reneging, and capacity. A single deterministic trajectory has zero sampling uncertainty only because randomness was intentionally excluded; that does not mean the corresponding real-world performance is certain.

DES can reveal nonlinear congestion. If arrivals approach service capacity, small changes in workload or variability can cause disproportionately large waits. Yet a model remains conditional on its assumptions. A server may represent a person, sequencer, microscope, compute node, or sample-preparation station, but each interpretation changes scheduling, failure, setup, batching, and priority rules. Results should therefore be accompanied by an explicit model boundary and an event trace, not just a headline average.

Test progress

The validated attempt is attempt 3. No GPU, CUDA runtime, network service, or large model was required. The package remained installed in the retained environment under the testing policy, allowing later repair or reproduction without repeating installation.

Prerequisites and validated installation

The execution requires Python and SimPy. The environment used SimPy 4.1.1 on Linux x86_64 CPU. The transparent reproduction path is:

python -m pip install "simpy==4.1.1"
python native_demo.py --output-dir outputs

Pinning the version narrows environmental variation. A production project should additionally lock Python and transitive dependencies, archive the input specification, and record the executing script checksum. Installation success alone receives no scientific credit; the test only passes after the package executes the requested model and artifacts satisfy semantic checks.

Demo user request

Use the installed SimPy skill and its retained environment to simulate four customers arriving at times 0, 1, 2, and 3 to one capacity-one server. Every service takes exactly two time units. Run a real simpy.Environment, simpy.Resource, processes, requests, and timeouts. Create outputs/simpy-events.csv with customer, arrival, service_start, departure, and wait, plus outputs/simpy-summary.json with version, customer count, capacity, service time, average and maximum wait, and final completion time. Do not calculate a substitute table without executing SimPy.

This wording intentionally specifies both the scientific model and the evidence contract. It prevents an agent from answering with generic queueing prose or silently calculating the known values without invoking SimPy.

Demo data

The input is synthetic and repository-authored for deterministic verification. Its provenance and limitations are documented in data/README.md. Time is expressed in abstract simulation units, so the results can be read as seconds, minutes, or hours only after a user supplies a domain mapping. Customer identifiers are labels, not human-subject data.

The dataset is deliberately tiny. It detects queue-order errors, incorrect resource capacity, missing waits, and mistaken final-clock calculations, but it cannot test random variates, priorities, preemption, interrupts, failures, reneging, or confidence intervals.

Workflow and implementation logic

The workflow first parses the requested arrivals and constants, then constructs one environment and one capacity-one resource. It registers one generator process per customer. Each process waits until its arrival time, requests the resource, records the grant time, yields a two-unit timeout, records departure, and releases the resource. After env.run(), the script writes rows in customer order and derives summary statistics from those rows.

The validator reads rather than trusts the report. It checks that four rows exist, required columns are present, starts are 0/2/4/6, departures are 2/4/6/8, and waits are 0/1/2/3. It also checks package version, count, capacity, service time, mean, maximum, and final time in JSON. This makes the CSV the event-level evidence and the JSON a derived view. Agreement between them catches transcription and aggregation mistakes.

Results and artifacts

The primary result is a mean wait of 1.5 simulation time units. Maximum wait is 3 units, and all work completes at time 8. There is no statistical uncertainty because the scenario contains no random variables; these numbers are exact for the stated finite schedule, not estimates of a population mean.

The event trace is retained as simpy-events.csv, the machine-readable summary as simpy-summary.json, and the readable audit report as results-report.md.

The focused application capture presents the result report rather than a file list or raw JSON editor. It establishes that the chat-driven workflow surfaced the validated scientific deliverable.

The table view exposes the causal chronology. Since one two-unit service begins every two units while customers arrive every one unit, the queue grows and waits increase linearly over this short horizon.

The inventory confirms that both structured artifacts and the human-readable report were retained. Artifact presence alone was insufficient: semantic validation had to pass.

Interpretation and practical use

Customer 1 begins immediately because the resource is idle. Customer 2 arrives while customer 1 is in service and waits one unit. Customer 3 arrives at the first completion timestamp but customer 2 already holds queue precedence, so customer 3 waits two units. Customer 4 waits three. The arithmetic mean (0+1+2+3)/4 is 1.5, and the last two-unit service finishes at 8.

For operational decisions, the next useful experiment would vary interarrival and service distributions and compare capacities. One might record utilization, time-weighted queue length, percentile wait, probability of missing a service-level threshold, and costs. A warm-up period may be needed for a continuing system, whereas a terminating daily clinic should use a meaningful opening state and multiple replicated days. Model calibration should compare simulated and observed interarrival, service, and queue-length distributions.

Failures, repairs, and alternatives

The decisive safeguard was requiring package-specific execution. A script that merely emitted the expected numbers would be a false test because it would not exercise SimPy scheduling. The final contract explicitly names Environment, Resource, generator processes, resource requests, and timeouts, and the retained native demonstration imports and runs the installed package.

If installation from the default package index fails, a vetted mirror or a previously downloaded wheel may be used while preserving hashes and version metadata. If Python compatibility fails, a scoped environment with a supported interpreter is preferable to modifying the system interpreter. These alternatives must still run the same scientific case. Spreadsheet calculation, hand-coded event loops, and mocked SimPy modules are not acceptable substitutes for this package validation.

Reproducibility

The run used attempt 3, Linux on x86_64, CPU execution, Python with SimPy 4.1.1, and validation completed in July 2026. Inputs, source scripts, prompt, CSV, JSON, report, image manifests, and checksums are retained in the dossier. The screenshot manifest attributes captures to Playwright on the chat route with focused locators; the visual-asset manifest links images back to source artifacts.

Reproduction should preserve row ordering and numeric types but need not rely on screenshots. The authoritative evidence is the structured output plus semantic checks. Screenshots make review convenient; they are not a replacement for machine-readable provenance.

Limitations

This test covers one deterministic, non-preemptive, first-come-first-served, capacity-one resource. It does not validate stochastic distributions, seeded replication, priorities, reneging, interruptions, preemption, stores, containers, real-time simulation, or distributed execution. It makes no claim about performance at large event counts. It also does not validate any real queue because no empirical observations were fitted.

The average wait should never be transferred to another workload. Changing one arrival, service time, discipline, or capacity changes the trajectory. The absence of uncertainty is a property of the deterministic input, not confidence in a real operational system. Domain use requires subject-matter review, data-quality assessment, calibration, validation, sensitivity analysis, and decision-appropriate uncertainty reporting.

References

1. SimPy Project. SimPy documentation: process-based discrete-event simulation framework.
2. SimPy Project. Resources: shared-resource modeling and requests.
3. Banks J, Carson JS, Nelson BL, Nicol DM. Discrete-Event System Simulation.
4. Law AM. Simulation Modeling and Analysis.
5. Kendall DG. Stochastic processes occurring in the theory of queues and their analysis by the method of the imbedded Markov chain.

Try this workflow

MindPlot has built-in support for the demonstrated SimPy skill. A user can describe the queue in ordinary language; the MindPlot agent writes and runs the package-specific code, retains the CSV and JSON, and presents the results, so users do not need to write the reproduction code themselves. Try it at https://mindplot.ai, or download the desktop version for a better integrated experience and stronger local-data privacy.