Events & traces API

Base of all events. t and seq are stamped by :meth:Environment.emit.

Bases: Event

An event that is part of the trajectory. ordinal is stamped while the projection is active.

Bases: Event

An event emitted for observers (logging, KPI samples); it never carries deltas.

Synchronous event delivery with nested emissions queued FIFO.

probe, when given, is called before and after each handler and returns the number of scheduled SimPy events and the number of RNG draws; a change in either means the handler scheduled a SimPy event or drew from env.rng, which raises RuntimeError (debug mode).

delivering: bool

publish(event: Event) -> None

subscribe(
    handler: Handler,
    types: tuple[type[Event], ...] | Literal["*", "**"],
) -> Subscription

wants(cls: type[Event]) -> bool

wants_log(priority: int) -> bool

A handle returned by :meth:EventBus.subscribe.

cancel() -> None

An immutable sequence of delta operations (see the module docstring for their shapes).

Accumulates delta operations; values are frozen into wire values as they are added.

Bases: ObserverEvent

One sample of a KPI series; scope is the id of the owner entity.

Mixin for components with an identity in their environment.

Subclasses declare kind=... in the class statement and a state_schema class attribute, and call env.entities.attach(self, ...) in their constructor once the state fields exist. Subclasses without kind inherit their parent's kind. :meth:snapshot returns the current state.

The entities of one environment: ids, live entities and lifecycle events.

Ids are unique across kinds. Live entities are held strongly in attachment order; retired ones only weakly, and their ids are never reused.

attach(
    obj: Entity,
    *,
    name: str | None = None,
    label: str | None = None,
) -> str

bind_node(node: Node) -> NodeBinding

check_lifecycle_op(op: Op) -> None

get(entity_id: str) -> Entity

is_live(obj: Entity) -> bool

is_named(entity_id: str) -> bool

kind_of(entity_id: str) -> str | None

live() -> tuple[Entity, ...]

node_binding(node: Node) -> NodeBinding | None

retire(obj: Entity) -> None

snapshot(
    *, include_presentation: bool = True
) -> dict[str, dict[str, Wire]]

Bases: Mapping[str, FieldSpec]

The state fields of an entity kind, in declaration order.

Field names are non-empty strings that do not start with $ ("$kind" is reserved in state maps).

Declaration of one entity state field.

wire_type is one of str, int, float, bool, array, map or any; for a collection field (collection "list" or "map") it is the type of the items. Presentation fields are excluded from the semantic projection.

Bases: Protocol[T_co]

A description of a random variate that builds samplers drawing from a given stream.

BLAKE2b-256 digest of the semantic projection of a run.

It is fed with the initial-state projection at activation and then with the projection of every domain event (see :class:DigestAccumulator). Create it with :meth:attach, before activation.

Events are encoded on a fast path that packs the precomputed canonical field order of each event class (:attr:~simulatte.events.Event.wire_semantic) and frozen values directly; it yields the bytes of :func:project_event with the rolled kind map. When an event has no presentation payload field and the projection keeps its operations unchanged, the encoded payload, deltas tail equals what a trace recorder stores for the event, and :meth:shared_tail hands it over so full recording encodes each event once.

Comparable summary of a run: the semantic digest (None when none is enabled) and the KPI scalars.

kpis maps "<scope id>/<kpi name>" to the scalar, so two systems sharing an environment never merge their results (spec §12.1). kpi.sample events are observer events: they never enter the digest.

Hashes that identify what a run was made of; each is a hash string or :data:UNAVAILABLE.

The manifest of a run: the requested part and, once a run finished, the final part.

complete: bool

merged() -> FrozenMap

Record the run of env to a trace file at path (spec §11).

Attach it before activation (it raises RuntimeError afterwards). It enables the semantic digest of env, writes the header immediately, records prelude events and, at activation, the initial state. At level="full" it records every domain event in chunks; at level="kpi" only the header, the initial state, KPI records and the footer. At both levels it records kpi.sample events (the KPI series) in KPI records. Several :meth:Environment.run calls continue the same trace.

:meth:close (also called by :meth:Environment.close) seals the open chunk, writes the remaining KPI samples, the KPI scalars and the footer, and waits until everything is on disk. clock is the time source of the latency limit and of the blocked time reported when backpressure stops the simulation.

close(
    outcome: Outcome | None = None,
    *,
    termination: str | None = None,
) -> None

wait_committed() -> None

When the open buffer of events is sealed into a record.

A buffer is sealed when it holds max_events events or max_bytes encoded bytes (a single larger event makes a chunk of its own), when it has been open for max_latency_s seconds of the recorder clock, or, when max_sim_window is set, before an event whose simulated time is that far from the buffer's first event. An event above max_event_bytes is recorded with a warning, or raises in debug mode.

