from __future__ import annotations
import warnings
from collections.abc import Callable, Mapping, MutableMapping
from typing import TYPE_CHECKING, Any
from passengersim_core import (
Event,
)
from .combine import combine_values
from .registry import (
DEFAULT_DAILY_PRIORITY,
HOOKS,
SYNCHRONOUS_HOOKS,
CallbackRegistry,
Registration,
check_daily_priority,
)
from .tracer import GenericTracer, tracer_hooks, uses_hook_methods
if TYPE_CHECKING:
from passengersim_core import SimulationEngine
from passengersim.rm.systems import RmSys
from .configured import CallbackDefinition
def _hook_callbacks_view(hook: str) -> property:
"""Build the read-only ``<hook>_callbacks`` tuple property for one hook."""
def view(self: CallbackMixin) -> tuple[Callable, ...]:
# A tuple, not a list, so that an attempt to edit it fails loudly
# instead of silently changing a copy.
return tuple(self._callback_registry.functions(hook))
view.__doc__ = (
f"Every callback attached to the ``{hook}`` hook, in the order they run.\n\n"
"Includes RM systems and configured callbacks. This is a read-only snapshot:\n"
f"use the ``{hook}_callback`` method to attach a callback."
)
return property(view)
[docs]
class TracerHook:
"""One hook method of a tracer, as registered on that hook.
A tracer written with ``on_<hook>`` methods is registered once per hook,
each registration holding one of these. All of them call the same tracer
object, so the tracer's state is never split across copies. The
``priority`` and ``skip_burn`` settings are read from the tracer, so the
scheduler and dispatcher treat this exactly like a legacy tracer.
A tracer has one ``priority``, which times all of its queued hooks
(``begin_sample``, ``daily``, and ``end_sample``) alike, so it observes
every DCP from the same side of the RM systems and bookkeeping. Where
two of its hooks share a timestamp (the first DCP's begin-sample and
daily calls, or the final DCP's daily and end-sample calls), they run in
lifecycle order, as all callbacks sharing a timestamp do (see
:meth:`CallbackMixin.add_callback_events`).
"""
__slots__ = ("__wrapped__", "hook", "tracer")
def __init__(self, tracer: GenericTracer, hook: str) -> None:
self.tracer = tracer
"""The tracer whose method is called."""
self.hook = hook
"""The lifecycle hook this method runs on."""
# inspect.signature() follows __wrapped__, so configured-callback
# preparation checks the real method's signature, not this wrapper's.
self.__wrapped__ = getattr(tracer, f"on_{hook}")
def __call__(self, sim: Any, *args: Any) -> Any:
return self.__wrapped__(sim, *args)
@property
def priority(self) -> Any:
"""The tracer's offset in seconds, read when events are scheduled."""
return getattr(self.tracer, "priority", DEFAULT_DAILY_PRIORITY)
@property
def skip_burn(self) -> bool:
"""Whether the tracer is skipped during burn-in samples."""
return bool(getattr(self.tracer, "skip_burn", False))
def __repr__(self) -> str:
return f"<{type(self.tracer).__name__}({self.tracer.name!r}).on_{self.hook}>"
def _check_tracer_name(name: Any, what: str = "tracer") -> None:
"""Reject a result name that is empty or reserved for a hook's data."""
if not isinstance(name, str) or not name:
raise ValueError(f"A {what} name must be a nonempty string, not {name!r}")
if name in HOOKS:
raise ValueError(
f"A {what} cannot be named {name!r}: that name is reserved for the data returned by {name} callbacks"
)
[docs]
class CallbackWithOptions:
"""A plain callback registered with keyword options.
Registering a function with options such as ``priority`` or ``name``
stores the function inside one of these, rather than setting attributes
on the function itself, so the same function can be registered elsewhere
with different options. An option left as None falls back to the
function's own attribute of the same name, if it has one.
"""
__slots__ = ("__wrapped__", "_priority", "_skip_burn", "result_name")
def __init__(
self,
func: Callable,
*,
priority: int | None = None,
skip_burn: bool | None = None,
name: str | None = None,
) -> None:
self.__wrapped__ = func
self._priority = priority
self._skip_burn = skip_burn
self.result_name = name
"""Key under which returned dictionaries are stored, instead of the hook name."""
def __call__(self, sim: Any, *args: Any) -> Any:
return self.__wrapped__(sim, *args)
@property
def priority(self) -> Any:
"""The offset in seconds for a queued hook, read when events are scheduled."""
if self._priority is not None:
return self._priority
return getattr(self.__wrapped__, "priority", DEFAULT_DAILY_PRIORITY)
@property
def skip_burn(self) -> bool:
"""Whether the callback is skipped during burn-in samples."""
if self._skip_burn is not None:
return self._skip_burn
return bool(getattr(self.__wrapped__, "skip_burn", False))
def __repr__(self) -> str:
options = {"priority": self._priority, "skip_burn": self._skip_burn, "name": self.result_name}
text = ", ".join(f"{k}={v!r}" for k, v in options.items() if v is not None)
return f"<{self.__wrapped__!r} with {text}>"
def _result_name(func: Callable) -> str | None:
"""The ``callback_data`` key a plain callback was given with ``name=``, if any."""
name = getattr(func, "result_name", None)
return name if isinstance(name, str) else None
def _same_callable(attached: Any, callback: Callable) -> bool:
"""Whether an attached callable is the given callback.
Equality, not identity, is what identifies a bound method: every access to
``obj.method`` creates a new method object, but two of them compare equal
when they bind the same function to the same object. An ``__eq__`` that
raises or returns something other than a bool counts as no match.
"""
if attached is callback:
return True
if attached is None:
return False
try:
result = attached == callback
except Exception:
return False
return result if isinstance(result, bool) else False
def _owning_tracer(registration: Registration) -> GenericTracer | None:
"""Get the tracer a registration belongs to, or None for a plain callback."""
if registration.owner is not None:
return registration.owner
# Registrations made without an owner (e.g. by older code calling the
# registry directly) still count a tracer registered as itself.
return registration.func if isinstance(registration.func, GenericTracer) else None
def _tracer_entries(tracer: GenericTracer, hooks: tuple[str, ...]) -> list[tuple[str, Callable]]:
"""Build the ``(hook, callable)`` pairs that attach one tracer to its hooks."""
if uses_hook_methods(tracer):
return [(hook, TracerHook(tracer, hook)) for hook in hooks]
# A legacy tracer is itself the callable, on its one hook.
return [(hook, tracer) for hook in hooks]
[docs]
class CallbackMixin:
if TYPE_CHECKING:
eng: SimulationEngine
callback_data: CallbackData
@property
def _callback_registry(self) -> CallbackRegistry:
"""Registry of every callback attached to this object, created on first use."""
# Classes using this mixin do not call an initializer for it, so the
# registry is created lazily and kept in the instance dictionary.
try:
return self.__dict__["_callback_registry_store"]
except KeyError:
registry = self.__dict__["_callback_registry_store"] = CallbackRegistry()
return registry
initialize_sample_callbacks = _hook_callbacks_view("initialize_sample")
begin_sample_callbacks = _hook_callbacks_view("begin_sample")
daily_callbacks = _hook_callbacks_view("daily")
end_sample_callbacks = _hook_callbacks_view("end_sample")
finalize_sample_callbacks = _hook_callbacks_view("finalize_sample")
def _add_callback(
self,
hook: str,
callback: Callable | GenericTracer,
origin: str = "manual",
*,
options: dict[str, Any] | None = None,
) -> Callable:
"""Attach a callback to a hook, or a fresh copy of a tracer to all its hooks.
Parameters
----------
hook : str
Lifecycle hook to attach to. For a tracer with several hook
methods, this must be one of them, and the tracer is attached to
all of them.
callback : Callable or GenericTracer
The callback. A tracer is replaced by a fresh copy, so that a tracer
object attached to several simulations never shares state.
origin : {"manual", "configured", "rm"}, default "manual"
Owner of the registration.
options : dict, optional
Keyword options given at registration (``priority``,
``skip_burn``, ``name``); None values are ignored. A plain
callback is wrapped in a :class:`CallbackWithOptions`; a tracer's
fresh copy has the options set as attributes. A ``priority``
given for a tracer with hook methods applies to all its queued
hooks, whichever registration method it was given to.
Returns
-------
Callable
The callback actually attached: the fresh copy, for a tracer.
Raises
------
ValueError
If a tracer does not run on `hook`, a tracer's name is empty or
reserved, or a queued callback has a ``priority`` of zero.
TypeError
If a tracer both declares a ``hook`` and overrides hook methods.
"""
options = {k: v for k, v in (options or {}).items() if v is not None}
if not isinstance(callback, GenericTracer):
if options:
if "name" in options:
_check_tracer_name(options["name"], "callback")
callback = CallbackWithOptions(callback, **options)
name = _result_name(callback)
if name is not None:
self._check_name_free(name, f"A callback named {name!r}")
self._callback_registry.add(hook, callback, origin)
return callback
hooks = self._tracer_hooks_for(hook, callback)
if "name" in options:
_check_tracer_name(options["name"])
clone = self._fresh_tracer(callback)
if isinstance(clone, GenericTracer):
for option, value in options.items():
setattr(clone, option, value)
if not isinstance(clone, GenericTracer):
# A tracer whose fresh() returns some other callable is attached
# as a plain callback, as it always has been.
self._callback_registry.add(hook, clone, origin)
return clone
self._check_name_free(clone.name, f"A tracer named {clone.name!r}", tracers=False)
replaces: list[Registration] = []
if origin == "manual":
# A manual tracer replaces an earlier one with the same result
# name, which would otherwise be silently overwritten. Replacing
# (rather than refusing) keeps notebook cells re-runnable. Every
# registration the earlier tracer owns goes, on all its hooks.
replaces = [
r
for r in self._callback_registry.select(origin="manual")
if isinstance(owner := _owning_tracer(r), GenericTracer) and owner.name == clone.name
]
self._callback_registry.add_group(_tracer_entries(clone, hooks), origin, owner=clone, replaces=replaces)
if replaces:
warnings.warn(
f"A tracer named {clone.name!r} was already attached, and has been replaced. "
"To keep both, give one of them a different name with the tracer's name= option.",
UserWarning,
stacklevel=3,
)
return clone
def _check_name_free(self, name: str, what: str, *, tracers: bool = True) -> None:
"""Reject a result name that a tracer, or a named callback, already uses.
Parameters
----------
name : str
The ``callback_data`` key about to be claimed.
what : str
Description of the newcomer, for the error message.
tracers : bool, default True
Whether to check tracers. A newly attached tracer leaves this
False, because it replaces a manual tracer of the same name.
Raises
------
ValueError
If a tracer, or (when `tracers` is False) a named callback, uses
the same name, so their results would overwrite each other.
"""
for registration in self._callback_registry.select():
tracer = _owning_tracer(registration)
if tracers and tracer is not None and tracer.name == name:
clash = f"tracer {type(tracer).__name__}"
elif not tracers and tracer is None and _result_name(registration.func) == name:
clash = f"callback {registration.func!r}"
else:
continue
raise ValueError(
f"{what} would store its results under the same name as the {clash}; choose a different name"
)
[docs]
def remove_callback(self, callback: Callable | GenericTracer | str, *, missing_ok: bool = False) -> int:
"""Detach manually attached callbacks or tracers.
Parameters
----------
callback : Callable or GenericTracer or str
What to remove:
- a function (or other callable) previously attached, with or
without options, is removed from every hook it is attached to;
a bound method matches when it binds the same function to the
same object, even if it is a new ``obj.method`` expression;
- a tracer, or a tracer's result name, removes the attached tracer
of that name from all its hooks;
- a name given to callbacks with ``name=`` removes those callbacks.
missing_ok : bool, default False
Return 0 instead of raising if nothing matches.
Returns
-------
int
The number of hook registrations removed.
Raises
------
ValueError
If nothing matches and `missing_ok` is False. Callbacks built from
``config.callbacks`` and carrier RM systems cannot be removed this
way: disable a configured callback in the configuration instead.
Notes
-----
A callback removed while a sample is running may still be called for
the rest of that sample; the removal takes effect from the next one.
"""
def matches(registration: Registration) -> bool:
tracer = _owning_tracer(registration)
if isinstance(callback, str):
return (tracer.name if tracer is not None else _result_name(registration.func)) == callback
if isinstance(callback, GenericTracer):
# The attached tracer is a fresh copy, which keeps the name.
return tracer is not None and tracer.name == callback.name
if tracer is not None:
# A tracer is removed only as a whole (by object or name), so
# passing one of its hook methods never splits it across hooks.
return False
return _same_callable(registration.func, callback) or _same_callable(
getattr(registration.func, "__wrapped__", None), callback
)
registry = self._callback_registry
found = [r for r in registry.select(origin="manual") if matches(r)]
if not found:
if missing_ok:
return 0
others = {r.origin for r in registry.select() if r.origin != "manual" and matches(r)}
if "configured" in others:
raise ValueError(
f"{callback!r} was built from config.callbacks; disable it there instead of removing it"
)
raise ValueError(f"{callback!r} is not attached as a callback")
registry.remove(found)
return len(found)
@staticmethod
def _tracer_hooks_for(hook: str | None, tracer: GenericTracer) -> tuple[str, ...]:
"""Get the hooks to register a tracer on, when attached through `hook`.
Raises
------
ValueError
If the tracer does not run on `hook`.
"""
hooks = tracer_hooks(tracer)
if hook is None:
if not hooks:
raise TypeError("a tracer registered without a hook must declare one")
return hooks
if not hooks:
# A legacy tracer that declares no hook goes wherever it is put.
return (hook,)
if hook not in hooks:
if len(hooks) == 1:
runs_on = f"the {hooks[0]!r} hook"
instead = f"use its attach() method or the {hooks[0]}_callback method instead"
else:
runs_on = f"the hooks {', '.join(repr(h) for h in hooks)}"
instead = "use its attach() method instead"
raise ValueError(
f"{type(tracer).__name__} runs on {runs_on} and cannot be attached as a {hook} callback; {instead}"
)
return hooks
@staticmethod
def _fresh_tracer(tracer: GenericTracer) -> Callable:
"""Check a tracer's name, and make the fresh copy to attach.
Parameters
----------
tracer : GenericTracer
The tracer as given by the user.
Returns
-------
Callable
The fresh copy, carrying the original tracer's result name and hook settings.
Raises
------
ValueError
If the tracer's name is invalid.
"""
_check_tracer_name(tracer.name)
clone = tracer.fresh()
if isinstance(clone, GenericTracer):
# A custom fresh() may rebuild from constructor arguments, losing
# options set on the attached instance before it reached a worker.
for option, default in (("name", None), ("priority", DEFAULT_DAILY_PRIORITY), ("skip_burn", False)):
value = getattr(tracer, option, default)
if getattr(clone, option, default) != value:
setattr(clone, option, value)
return clone
def _distinct_tracers(self, origin: str | None = None) -> list[GenericTracer]:
"""Get the distinct tracers attached to this object, in dispatch order.
Parameters
----------
origin : str, optional
Only tracers with this origin.
Returns
-------
list[GenericTracer]
Each tracer once, even if it is registered on several hooks.
"""
seen: set[int] = set()
tracers = []
for registration in self._callback_registry.select(origin=origin):
tracer = _owning_tracer(registration)
if isinstance(tracer, GenericTracer) and id(tracer) not in seen:
seen.add(id(tracer))
tracers.append(tracer)
return tracers
def _reset_manual_tracers(self) -> None:
"""Clear the accumulated data of every manually attached tracer.
Called once at the start of each public execution (``run`` or
``run_trial``), so that a re-run does not carry accumulation over from
a previous run. Configured tracers are rebuilt for each run instead.
"""
for tracer in self._distinct_tracers(origin="manual"):
tracer.reset()
def _setup_tracers(self) -> None:
"""Call ``setup`` on every attached tracer, once the scenario is built.
Called once per public execution, after the scenario is built and
before the first sample, for tracers of every origin. An exception
propagates and stops the run before any sample is simulated.
"""
for tracer in self._distinct_tracers():
tracer.setup(self)
def _invoke_callback(self, callback: Callable, *args: Any) -> Any:
"""Call one callback with this object and any hook arguments.
Subclasses override this to wrap the call, e.g. with timing diagnostics.
"""
return callback(self, *args)
def _dispatch_callback(self, hook: str, callback: Callable, *args: Any) -> None:
"""Run one callback and store any dictionary it returns.
This is the single path by which every hook, synchronous or queued,
invokes a callback.
Parameters
----------
hook : str
The hook being dispatched; also the ``callback_data`` key under
which a returned dictionary is stored, unless the callback was
registered with a ``name``.
callback : Callable
The callback to run. One with a true ``skip_burn`` attribute (see
:attr:`GenericTracer.skip_burn`) is not run during burn-in samples.
*args
Hook arguments after the simulation: the days prior for a daily
callback, nothing for the other hooks.
Raises
------
ValueError
If the callback returns a dictionary with a ``trial``, ``sample``
or ``days_prior`` key, which are reserved for the stored row's
index (see :meth:`CallbackData.update_data_from_mapping`).
"""
if getattr(callback, "skip_burn", False) and self.eng.sample < self.eng.burn_samples:
return
result = self._invoke_callback(callback, *args)
if isinstance(result, dict):
key = _result_name(callback) or hook
# Checked here as well as in update_data, so the error can name the
# hook and the callback rather than only the storage key.
reserved = _reserved_keys_in(result)
if reserved:
raise ValueError(
f"{hook} callback {callback!r} returned the reserved key(s) "
f"{', '.join(map(repr, reserved))}; {_RESERVED_KEYS_HINT}"
)
days_prior = args[0] if args else None
# The returned dictionary is passed as one mapping, not as keyword
# arguments, so keys such as "label" cannot collide with parameters.
self.callback_data.update_data_from_mapping(key, self.eng.trial, self.eng.sample, days_prior, result)
def _run_synchronous_callbacks(self, hook: str) -> None:
"""Dispatch a synchronous lifecycle hook without creating events."""
for callback in self._callback_registry.functions(hook):
self._dispatch_callback(hook, callback)
def _register(
self, hook: str, callback: Callable | GenericTracer | None, options: dict[str, Any]
) -> Callable | GenericTracer:
"""Attach a callback, or return a decorator that will, with keyword options.
Without options, the result is what :meth:`_add_callback` returns (the
fresh copy, for a tracer). With options, a plain function is returned
unchanged, so that it still names the function where it is decorated.
"""
def attach(func: Callable | GenericTracer) -> Callable | GenericTracer:
attached = self._add_callback(hook, func, options=options)
if isinstance(attached, CallbackWithOptions) and attached.__wrapped__ is func:
return func
return attached
if callback is None:
return attach
return attach(callback)
[docs]
def initialize_sample_callback(
self,
callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None,
*,
skip_burn: bool | None = None,
name: str | None = None,
) -> Callable[[CallbackMixin], dict | None] | GenericTracer:
"""Register a synchronous callback before sample demand generation.
The sample number, random seed, and counters have been initialized,
but the new sample's RM steps have not run. Changes to demand inputs
affect this sample. Callbacks run in registration order, with configured
callbacks first; event priority does not apply.
Parameters
----------
callback : Callable[[Simulation], dict | None] or GenericTracer, optional
Callback receiving the simulation. Returned dictionaries are stored
under ``callback_data.initialize_sample`` with trial/sample keys.
Omit it to use this method as a decorator with options.
skip_burn : bool, optional
If True, the callback is not called during burn-in samples.
name : str, optional
Store returned dictionaries under ``callback_data.<name>`` instead
of the shared hook key; for a tracer, its result name.
Returns
-------
Callable or GenericTracer
The callback, or the fresh copy of a tracer. Without `callback`, a
decorator that registers the function it decorates.
"""
return self._register("initialize_sample", callback, {"skip_burn": skip_burn, "name": name})
[docs]
def finalize_sample_callback(
self,
callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None,
*,
skip_burn: bool | None = None,
name: str | None = None,
) -> Callable[[CallbackMixin], dict | None] | GenericTracer:
"""Register a synchronous callback after sample bookkeeping finishes.
Callbacks run after departure statistics, history rollover, database
commit, and other bookkeeping updates. They observe post-bookkeeping
state and cannot change statistics already recorded. Use ``end_sample``
to access pre-bookkeeping state. Their execution is included in sample
timing, before diagnostics are published. They run only on successful
completion, not as exception cleanup; callback failures propagate after
bookkeeping has completed. Configured callbacks run first, followed by
manual callbacks, each in registration order. Event priority does not
apply. Exceptions propagate.
Parameters
----------
callback : Callable[[Simulation], dict | None] or GenericTracer, optional
Callback receiving the simulation. Returned dictionaries are stored
under ``callback_data.finalize_sample`` with trial/sample keys.
Omit it to use this method as a decorator with options.
skip_burn : bool, optional
If True, the callback is not called during burn-in samples.
name : str, optional
Store returned dictionaries under ``callback_data.<name>`` instead
of the shared hook key; for a tracer, its result name.
Returns
-------
Callable or GenericTracer
The callback, or the fresh copy of a tracer. Without `callback`, a
decorator that registers the function it decorates.
"""
return self._register("finalize_sample", callback, {"skip_burn": skip_burn, "name": name})
[docs]
def end_sample_callback(
self,
callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None,
*,
priority: int | None = None,
skip_burn: bool | None = None,
name: str | None = None,
) -> Callable[[CallbackMixin], dict | None] | GenericTracer:
"""Register a function to be triggered at the end of each sample.
The callback function will be triggered before counters are reset or
history buffers are rolled over.
It runs at an offset, in seconds, from the trigger time of the final
DCP (the day of departure). The offset is the `priority` option if
given, else the callback's own ``priority`` attribute if it has one,
and otherwise one second, which is after the final DCP's RM systems
(-1) and bookkeeping (0). A negative ``priority`` runs it before that
bookkeeping, or, below -1, before the RM systems as well. A
``priority`` of zero is not allowed, as for a daily callback.
Parameters
----------
callback : Callable[[Simulation], dict | None] or GenericTracer, optional
The callback function to register. It should accept a single argument,
which will be the Simulation object, and return a dictionary of interesting
things to store, or nothing. Omit it to use this method as a
decorator with options.
priority : int, optional
Offset in seconds from the final DCP's trigger time; see above.
skip_burn : bool, optional
If True, the callback is not called during burn-in samples.
name : str, optional
Store returned dictionaries under ``callback_data.<name>`` instead
of the shared hook key; for a tracer, its result name.
Returns
-------
Callable or GenericTracer
The callback, or the fresh copy of a tracer. Without `callback`, a
decorator that registers the function it decorates.
"""
return self._register("end_sample", callback, {"priority": priority, "skip_burn": skip_burn, "name": name})
[docs]
def begin_sample_callback(
self,
callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None,
*,
priority: int | None = None,
skip_burn: bool | None = None,
name: str | None = None,
) -> Callable[[CallbackMixin], dict | None] | GenericTracer:
"""Register a function to be triggered at the beginning of each sample.
The callback function will be triggered after initial setup including
all RM steps for the initial DCP, but before any customers can arrive.
It runs at an offset, in seconds, from the trigger time of the first
DCP. The offset is the `priority` option if given, else the
callback's own ``priority`` attribute if it has one, and otherwise one
second, which is after the first DCP's RM systems (-1) and bookkeeping
(0). A negative ``priority`` runs it before that bookkeeping, or,
below -1, before the first DCP's RM steps as well. No customer arrives
within five seconds of a DCP, so a ``priority`` from 1 to 4 always
runs before the first arrival; a larger one may not. A ``priority`` of
zero is not allowed, as for a daily callback.
Parameters
----------
callback : Callable[[Simulation], dict | None] or GenericTracer, optional
The callback function to register. It should accept a single argument,
which will be the Simulation object, and return a dictionary of interesting
things to store, or nothing. Omit it to use this method as a
decorator with options.
priority : int, optional
Offset in seconds from the first DCP's trigger time; see above.
skip_burn : bool, optional
If True, the callback is not called during burn-in samples.
name : str, optional
Store returned dictionaries under ``callback_data.<name>`` instead
of the shared hook key; for a tracer, its result name.
Returns
-------
Callable or GenericTracer
The callback, or the fresh copy of a tracer. Without `callback`, a
decorator that registers the function it decorates.
"""
return self._register("begin_sample", callback, {"priority": priority, "skip_burn": skip_burn, "name": name})
[docs]
def daily_callback(
self,
callback: Callable[[CallbackMixin, int], dict | None] | GenericTracer | RmSys | None = None,
*,
priority: int | None = None,
skip_burn: bool | None = None,
name: str | None = None,
) -> Callable[[CallbackMixin, int], dict | None] | GenericTracer:
"""Register a function to be triggered each day during a sample.
The callback runs at an offset, in seconds, from the overnight trigger
time. The offset is the `priority` option if given, else the
callback's own ``priority`` attribute if it has one, and otherwise one
second. RM systems run at -1 and the simulation's own DCP and daily
data capture at 0, so by default a callback sees each day after both
have finished. Use a negative ``priority`` to run it before the
simulation's bookkeeping, or below -1 to run it before the RM systems
as well.
A ``priority`` of zero is not allowed, because it would tie with the
simulation's own bookkeeping in an arbitrary order. It is rejected
here, and again when a run starts if it was set after registration.
The ``priority`` must also be a whole number of seconds: a value that
clearly names one, such as ``1.0`` or ``"1"``, is used as that integer,
and anything else (``0.5``, ``"1.5"``, ``True``, ``"high"``) is
rejected rather than rounded. A callback attached while a sample is
running takes effect from the next sample.
The options can be given with the callback, or to use this method as
a decorator::
@sim.daily_callback(priority=-5, skip_burn=True, name="nogo")
def count_nogo(sim, days_prior): ...
Parameters
----------
callback : Callable[[Simulation, int], dict | None] or GenericTracer, optional
The callback function to register. It should accept two arguments,
which will be the Simulation object and the days_prior, and return
a dictionary of interesting things to store, or nothing. Omit it to
use this method as a decorator with options.
priority : int, optional
Offset in seconds from the overnight trigger time; see above.
skip_burn : bool, optional
If True, the callback is not called during burn-in samples.
name : str, optional
Store returned dictionaries under ``callback_data.<name>`` instead
of the shared ``daily`` key, so they cannot collide with other
callbacks' keys; for a tracer, its result name.
Returns
-------
Callable or GenericTracer
The callback, or the fresh copy of a tracer. Without `callback`, a
decorator that registers the function it decorates.
Raises
------
ValueError
If the priority is zero or not a whole number of seconds, the name
is reserved or used by a tracer,
or the callback is a tracer declaring a hook other than ``daily``.
"""
return self._register("daily", callback, {"priority": priority, "skip_burn": skip_burn, "name": name})
[docs]
def callback_functions(self) -> dict[str, list[Callable]]:
"""Get all manually attached callback functions.
Callbacks constructed from ``config.callbacks`` declarations are
excluded. They are owned by this object's config and are rebuilt by
any simulation that runs that config, so copying them elsewhere (e.g.
via :meth:`apply_callback_functions` or worker forwarding) would
attach them twice. Carrier RM systems are excluded for the same
reason: every simulation builds its own.
Returns
-------
dict[str, list[Callable]]
Mapping of ``"<hook>_callbacks"`` to the manual callbacks for each
hook, in registration order. A tracer is listed as itself under
each hook it runs on.
"""
return {
f"{hook}_callbacks": [
r.func if (tracer := _owning_tracer(r)) is None else tracer
for r in self._callback_registry.select(hook, origin="manual")
]
for hook in HOOKS
}
def _manual_callbacks(self) -> list[tuple[str, Callable]]:
"""Get manual callbacks as ``(hook, callback)`` pairs in registration order.
Unlike :meth:`callback_functions`, this keeps the order of callbacks
on different hooks, which decides who runs first when they share a
timestamp. It is what gets forwarded to other simulations and workers.
A tracer appears once, as itself, at the position of its first hook,
never as separate hook methods. The receiving side makes one fresh
copy and binds every hook to that copy, so the tracer's state cannot
be split across copies.
"""
exported: list[tuple[str, Callable]] = []
seen: set[int] = set()
for registration in self._callback_registry.select(origin="manual"):
tracer = _owning_tracer(registration)
if tracer is None:
exported.append((registration.hook, registration.func))
elif id(tracer) not in seen:
seen.add(id(tracer))
exported.append((registration.hook, tracer))
return exported
def _adopt_callbacks(self, callbacks: list[tuple[str, Callable]]) -> None:
"""Attach ``(hook, callback)`` pairs, in order, as manual callbacks.
A tracer is attached to all its hooks, whichever one it is paired with.
"""
for hook, callback in callbacks:
# Go through the public methods so that subclass overrides apply.
getattr(self, f"{hook}_callback")(callback)
[docs]
def apply_callback_functions(self, sim: CallbackMixin) -> None:
"""Attach this object's manual callbacks to another simulation.
Parameters
----------
sim : CallbackMixin
The simulation (or experiments) to receive the callbacks. Tracers
are copied fresh; other callables are shared.
"""
sim._adopt_callbacks(self._manual_callbacks())
[docs]
def use_registered_callbacks(self) -> None:
"""Adopt all globally registered callbacks (deprecated).
Warnings
--------
This method emits a DeprecationWarning. For reusable callbacks,
register them with ``register_callback`` (functions) or
``register_tracer`` (tracer classes) and select them in
``config.callbacks``; those register for configuration rather than
attaching to every simulation. For development and testing, attach
callbacks directly with the simulation's hook methods, or use an
explicit ``CallbackMixin`` bundle and
``bundle.apply_callback_functions(sim)``. Registration APIs, including
the factory ones, are not deprecated.
"""
from .registration import _REGISTERED_CALLBACKS
warnings.warn(
"use_registered_callbacks is deprecated. For reusable callbacks, register them with "
"register_callback (functions) or register_tracer (tracer classes) and select them in "
"config.callbacks; those do not attach them to every simulation. For development and "
"testing, attach callbacks directly to the simulation, or use an explicit CallbackMixin "
"bundle with bundle.apply_callback_functions(sim).",
DeprecationWarning,
stacklevel=2,
)
_REGISTERED_CALLBACKS.apply_callback_functions(self)
def _preflight_configured_callbacks(self) -> dict[str, CallbackDefinition]:
from .configured import preflight
return preflight(self)
def _prepare_configured_callbacks(self, definitions: dict[str, CallbackDefinition] | None = None) -> None:
from .configured import prepare
prepare(self, definitions)
[docs]
def add_callback_events(self):
"""Add callback events to the simulation event queue.
All callbacks due at the same timestamp are placed in one event. The
native event queue orders events by time alone, so separate events at
one timestamp would run in an arbitrary order. Within one event, they
run in this order:
1. RM systems;
2. then the hooks in lifecycle order, so that at the first DCP every
``begin_sample`` callback runs before any ``daily`` one, and at the
final DCP every ``daily`` callback runs before any ``end_sample``
one;
3. within each hook, configured callbacks before manual ones, each in
registration (or declaration) order.
RM systems stay first so that a priority of -1, the RM systems' own,
still runs a callback after them, as documented for each hook.
"""
dcp_hour = self.eng.config.simulation_controls.dcp_hour
first_day = self.dcp_list[0]
# Each entry is (sort key, event info). select() already orders by
# origin and registration, and the stable sort below keeps that order
# within each hook.
batches: dict[int, list[tuple[tuple[int, int], tuple]]] = {}
for registration in self._callback_registry.select():
hook = registration.hook
if hook in SYNCHRONOUS_HOOKS:
continue
# The priority is a number of seconds before or after the overnight
# trigger time. If priority is negative, the callback will be run
# before any RM system daily or same-time DCP events. If priority is
# positive it will be run after other RM events. The default of one
# second places begin-sample callbacks after the first DCP but before
# any customers can arrive (none arrive within 5 seconds of a DCP),
# and end-sample callbacks after the last DCP.
# Checked again here, because the priority is read from the
# callable and may have been changed after registration. The
# checked value is an int, so a priority given as "1" or 1.0 is
# scheduled at exactly one second.
offset = check_daily_priority(registration.priority, f"{hook} callback {registration.func!r}")
if hook == "daily":
days = range(first_day, -1, -1)
else:
days = [first_day if hook == "begin_sample" else 0]
key = (0 if registration.origin == "rm" else 1, HOOKS.index(hook))
for day in days:
timestamp = int(self.eng.base_time - day * 86400 + 3600 * dcp_hour + offset)
info = (hook, registration.func, day) if hook == "daily" else (hook, registration.func)
batches.setdefault(timestamp, []).append((key, info))
for timestamp, entries in batches.items():
entries.sort(key=lambda entry: entry[0])
self.eng.add_event(Event(("callback_batch", tuple(info for _, info in entries)), timestamp))
_RESERVED_ROW_KEYS = ("days_prior", "sample", "trial")
"""Keys every :class:`CallbackData` row uses as its index; callbacks cannot store values under them."""
_RESERVED_KEYS_HINT = (
"trial, sample and days_prior are recorded automatically as each row's index; rename the value to store it"
)
def _reserved_keys_in(values: Mapping[str, Any]) -> list[str]:
"""The reserved row index keys present in a mapping of values, sorted."""
return [k for k in _RESERVED_ROW_KEYS if k in values]
def _detached(value):
"""Return a sum result's container that does not alias an operand's list.
Writing into a summed :class:`CallbackData` (e.g. via ``update_data``)
appends to its lists, so passing an operand's list through unchanged would
write into that operand too. Other values are returned as is.
"""
return list(value) if isinstance(value, list) else value
def _flatten_dict_keys(d):
for k, v in d.items():
if isinstance(v, dict):
for sub_k, sub_v in _flatten_dict_keys(v):
yield f"{k}.{sub_k}", sub_v
elif isinstance(v, list | tuple):
for i, sub_v in enumerate(v):
yield f"{k}[{i}]", sub_v
else:
yield k, v
def _flatten_iter_of_dict(i):
for item in i:
yield dict(_flatten_dict_keys(item))
[docs]
class CallbackData(MutableMapping):
"""Data collected during callbacks."""
def __init__(self):
self._data = {}
self._cached_dataframes = {}
[docs]
def get_data(self, label: str, trial: int, sample: int, days_prior: int | None = None) -> dict[str, Any]:
"""Return the row dictionary for one trial, sample and day, creating it if needed.
Rows under a label are appended in order, and only the most recent row
is reused: a row is matched on its ``trial``, ``sample`` and (when given)
``days_prior`` index keys, and a new row is started when they differ.
Parameters
----------
label : str
The ``callback_data`` key: a hook name, or a callback's result name.
trial, sample : int
The trial and sample the row belongs to.
days_prior : int, optional
The days prior to departure, for a daily callback's row.
Returns
-------
dict
The stored row, which holds the index keys and any values added to it.
"""
key_match = {"trial": trial, "sample": sample}
if days_prior is not None:
key_match["days_prior"] = days_prior
if label not in self._data:
self._data[label] = [key_match]
store = self._data[label][-1]
if any(store.get(k) != v for k, v in key_match.items()):
self._data[label].append(key_match)
store = self._data[label][-1]
return store
[docs]
def update_data(
self,
label: str,
trial: int,
sample: int,
days_prior: int | None = None,
**kwargs: Any,
) -> None:
"""Add keyword values to a callback row.
Parameters
----------
label : str
Callback result key.
trial, sample : int
Trial and sample identifying the row.
days_prior : int, optional
Days before departure for a daily observation.
**kwargs
Values to add. Use `update_data_from_mapping` for a value named
``label`, which is also an argument to this method.
"""
self.update_data_from_mapping(label, trial, sample, days_prior, kwargs)
[docs]
def update_data_from_mapping(
self,
label: str,
trial: int,
sample: int,
days_prior: int | None = None,
values: Mapping[str, Any] | None = None,
/,
**kwargs: Any,
) -> None:
"""Add values to the row for one trial, sample and day.
All the bookkeeping parameters are positional-only, so a value may be
given as a keyword of any name, including ``label`` or ``values``.
Values may also be given as a ``values`` mapping, which is how the
dictionary returned by a callback is stored; keyword values are applied
after it.
The keys ``trial``, ``sample`` and ``days_prior`` are reserved for the
row's own index, which :meth:`get_data` matches rows on, so a value
under one of those keys is refused rather than stored. This applies to
every row, daily or not.
Parameters
----------
label : str
The ``callback_data`` key: a hook name, or a callback's result name.
trial, sample : int
The trial and sample the row belongs to.
days_prior : int, optional
The days prior to departure, for a daily callback's row.
values : Mapping, optional
Values to store in the row.
**kwargs
More values to store in the row.
Raises
------
ValueError
If a value is given under ``trial``, ``sample`` or ``days_prior``.
"""
reserved = sorted(set(_reserved_keys_in(values or {})) | set(_reserved_keys_in(kwargs)))
if reserved:
raise ValueError(
f"values for {label!r} use the reserved key(s) {', '.join(map(repr, reserved))}; {_RESERVED_KEYS_HINT}"
)
store = self.get_data(label, trial, sample, days_prior)
if values:
store.update(values)
store.update(kwargs)
self._cached_dataframes.pop(label, None)
[docs]
def to_dataframe(self, item: str):
import pandas as pd
try:
if item in self._cached_dataframes:
return self._cached_dataframes[item]
except AttributeError:
self._cached_dataframes = {}
if item in self._data:
df = pd.DataFrame(_flatten_iter_of_dict(self._data[item]))
self._cached_dataframes[item] = df
return df
else:
raise KeyError(f"{item} not found in callback data")
def __getitem__(self, item):
return self._data[item]
def __setitem__(self, key, value):
self._data[key] = value
self._cached_dataframes.pop(key, None)
def __delitem__(self, key):
del self._data[key]
self._cached_dataframes.pop(key, None)
def __iter__(self):
return iter(self._data)
def __len__(self):
return len(self._data)
def __getattr__(self, item):
if not item.startswith("_") and item in self._data:
return self._data[item]
raise AttributeError(f"{self.__class__.__name__} has no attribute '{item}'")
def __repr__(self):
if self._data:
keys = ", ".join(self._data.keys())
return f"<{self.__class__.__module__}.{self.__class__.__name__} from {keys}>"
else:
return f"<{self.__class__.__module__}.{self.__class__.__name__} with no data>"
def __bool__(self):
return bool(self._data)
def __add__(self, other):
"""Combine the data of two runs, trials, or workers into a new object.
Rows collected by callback functions are concatenated. Tracer tables
are combined by the aggregation process they declare (see
:func:`passengersim.callbacks.register_combiner`). A key present in
only one operand is copied over. Neither operand is modified.
Raises
------
ValueError
If two tables under one key declare different aggregation
processes, or a process with no registered combiner.
"""
if isinstance(other, CallbackData):
new = CallbackData()
for k in self._data:
if k in other._data:
new._data[k] = combine_values(k, self._data[k], other._data[k])
else:
new._data[k] = _detached(self._data[k])
for k in other._data:
if k not in self._data:
new._data[k] = _detached(other._data[k])
return new
elif isinstance(other, int) and other == 0:
return self
elif other is None:
return self
else:
return NotImplemented
def __radd__(self, other):
if isinstance(other, int) and other == 0:
return self
elif other is None:
return self
else:
return NotImplemented
def __dir__(self):
return self._data.keys()