from __future__ import annotations
from collections import Counter
from collections.abc import Callable, MutableMapping
from typing import TYPE_CHECKING
from passengersim_core import (
Event,
)
from passengersim.tracers.generic import GenericTracer
if TYPE_CHECKING:
from passengersim_core import SimulationEngine
from passengersim.rm.systems import RmSys
from .configured import CallbackDefinition
[docs]
class CallbackMixin:
if TYPE_CHECKING:
eng: SimulationEngine
[docs]
def initialize_sample_callback(
self, callback: Callable[[CallbackMixin], dict | None] | GenericTracer
) -> 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
Callback receiving the simulation. Returned dictionaries are stored
under ``callback_data.initialize_sample`` with trial/sample keys.
Returns
-------
Callable or GenericTracer
Registered callback, copied fresh if it is a tracer. This method
can also be used as a decorator.
"""
if not hasattr(self, "initialize_sample_callbacks"):
self.initialize_sample_callbacks = []
if isinstance(callback, GenericTracer):
callback = callback.fresh()
self.initialize_sample_callbacks.append(callback)
return callback
[docs]
def finalize_sample_callback(
self, callback: Callable[[CallbackMixin], dict | None] | GenericTracer
) -> Callable[[CallbackMixin], dict | None] | GenericTracer:
"""Register a synchronous callback after all sample events finish.
Callbacks run before sample diagnostics, departure statistics, history
rollover, and other bookkeeping, and are included in sample timing.
They run only on successful completion, not as exception cleanup.
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
Callback receiving the simulation. Returned dictionaries are stored
under ``callback_data.finalize_sample`` with trial/sample keys.
Returns
-------
Callable or GenericTracer
Registered callback, copied fresh if it is a tracer. This method
can also be used as a decorator.
"""
if not hasattr(self, "finalize_sample_callbacks"):
self.finalize_sample_callbacks = []
if isinstance(callback, GenericTracer):
callback = callback.fresh()
self.finalize_sample_callbacks.append(callback)
return callback
def _run_synchronous_callbacks(self, hook: str) -> None:
"""Dispatch a synchronous lifecycle hook without creating events."""
for callback in getattr(self, f"{hook}_callbacks", []):
result = callback(self)
if isinstance(result, dict):
self.callback_data.update_data(hook, self.eng.trial, self.eng.sample, **result)
[docs]
def end_sample_callback(self, callback: 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.
Parameters
----------
callback : Callable[[Simulation], None]
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.
"""
if not hasattr(self, "end_sample_callbacks"):
self.end_sample_callbacks = []
if isinstance(callback, GenericTracer):
callback = callback.fresh()
self.end_sample_callbacks.append(callback)
return callback
[docs]
def begin_sample_callback(self, callback: 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.
Parameters
----------
callback : Callable[[Simulation], dict | None]
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.
"""
if not hasattr(self, "begin_sample_callbacks"):
self.begin_sample_callbacks = []
if isinstance(callback, GenericTracer):
callback = callback.fresh()
self.begin_sample_callbacks.append(callback)
return callback
[docs]
def daily_callback(self, callback: Callable[[CallbackMixin, int], dict | None] | GenericTracer | RmSys):
"""Register a function to be triggered each day during a sample.
The callback function will be triggered after all RM steps when the day
coincides with a DCP.
Parameters
----------
callback : Callable[[Simulation, int], dict | None]
The callback function to register. It should accept two arguments,
which will be the Simulation object and the days_prior, and return None.
"""
if not hasattr(self, "daily_callbacks"):
self.daily_callbacks = []
if isinstance(callback, GenericTracer):
callback = callback.fresh()
self.daily_callbacks.append(callback)
return callback
[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.
Returns
-------
dict[str, list[Callable]]
Mapping of ``"<hook>_callbacks"`` to the manual callbacks for each
hook that has been used on this object.
"""
cb = {}
for hook in ["initialize_sample", "begin_sample", "daily", "end_sample", "finalize_sample"]:
if hasattr(self, f"{hook}_callbacks"):
# Preparation prepends configured registrations. Remove only
# their occurrences in this hook, not every matching callable:
# a stateless function may also be attached manually, repeatedly,
# or to another hook.
remaining = Counter(
id(callback) for when, callback in getattr(self, "_configured_attached", []) if when == hook
)
manual = []
for callback in getattr(self, f"{hook}_callbacks", []):
if remaining[id(callback)]:
remaining[id(callback)] -= 1
else:
manual.append(callback)
cb[f"{hook}_callbacks"] = manual
return cb
[docs]
def apply_callback_functions(self, sim: CallbackMixin):
callbacks = self.callback_functions()
for hook in ("initialize_sample", "finalize_sample"):
for cb in callbacks.get(f"{hook}_callbacks", []):
getattr(sim, f"{hook}_callback")(cb)
for cb in callbacks.get("begin_sample_callbacks", []):
sim.begin_sample_callback(cb)
for cb in callbacks.get("end_sample_callbacks", []):
sim.end_sample_callback(cb)
for cb in callbacks.get("daily_callbacks", []):
sim.daily_callback(cb)
[docs]
def use_registered_callbacks(self):
"""Adopt all globally registered callbacks."""
from .registration import _REGISTERED_CALLBACKS
_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) -> None:
from .configured import prepare
prepare(self)
[docs]
def add_callback_events(self):
"""Add callback events to the simulation event queue."""
dcp_hour = self.eng.config.simulation_controls.dcp_hour
configured = getattr(self, "_configured_attached", [])
manual = self.callback_functions()
# The native priority queue is not stable for ties. One event per
# timestamp dispatches configured callbacks in declaration order without
# changing their timestamps or RM event priorities.
batches = {}
for hook, callback in configured:
if hook in {"initialize_sample", "finalize_sample"}:
continue
days = (
range(self.dcp_list[0], -1, -1)
if hook == "daily"
else [self.dcp_list[0] if hook == "begin_sample" else 0]
)
for day in days:
offset = getattr(callback, "priority", 0) if hook == "daily" else 1
timestamp = int(self.eng.base_time - day * 86400 + 3600 * dcp_hour + offset)
info = (f"callback_{hook}", callback, day) if hook == "daily" else (f"callback_{hook}", callback)
batches.setdefault(timestamp, []).append(info)
for timestamp, infos in batches.items():
self.eng.add_event(Event(("configured_callbacks", tuple(infos)), timestamp))
for callback in manual.get("begin_sample_callbacks", []):
dcp = self.dcp_list[0]
# no customers can arrive within 5 seconds of a DCP.
# we want these callbacks to be triggered after the first DCP
# but before any customers can arrive, so we add one second.
event_time = int(self.eng.base_time - dcp * 86400 + 3600 * dcp_hour) + 1
rm_event = Event(
(
"callback_begin_sample",
callback,
),
event_time,
)
self.eng.add_event(rm_event)
for callback in manual.get("end_sample_callbacks", []):
# we want these callbacks to be triggered after the last DCP
# so we add one second.
event_time = int(self.eng.base_time + 3600 * dcp_hour) + 1
rm_event = Event(
(
"callback_end_sample",
callback,
),
event_time,
)
self.eng.add_event(rm_event)
for callback in manual.get("daily_callbacks", []):
day = self.dcp_list[0]
# The priority is a number of seconds before or after the overnight
# trigger time. If priority is negative, the daily 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.
priority = getattr(callback, "priority", 0)
while day >= 0:
event_time = int(self.eng.base_time - day * 86400 + 3600 * dcp_hour + priority)
rm_event = Event(("callback_daily", callback, day), event_time)
self.eng.add_event(rm_event)
day -= 1
def _weighted_mean(a, n1, b, n2):
"""Combine two weighted-mean frames, ignoring a side that carries no weight.
Arithmetic between frames aligns on the union of their indexes, so an
empty zero-weight frame (e.g. a tracer that recorded no post-burn samples)
would otherwise turn every value of the other frame into NaN.
"""
if n1 == 0 and n2 != 0:
return b.copy()
if n2 == 0:
return a.copy()
return ((a * n1) + (b * n2)) / (n1 + n2)
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):
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,
):
store = self.get_data(label, trial, sample, days_prior)
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):
if isinstance(other, CallbackData):
new = CallbackData()
for k in self._data:
try:
aggregation_process = self._data[k].attrs.get("aggregation_process", None)
except AttributeError:
aggregation_process = None
if k in other._data and aggregation_process == "wgt_by_samples":
n1 = self._data[k].attrs.get("n_samples", 1)
n2 = other._data[k].attrs.get("n_samples", 1)
new._data[k] = _weighted_mean(self._data[k], n1, other._data[k], n2)
new._data[k].attrs["n_samples"] = n1 + n2
new._data[k].attrs["aggregation_process"] = "wgt_by_samples"
if k == "segmentation_detail":
# A pooled mean is complete only where every worker
# recorded the requested scope. Unknown coverage stays unknown.
c1 = self._data[k].attrs.get("segmentation_coverage")
c2 = other._data[k].attrs.get("segmentation_coverage")
# A side with no samples contributed no data, so its
# (possibly unknown) coverage must not affect the result.
if n1 == 0 and n2 != 0:
c1 = c2
elif n2 == 0 and n1 != 0:
c2 = c1
new._data[k].attrs["segmentation_coverage"] = (
{
field: tuple(sorted(set(c1[field]) | set(c2[field])))
for field in ("missing_markets", "missing_segments")
}
if c1 is not None and c2 is not None
else None
)
elif k in other._data and aggregation_process == "wgt_by_trials":
n1 = self._data[k].attrs.get("n_trials", 1)
n2 = other._data[k].attrs.get("n_trials", 1)
new._data[k] = _weighted_mean(self._data[k], n1, other._data[k], n2)
new._data[k].attrs["n_samples"] = n1 + n2
new._data[k].attrs["aggregation_process"] = "wgt_by_trials"
else:
new._data[k] = self._data[k]
if k in other._data:
new._data[k] += other._data[k]
for k in other._data:
if k not in self._data:
new._data[k] = 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()