Entity¶

Base class for stateful simulation actors. Override handle_event() to define behavior.

Base class for simulation actors that respond to events.

Entities are the building blocks of a simulation model. Each entity receives events via handle_event() and returns reactions (new events or generators).

SimYield `module-attribute` ¶

SimYield = Union[
    float,
    tuple[float, list[Event] | Event | None],
    "SimFuture",
]

Type alias for generator yield values: delay, (delay, side_effects), or SimFuture.

SimReturn `module-attribute` ¶

SimReturn = list[Event] | Event | None

Type alias for generator return values: events to schedule on completion.

Entity ¶

Entity(name: str)

Bases: ABC

Abstract base class for all simulation actors.

Entities receive events through handle_event() and produce reactions. They maintain a reference to the simulation clock for time-aware logic.

The simulation injects the clock during initialization, so entities should not be used outside a simulation context.

Subclasses must implement handle_event() to define their behavior. Optionally override has_capacity() to model resource constraints.

Attributes:

Name	Type	Description
`name`		Identifier for logging and debugging.

now `property` ¶

now: Instant

Current simulation time from the injected clock.

Raises:

Type	Description
`RuntimeError`	If accessed before clock injection.

set_clock ¶

set_clock(clock: Clock) -> None

Inject the simulation clock. Called automatically during setup.

handle_event `abstractmethod` ¶

handle_event(
    event: Event,
) -> Union[
    Generator[SimYield, None, SimReturn],
    list[Event],
    Event,
    None,
]

Process an incoming event and return any resulting events.

Returns:

Name	Type	Description
`Generator`	`Union[Generator[SimYield, None, SimReturn], list[Event], Event, None]`	For multi-step processes. Yield delays; optionally return events on completion.
	`Union[Generator[SimYield, None, SimReturn], list[Event], Event, None]`	list[Event] \| Event \| None: For immediate, single-step responses.

forward ¶

forward(
    event: Event,
    target: Entity,
    event_type: str | None = None,
) -> Event

Create a forwarding event that preserves the original event's context.

This method only creates the event — it does not schedule it. The caller must include the returned event in their return value (e.g., return [self.forward(event, downstream)]) for the simulation loop to schedule it.

Parameters:

Name	Type	Description	Default
`event`	`Event`	The original event whose context to preserve.	required
`target`	`Entity`	The downstream entity to receive the new event.	required
`event_type`	`str \| None`	Override the event type (default: keep original).	`None`

Returns:

Type	Description
`Event`	A new Event at the current time with the same context, targeted
`Event`	at the given downstream entity.

has_capacity ¶

has_capacity() -> bool

Check if this entity can accept additional work.

Override in subclasses with concurrency limits, rate limits, or other resource constraints. Returns True by default.

downstream_entities ¶

downstream_entities() -> list[Entity]

Return downstream entities for topology discovery.

The visual debugger calls this method to build the entity graph. Subclasses that hold references to other entities should override this and return all referenced entities so that edges appear in the topology view.

The base implementation returns an empty list, which is correct for leaf entities (sinks, counters, resources) that have no downstream connections.