Simulation¶

The main simulation engine that manages the event heap and runs the event loop.

Core simulation orchestrator for the discrete-event simulation engine.

This module implements the main simulation loop using a pop-invoke-push pattern: events are popped from a priority heap, invoked to perform their work, and any resulting events are pushed back for future processing.

Simulation ¶

Simulation(
    start_time: Instant | None = None,
    end_time: Instant | None = None,
    sources: list[Source] | None = None,
    entities: list[Simulatable] | None = None,
    probes: list[Source] | None = None,
    trace_recorder: TraceRecorder | None = None,
    fault_schedule: FaultSchedule | None = None,
    duration: float | None = None,
)

Orchestrates discrete-event simulation execution.

The simulation maintains a central event heap and advances time by processing events in chronological order. It supports two termination modes:

Explicit: Run until end_time is reached
Auto: Run until no primary (non-daemon) events remain, allowing probes to keep running without blocking termination

All entities share a common Clock instance, ensuring consistent time views across the simulation. Sources and probes are bootstrapped during initialization, priming the heap with their first events.

Interactive control (pause/resume, stepping, breakpoints) is available via the control property, which lazily creates a SimulationControl instance. When control is never accessed, the run loop incurs zero overhead.

Parameters:

Name	Type	Description	Default
`start_time`	`Instant \| None`	When the simulation begins. Defaults to Instant.Epoch (t=0).	`None`
`end_time`	`Instant \| None`	When to stop processing. Defaults to Instant.Infinity (auto-terminate).	`None`
`sources`	`list[Source] \| None`	Load generators that produce events at specified intervals.	`None`
`entities`	`list[Simulatable] \| None`	Simulation actors that respond to events.	`None`
`probes`	`list[Source] \| None`	Measurement sources that run as daemons (won't block termination).	`None`
`trace_recorder`	`TraceRecorder \| None`	Optional recorder for debugging/visualization.	`None`
`fault_schedule`	`FaultSchedule \| None`	Optional fault injection schedule.	`None`

control `property` ¶

control

Access the simulation control surface for interactive debugging.

Lazily creates a SimulationControl instance on first access.

trace_recorder `property` ¶

trace_recorder: TraceRecorder

Access the trace recorder for inspection after simulation.

summary `property` ¶

summary: SimulationSummary | None

Summary from the most recent run(), or None if not yet run.

schedule ¶

schedule(events: Event | list[Event]) -> None

Inject events into the simulation from outside the event loop.

Useful for adding events programmatically after initialization but before or during simulation execution.

Events scheduled before run() is called are remembered so they can be replayed on control.reset().

run ¶

run() -> SimulationSummary

Execute the simulation until termination or pause.

Implements the core pop-invoke-push loop: 1. Pop the earliest event from the heap 2. Advance simulation time to that event's timestamp 3. Invoke the event (calling its target entity or callback) 4. Push any resulting events back onto the heap 5. Repeat until termination condition is met

The method is re-entrant: calling run() on a paused simulation resumes from where it left off. When the simulation is paused (via control.pause(), control.step(), or a breakpoint), a partial SimulationSummary is returned.

Termination occurs when: - The event heap is exhausted, or - Current time exceeds end_time, or - Auto-terminate mode with no primary events remaining, or - The simulation is paused (returns partial summary)

Returns:

Type	Description
`SimulationSummary`	SimulationSummary with run statistics (partial if paused).