GenericTracer¶
- class passengersim.tracers.generic.GenericTracer[source]¶
Bases:
ABCBase class for tracers that collect detail while a simulation runs.
A tracer accumulates what it observes while a simulation runs, and
finalize()turns that into a table stored undersummary.callback_data.<name>.A tracer is written in one of two forms:
Hook methods. Override one or more of
on_initialize_sample(),on_begin_sample(),on_daily(),on_end_sample(), andon_finalize_sample(). The tracer is attached to every hook whose method it overrides, and one copy of the tracer receives all of them, so it can, for example, compare the start and end of each sample.Legacy. Set the class attribute
hookand define__call__, which runs on that one hook.
The time at which a queued hook (
begin_sample,daily, orend_sample) runs can be shifted with an offset in seconds, as for a plain callback, by setting apriorityattribute. A hook-method tracer has just onepriority, which applies to all of its queued hooks, so it observes every DCP from the same side of the RM systems and the simulation’s bookkeeping.Subclasses must implement
reset()andfinalize(). Thefresh(),attach(), andsetup()methods have working defaults.For each run, a tracer is reset, then set up once the scenario is built, then called at its hooks for every trial and sample, and finally finalized after the last trial. See the user guide for the full lifecycle.
passengersim.callbacks.register_tracer()registers a subclass under itsnameand infers its configuration options from the annotated constructor. A subclass can supply an explicitoptions_modelwhen configuration needs different validation.Methods
__init__()attach(sim)Attach a fresh copy of this tracer to a simulation, on all its hooks.
finalize()Convert the internal counters on this tracer to a dataframe.
fresh()Return a fresh copy of this tracer, tracing the same targets but not sharing state.
on_begin_sample(sim)Observe a sample after its first DCP, before any customer arrives.
on_daily(sim, days_prior)Observe each day of a sample.
on_end_sample(sim)Observe the end of a sample, before counters are reset.
on_finalize_sample(sim)Observe a sample after its events and bookkeeping have finished.
on_initialize_sample(sim)Observe the start of a sample, before its demand is generated.
reset()Reset the internal counters on this tracer to a null state.
setup(sim)Prepare to trace a run, once its scenario has been built.
Attributes
Result key in
callback_data.Pydantic model of the constructor's keyword options, for configured callbacks.
Configured-callback implementation version; bump when results change meaning.
Whether the simulation skips calling this tracer during burn-in samples.
Lifecycle hook at which a legacy-form tracer's
__call__runs.-
name : str =
'generic_tracer'¶ Result key in
callback_data.The class value is the canonical name. An instance may set its own name, so that two tracers of one class can be attached to the same simulation without overwriting each other’s results.
- hook : ClassVar[Literal['initialize_sample', 'begin_sample', 'daily', 'end_sample', 'finalize_sample']]¶
Lifecycle hook at which a legacy-form tracer’s
__call__runs.Leave this unset for a tracer written with
on_<hook>methods.
-
skip_burn : ClassVar[bool] =
False¶ Whether the simulation skips calling this tracer during burn-in samples.
The check is made by the simulation before each call, so a tracer setting this does not need to test for burn-in itself. It defaults to False so that tracers written before this flag existed behave as they always have.
-
options_model : ClassVar[type[BaseModel] | None] =
None¶ Pydantic model of the constructor’s keyword options, for configured callbacks.
By default, registration derives the model from the annotated constructor.
-
options_version : ClassVar[str] =
'1'¶ Configured-callback implementation version; bump when results change meaning.
- fresh() GenericTracer[source]¶
Return a fresh copy of this tracer, tracing the same targets but not sharing state.
The default makes a deep copy of this tracer and then calls
reset()on the copy. Override it if a tracer holds something that cannot be deep-copied, or that is expensive to copy.- Returns:
GenericTracer – A new tracer of the same type and configuration, with no accumulated data.
- attach(sim: Simulation) None[source]¶
Attach a fresh copy of this tracer to a simulation, on all its hooks.
- Parameters:
- sim : Simulation or MultiSimulation or Experiments¶
The object to attach to. The simulation stores a copy made with
fresh(), so this tracer object itself is never modified by a run and can be attached to several simulations.
- Raises:
TypeError – If the tracer declares no hook and overrides no hook method.
- setup(sim: Simulation) None[source]¶
Prepare to trace a run, once its scenario has been built.
Called once per run (
runorrun_trial), afterreset()and after the simulation has built its network, fares, and demands, but before the first sample. Override it to look up what the tracer will observe and to allocate its accumulators, so that problems are reported before the run starts. The default does nothing.An exception raised here stops the run; nothing is finalized, and the next run starts from a fresh reset.
- Parameters:
- sim : Simulation¶
The simulation about to run.
- on_initialize_sample(sim: Simulation) dict | None[source]¶
Observe the start of a sample, before its demand is generated.
Override this to attach the tracer to the
initialize_samplehook. A returned dictionary is stored undercallback_data.initialize_sample, as for a plain callback.- Parameters:
- sim : Simulation¶
The running simulation.
- on_begin_sample(sim: Simulation) dict | None[source]¶
Observe a sample after its first DCP, before any customer arrives.
Override this to attach the tracer to the
begin_samplehook. Its time is set by the tracer’spriorityattribute, if it has one, as for a plain begin-sample callback.- Parameters:
- sim : Simulation¶
The running simulation.
- on_daily(sim: Simulation, days_prior: int) dict | None[source]¶
Observe each day of a sample.
Override this to attach the tracer to the
dailyhook. The time of day is set by the tracer’spriorityattribute, if it has one, as for a plain daily callback.- Parameters:
- sim : Simulation¶
The running simulation.
- days_prior : int¶
Days remaining before departure.
- on_end_sample(sim: Simulation) dict | None[source]¶
Observe the end of a sample, before counters are reset.
Override this to attach the tracer to the
end_samplehook. Its time is set by the tracer’spriorityattribute, if it has one, as for a plain end-sample callback.- Parameters:
- sim : Simulation¶
The running simulation.
- on_finalize_sample(sim: Simulation) dict | None[source]¶
Observe a sample after its events and bookkeeping have finished.
Override this to attach the tracer to the
finalize_samplehook.- Parameters:
- sim : Simulation¶
The running simulation.