A trace file opened for reading; create it with :meth:open.

The reader keeps the file closed between calls and reads chunks on demand, caching the last few.

catalog: Mapping[str, CatalogEntry]

cursor_range: tuple[Cursor, Cursor] | None

execution: FrozenMap | None

fingerprint: Fingerprint | None

index: tuple[ChunkInfo, ...]

kpi_declarations: FrozenMap

kpi_series_display: FrozenMap

layout

level: str

manifest: FrozenMap

manifest_final: bool

outcome: str | None

check() -> None

events(
    start: Cursor | None = None, end: Cursor | None = None
) -> Iterator[TraceEvent]

inspect_events() -> Iterator[TraceEvent]

kpi_series() -> dict[str, list[KpiPoint]]

kpis() -> dict[str, float]

observer_events(
    *, prelude: bool = False
) -> Iterator[TraceEvent]

open(
    path: str | Path, *, limits: ReaderLimits | None = None
) -> Trace

state_at(cursor: Cursor) -> State

verify() -> bool | Literal['not_verifiable']

Bounds enforced while reading a trace (spec §11.1); raise them for trusted local files.

max_record bounds the payload of any record, max_chunk the decompressed size of a chunk, max_depth the nesting of decoded values and max_len the length of any decoded array or map.

Bases: NamedTuple

A recorded domain event: [seq, ordinal, type, t, payload, deltas] as stored in a chunk.

An entry of the chunk index: where the CHUNK record is and which events it holds.

length is the size of the record including its framing.

Bases: Exception

The trace file is damaged beyond an incomplete tail, inconsistent, or exceeds the reader limits.

Declaration of a KPI and its estimand (global C1.8).

• name: unique within its collector; no / or NUL (results are keyed "<scope id>/<name>").
• unit: unit of the value, for example "time" or "jobs".
• kind: ("scalar",), ("series",) or both; a series is sampled with :meth:Collector.sample, a scalar is returned by :meth:Collector.scalars.
• observation: the observation unit, for example "job", "operation" or "time_weighted".
• cohort: which observations count (:meth:Collector.observe): "completed_in_window" (completed at or after the warm-up), "arrived_in_window" (arrived at or after the warm-up) or "all".
• aggregation: how observations become the scalar; :meth:Collector.observe supports "mean", "sum", "count", "min" and "max", other values are computed by the collector.
• clip: "window" when intervals crossing the window boundaries are clipped, else "none".
• censoring: whether entities still in the system at the end are "exclude"-d or "include"-d.
• ema_reset: whether an exponential moving average restarts at the warm-up.
• empty: the scalar when there is no observation; None leaves the scalar out of the results.
• description: free text.
• interpolation: series display rule, "previous" (default), "linear" or "none". Exact-event inspection always uses recorded eligible samples, never a future linear bracket.
• missing: "gap" (default) breaks at non-finite samples; "hold" uses the preceding finite value. These presentation settings do not change recorded values or scalar estimands.

Base class of KPI collectors (spec §12.1), bound to an owner entity, its scope.

Subclasses declare :attr:kpis and :attr:subscribes, implement :meth:on_event, record observations with :meth:observe and series samples with :meth:sample, and expose further results as attributes. Scalars that are not plain aggregations of observations (time-weighted means, rates) come from :meth:scalar_values. :meth:attach subscribes the collector and registers it with the environment.

State that depends on the observation window, such as :class:TimeWeighted accumulators started at the warm-up, is built in :meth:on_activate, which runs at activation, once the warm-up is fixed.

When :attr:scope_field names a payload field ("shopfloor", "fleet", "server"), events whose field holds another entity's id are not delivered; events without the field are, and the collector filters them itself.

env: Environment

kpis: tuple[KPI, ...] = ()

scope = scope

scope_field: str | None = None

subscribes: (
    tuple[type[Event], ...] | Literal["*", "**"]
) = ()

window: Window

attach(env: Environment) -> Self

observe(
    kpi: str, value: float, *, arrived: float | None = None
) -> None

on_activate() -> None

on_event(event: Event) -> None

sample(kpi: str, value: float) -> None

scalar_values() -> Mapping[str, float | None]

scalars() -> dict[str, float]

The observation window [start, end), or [start, end] when closed.

Time-weighted mean of a piecewise-constant signal, accumulated in constant memory.

The signal starts with value and changes at each :meth:update. Only its part from start on is accumulated, so start is the left edge of the window. The warm-up, which is that edge, is fixed only at activation (:meth:Environment.configure_kpis may be called after a collector is built), so collectors create their accumulators in :meth:Collector.on_activate with self.window.start. Updates before start only set the value carried into the window. Integrals are exactly rounded sums (D58).

value: float

mean(
    window_start: float, window_end: float
) -> float | None

update(t: float, value: float) -> None