Source code for passengersim.tracers.generic
from __future__ import annotations
from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, ClassVar, Literal
if TYPE_CHECKING:
import pandas as pd
from pydantic import BaseModel
from passengersim import Simulation
[docs]
class GenericTracer(ABC):
"""Base class for tracers that collect detail while a simulation runs.
Subclasses that can be enabled from a configuration declare, beside their
constructor, everything a configured-callback registration needs:
:attr:`name`, :attr:`hook`, :attr:`options_model`, and
:attr:`options_version`. Then
:func:`passengersim.callbacks.register_tracer_factory` registers the class
without restating any of them.
"""
name: str = "generic_tracer"
"""Canonical result key in ``callback_data``."""
hook: ClassVar[Literal["initialize_sample", "begin_sample", "daily", "end_sample", "finalize_sample"]]
"""Lifecycle hook at which the tracer runs, for manual and configured attachment."""
options_model: ClassVar[type[BaseModel] | None] = None
"""Pydantic model of the constructor's keyword options, for configured callbacks.
Its fields and defaults must match the constructor's arguments.
"""
options_version: ClassVar[str] = "1"
"""Configured-callback implementation version; bump when results change meaning."""
[docs]
@abstractmethod
def reset(self) -> None:
"""Reset the internal counters on this tracer to a null state."""
raise NotImplementedError()
[docs]
@abstractmethod
def fresh(self) -> GenericTracer:
"""Return a fresh copy of this tracer, tracing the same targets but not sharing state."""
raise NotImplementedError()
[docs]
@abstractmethod
def attach(self, sim: Simulation) -> None:
"""Attach this tracer to a Simulation, which will be traced as it runs."""
raise NotImplementedError()
[docs]
@abstractmethod
def finalize(self) -> pd.DataFrame:
"""Convert the internal counters on this tracer to a dataframe."""
raise NotImplementedError()