Event Queue

Event Queue: Concept Architecture

Orientation and learning roadmap

The page follows the event calendar that moves a discrete-event simulation through time. It explains how events are scheduled and ordered, then works through a health-care pathway in which clinical and resource events interact. The final sections show how that calendar supports economic outcomes and what must be checked when events coincide or become invalid.

Keep future events separate from waiting patients

An event queue holds scheduled changes to the simulated system, such as an arrival, test result, treatment start, recurrence, or death. Each entry identifies when a change is due and what the model should do when it occurs; the simulation clock advances to the earliest valid entry. By contrast, a patient waiting line holds people seeking a limited resource, often with its own priority or first-come-first-served rule.

A patient can be in a resource waiting queue while the event calendar also contains a future deterioration or abandonment event for that patient. The two structures answer different questions, so the implementation must keep them distinct. A scheduling decision can add, reschedule, or invalidate a future event.

Schedule and execute the next valid event

The model begins with initial events and a simulation clock $t_0$. At each step it removes the earliest valid event, advances the clock to that event's time, updates the affected state, records any outcomes, and schedules consequential events. This event-driven advance skips intervals in which the model has no scheduled change.

1. Initialise the clock, entity states, resources, random streams, and future-event list.
2. Remove the earliest valid event and advance the clock to its scheduled time.
3. Update clinical states, resource occupancy, costs, or outcomes caused by the event.
4. Schedule any resulting future events and invalidate superseded ones.
5. Stop under the prespecified horizon or other termination rule, processing events at the horizon according to the chosen boundary convention.

An illustrative event record can be represented as $(t,p,s,k,i)$, with time $t$, tie priority $p$, unique sequence number $s$, event kind $k$, and entity identifier $i$. The tuple is an implementation pattern, not a universal data standard; a priority queue or heap can retrieve the minimum ordered entry efficiently. A unique sequence number makes tied events reproducible, while clinical ordering still needs an explicit rule where it changes outcomes.

Follow an illustrative treatment pathway

Suppose a patient arrives at time 0, has a diagnostic result at day 2, begins treatment at day 5, and may later experience an adverse event or recurrence. Processing the day-2 result can update eligibility and place a treatment-start event on the calendar. If death occurs before a scheduled treatment or recurrence, the model must cancel or ignore events that no longer apply.

The day-20 entry is a possible modelled event, not a prediction for any particular patient. If the model instead schedules candidate times for competing outcomes, it must specify their joint assumptions and whether an event changes or cancels the other candidates. An event list is an execution mechanism; the underlying clinical distributions and causal structure determine whether the simulation is credible.

Accumulate costs and health over irregular intervals

Event timing matters in health economics because costs can occur at an event and health can accrue between events. A model can integrate a utility rate over each interval in a given health state and apply discounted costs or effects at the times specified by its perspective and discounting convention. This avoids treating all events as if they happened at a common cycle boundary.

For a patient whose state has utility $u_j$ over consecutive intervals $[t_j,t_{j+1})$, an illustrative undiscounted calculation is

$$\mathrm{QALYs}=\sum_j u_j\,\frac{t_{j+1}-t_j}{365.25},$$

when simulation time is measured in days and the year-length convention is 365.25 days. If utility is 0.8 for 100 days, that interval contributes $0.8(100/365.25)\approx 0.2190$ QALYs. Discounting, changing utility within an interval, and terminal events require corresponding adjustments; use the same convention across compared strategies.

Resolve simultaneous events and stale entries

Two events can have the same scheduled time even in a continuous-time model because of fixed appointments, rounded times, or generated dependencies. Arbitrary processing order may change a patient's state, resource availability, or recorded cost, so prespecify whether, for example, a death at a given instant takes precedence over a treatment event at that instant. Stable insertion order is reproducible, but it is not automatically the clinically appropriate ordering.

Rescheduling can leave a stale event in a heap unless the implementation removes it or checks a validity flag when it is reached. The model should also reject attempts to schedule an event in the past and guard against an unbounded chain of zero-time events. These rules matter for both numerical correctness and a traceable account of why an event occurred.

Verify the event calendar and its outputs

Verification tests whether the coded queue follows the intended event logic, while validation asks whether the model represents the clinical and operational setting adequately. Inspect small deterministic traces before relying on stochastic results; a trace should show time, event type, entity, state before and after, and any newly scheduled or invalidated events. Compare simulated flow and resource use with appropriate observed or expected patterns where data permit.

• Confirm that processed event times never move backward and that no valid scheduled event is silently lost.
• Test simultaneous events, terminal events, cancellation, horizon boundaries, and zero-duration transitions with explicit expected traces.
• Reconcile resource occupancy, patient counts, and accumulated costs and QALYs with event logs in a small example.
• Check whether a patient's resource-waiting priority changes access while the event calendar remains time ordered.
• Run sensitivity and uncertainty analyses on the event-time inputs and consequential clinical or economic outputs.

Sources and technical basis

SimPy's developer documentation describes time ordering and deterministic tie handling for an event calendar. The simmer methods publication explains the event list and event loop, while its resource documentation describes the separate waiting line. A health-economic tutorial demonstrates how discrete-event simulation can represent clinical pathways and model costs and outcomes.

• SimPy, Time and Scheduling.
• simmer, Discrete-Event Simulation for R, technical article.
• simmer, Add a Resource documentation.
• Degeling and colleagues, Discrete Event Simulation in R using the simmer Package for Health Economic Modelling.