Callbacks¶
PassengerSim includes a variety of optimized data collection processes that run automatically during a simulation, but these pre-selected data may not be sufficient for every analysis. To supplement this, users can choose to additionally collect any other data while running a simulation. This is done by writing a “callback” function. Such a function is invoked regularly while the simulation is running, and can inspect and store almost anything from the Simulation object.
import pandas as pd
import passengersim as pax
pax.versions()
passengersim 0.95.dev13+g237281526
passengersim.core 0.94
Here, we’ll run a quick demo using the “3MKT” example model. We’ll give AL1 the ‘P’ RM system to make it interesting.
cfg = pax.Config.from_yaml(pax.demo_network("3MKT"))
cfg.simulation_controls.num_samples = 100
cfg.simulation_controls.burn_samples = 50
cfg.simulation_controls.num_trials = 1
cfg.db = None
cfg.outputs.reports.clear()
cfg.carriers.AL1.rm_system = "P"
sim = pax.Simulation(cfg)
/Users/jpn/Git/pax/packages/passengersim-public/src/passengersim/config/manipulate.py:49: UserWarning: Only 50 usable samples remain after burning 50 of 100 samples across 1 trials; at least 750 usable samples are recommended to ensure meaningful results.
schema_validator.validate_python(model.__dict__)
Types of Callback Functions¶
To collect data, we can write a function that will interrogate the simulation and grab whatever info we are looking for. There are five lifecycle hooks:
Hook |
Execution |
Timing |
|---|---|---|
|
Synchronous |
After the sample number, random seed, and counters are initialized, before demand generation |
|
Event queue |
One second after the first DCP, after its RM processing |
|
Event queue |
Each day, at the existing callback priority offset from the overnight trigger |
|
Event queue |
One second after the final DCP |
|
Synchronous |
After all queued events, before sample diagnostics, departure statistics, history rollover, and bookkeeping |
Use initialize_sample to modify demand inputs such as base_demand for the current sample. RM
steps have not yet run for that sample; use begin_sample to inspect its initial forecasts and bid
prices instead. With simulation_controls.skip_demand_generation=True, an initializer must set
scenario_demand and add booking events (for example, with sim.eng.add_booking_event). RM and
queued callback events are still generated normally.
finalize_sample sees the completed sample before history rollover. Its execution is included in
sample timing, and changes it makes are visible to subsequent bookkeeping. It cannot change output
already recorded during event processing. In run_single_sample(), it runs on normal context exit
after the caller’s context body and before bookkeeping.
Both synchronous hooks run in registration order, with configured callbacks before manual callbacks.
Event priority does not apply to them. They run during burn-in too, and callback exceptions
propagate. Finalization is a successful-completion hook, not exception cleanup; it does not run if
sample processing or the single-sample context body raises an exception. Finalizers should not
enqueue events: sample event processing has already finished.
All hooks except daily accept one argument (the Simulation object), and either return nothing
(to ignore that invocation) or return a dictionary of values to store, where the keys are all
strings naming what’s being stored and the values can be whatever is of interest. This can be a
simple numeric value (i.e., a scalar), or a tuple, an array, a nested dictionary, or any other
pickle-able
Python object.
We can attach each callback to the Simulation by using a Python decorator.
Example Callback Functions¶
For example, here we create a callback to collect carrier revenue at the end of every sample. Note that we skip the burn period by returning nothing for those samples; this is not required by the callback algorithm but is good practice for analysis.
@sim.end_sample_callback
def collect_carrier_revenue(sim: pax.Simulation) -> dict | None:
if sim.eng.sample < sim.eng.burn_samples:
return
return {c.name: c.revenue for c in sim.eng.carriers}
The daily callback operates similarly, except it accepts a second argument that gives the number of days prior to departure for this day. You don’t need to use the second argument in the callback function, but you need to including in the function signature (and you can use it if desired, e.g. to collect data only at DCPs instead of every day). In the example here, we collect daily carrier revenue, but only every 7th sample, which is a good way to reduce the overhead from collecting detailed data.
@sim.daily_callback
def collect_carrier_revenue_detail(
sim: pax.Simulation, days_prior: int
) -> dict | None:
if sim.eng.sample < sim.eng.burn_samples:
return
if sim.eng.sample % 7 == 0:
return {c.name: c.revenue for c in sim.eng.carriers}
Use the queued begin_sample hook to inspect RM state once per sample, after the first DCP:
@sim.begin_sample_callback
def grab_initial_forecasts(sim: pax.Simulation) -> dict:
return {"path-1": sim.eng.paths.select(path_id=1).get_forecast_data()}
The synchronous hooks use the same decorator interface:
@sim.initialize_sample_callback
def initialize_inputs(sim: pax.Simulation) -> dict:
return {"base_demand": sum(d.base_demand for d in sim.eng.demands)}
@sim.finalize_sample_callback
def collect_completed_sample(sim: pax.Simulation) -> dict:
return {"sold": sum(leg.sold for leg in sim.eng.legs)}
Returned data is available under callback_data.initialize_sample and
callback_data.finalize_sample, tagged with the current trial and sample. The corresponding global
decorators are register_initialize_sample_callback and register_finalize_sample_callback.
Configured callback factories can select either hook with when="initialize_sample" or
when="finalize_sample", including in multiprocessing runs.
Multiple callbacks of the same kind can be attached (i.e. there can be two end_sample callbacks). The only limitation is that the named values in the return values of each callback function must be unique, or else they will overwrite one another.
For example, suppose we also want to count for each carrier the number of passengers departing each airport on each sample day. The previous end sample callback stored revenue values in a dictionary keyed by carrier name, so if we don’t want to overwrite that, we need to use a different key. One way to avoid that is to just nest the output of the callback function in another dictionary with a unique top level key.
from collections import defaultdict
@sim.end_sample_callback
def collect_passenger_counts(sim: pax.Simulation) -> dict | None:
if sim.eng.sample < sim.eng.burn_samples:
return
paxcount = defaultdict(lambda: defaultdict(int))
for leg in sim.eng.legs:
paxcount[leg.carrier.name][leg.orig] += leg.sold
# convert defaultdict to a regular dict, not necessary but pickles smaller
paxcount = {
carrier: dict(airports) for carrier, airports in paxcount.items()
}
return {"psgr_by_airport": paxcount}
One of the nifty features of callbacks is that they can access anything available in the simulation, not just sales and revenue data from carriers. For example, we can inspect demand objects directly, and see how many potential passengers were simulated so far, and how many didn’t make a booking on any airlines (i.e. the “no-go” customers).
@sim.daily_callback
def count_nogo(sim: pax.Simulation, days_prior: int) -> dict | None:
if sim.eng.sample < sim.eng.burn_samples:
return
if sim.eng.sample % 7 == 0:
return
if days_prior > 0 and days_prior not in sim.config.dcps:
# Only count "nogo" (unsold) demand at DCPs, and at departure (days_prior == 0)
return
nogo_count = defaultdict(lambda: defaultdict(lambda: defaultdict(int)))
for dmd in sim.eng.demands:
nogo_count[dmd.orig][dmd.dest][dmd.segment] += dmd.unsold
# convert defaultdict to a regular dict, not necessary but pickles smaller
nogo_count = {
orig: {dest: dict(seg) for dest, seg in dests.items()}
for orig, dests in nogo_count.items()
}
return {"nogo": nogo_count}
Re-using Callback Functions¶
Attaching via the decorators is a convenient way to add callbacks to a single simulation. The decorators connect the callback function to the simulation, but do not otherwise modify the function itself. It is easy to define callback functions in a seperate module or to re-use callback functions for multiple simulations, by using the decorator as a regular function. For example, we can create a second simulation object, and attach the same callback functions like this:
duplicate_sim = pax.Simulation(cfg)
duplicate_sim.end_sample_callback(collect_carrier_revenue)
duplicate_sim.daily_callback(collect_carrier_revenue_detail)
<function __main__.collect_carrier_revenue_detail(sim: passengersim.driver._singleproc.Simulation, days_prior: int) -> dict | None>
In this example, the duplicate_sim is running the same config as the original, but this would work with a modified config or even a completely different network.
Once we have attached all desired callbacks to the simulation we want to run, we can run it as normal.
summary = sim.run()
Task Completed after 0.70 seconds
All the usual summary data remains available for review and analysis.
summary.fig_carrier_revenues()
Callback Data¶
In addition to the usual suspects, the summary object includes the collected callback data from our callback functions.
summary.callback_data
<passengersim.callbacks.base.CallbackData from daily, end_sample>
Because we connected a “daily” callback, the data we collected is available under the
callback_data.daily accessor.
summary.callback_data.daily[:5]
[{'trial': 0,
'sample': 50,
'days_prior': 63,
'nogo': {'BOS': {'ORD': {'business': 0, 'leisure': 0},
'LAX': {'business': 0, 'leisure': 0}},
'ORD': {'LAX': {'business': 0, 'leisure': 0}}}},
{'trial': 0,
'sample': 50,
'days_prior': 56,
'nogo': {'BOS': {'ORD': {'business': 0, 'leisure': 0},
'LAX': {'business': 0, 'leisure': 0}},
'ORD': {'LAX': {'business': 0, 'leisure': 0}}}},
{'trial': 0,
'sample': 50,
'days_prior': 49,
'nogo': {'BOS': {'ORD': {'business': 0, 'leisure': 0},
'LAX': {'business': 0, 'leisure': 0}},
'ORD': {'LAX': {'business': 0, 'leisure': 0}}}},
{'trial': 0,
'sample': 50,
'days_prior': 42,
'nogo': {'BOS': {'ORD': {'business': 0, 'leisure': 0},
'LAX': {'business': 0, 'leisure': 0}},
'ORD': {'LAX': {'business': 0, 'leisure': 0}}}},
{'trial': 0,
'sample': 50,
'days_prior': 35,
'nogo': {'BOS': {'ORD': {'business': 0, 'leisure': 0},
'LAX': {'business': 0, 'leisure': 0}},
'ORD': {'LAX': {'business': 0, 'leisure': 0}}}}]
As you might expect, the “begin_sample” or “end_sample” callbacks are available under
callback_data.begin_sample or callback_data.end_sample, respectively.
summary.callback_data.end_sample[:3]
[{'trial': 0,
'sample': 50,
'AL1': 110775.0,
'AL2': 95975.0,
'psgr_by_airport': {'AL1': {'BOS': 191.0, 'ORD': 240.0},
'AL2': {'BOS': 149.0, 'ORD': 240.0}}},
{'trial': 0,
'sample': 51,
'AL1': 101025.0,
'AL2': 100225.0,
'psgr_by_airport': {'AL1': {'BOS': 197.0, 'ORD': 240.0},
'AL2': {'BOS': 194.0, 'ORD': 240.0}}},
{'trial': 0,
'sample': 52,
'AL1': 100450.0,
'AL2': 97825.0,
'psgr_by_airport': {'AL1': {'BOS': 198.0, 'ORD': 240.0},
'AL2': {'BOS': 161.0, 'ORD': 240.0}}}]
The callback data can include pretty much anything, so it is stored in a very flexible (but
inefficient) format: a list of dict’s. If the content of the dicts is fairly simple (numbers,
tuples, lists, or nested dictionaries thereof), it can be converted into a pandas DataFrame using
the to_dataframe method on the callback_data attribute. This may make subsequent analysis
easier.
summary.callback_data.to_dataframe("daily")
| trial | sample | days_prior | nogo.BOS.ORD.business | nogo.BOS.ORD.leisure | nogo.BOS.LAX.business | nogo.BOS.LAX.leisure | nogo.ORD.LAX.business | nogo.ORD.LAX.leisure | AL1 | AL2 | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 0 | 50 | 63 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN |
| 1 | 0 | 50 | 56 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN |
| 2 | 0 | 50 | 49 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN |
| 3 | 0 | 50 | 42 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN |
| 4 | 0 | 50 | 35 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 1174 | 0 | 99 | 7 | 0.0 | 5.0 | 0.0 | 10.0 | 0.0 | 11.0 | NaN | NaN |
| 1175 | 0 | 99 | 5 | 0.0 | 6.0 | 0.0 | 15.0 | 0.0 | 14.0 | NaN | NaN |
| 1176 | 0 | 99 | 3 | 0.0 | 9.0 | 0.0 | 20.0 | 0.0 | 23.0 | NaN | NaN |
| 1177 | 0 | 99 | 1 | 2.0 | 11.0 | 8.0 | 26.0 | 2.0 | 28.0 | NaN | NaN |
| 1178 | 0 | 99 | 0 | 3.0 | 12.0 | 8.0 | 28.0 | 2.0 | 31.0 | NaN | NaN |
1179 rows × 11 columns
summary.callback_data.to_dataframe("end_sample")
| trial | sample | AL1 | AL2 | psgr_by_airport.AL1.BOS | psgr_by_airport.AL1.ORD | psgr_by_airport.AL2.BOS | psgr_by_airport.AL2.ORD | |
|---|---|---|---|---|---|---|---|---|
| 0 | 0 | 50 | 110775.0 | 95975.0 | 191.0 | 240.0 | 149.0 | 240.0 |
| 1 | 0 | 51 | 101025.0 | 100225.0 | 197.0 | 240.0 | 194.0 | 240.0 |
| 2 | 0 | 52 | 100450.0 | 97825.0 | 198.0 | 240.0 | 161.0 | 240.0 |
| 3 | 0 | 53 | 105000.0 | 101800.0 | 200.0 | 234.0 | 200.0 | 233.0 |
| 4 | 0 | 54 | 96550.0 | 90450.0 | 170.0 | 240.0 | 138.0 | 240.0 |
| 5 | 0 | 55 | 106175.0 | 103600.0 | 196.0 | 239.0 | 181.0 | 240.0 |
| 6 | 0 | 56 | 106150.0 | 98325.0 | 193.0 | 240.0 | 155.0 | 240.0 |
| 7 | 0 | 57 | 72650.0 | 70375.0 | 153.0 | 154.0 | 171.0 | 161.0 |
| 8 | 0 | 58 | 105800.0 | 103175.0 | 200.0 | 237.0 | 200.0 | 237.0 |
| 9 | 0 | 59 | 70125.0 | 74500.0 | 119.0 | 168.0 | 134.0 | 182.0 |
| 10 | 0 | 60 | 110875.0 | 105850.0 | 200.0 | 239.0 | 200.0 | 240.0 |
| 11 | 0 | 61 | 86675.0 | 93825.0 | 169.0 | 216.0 | 172.0 | 230.0 |
| 12 | 0 | 62 | 102500.0 | 95575.0 | 191.0 | 224.0 | 182.0 | 235.0 |
| 13 | 0 | 63 | 105150.0 | 108200.0 | 200.0 | 237.0 | 200.0 | 240.0 |
| 14 | 0 | 64 | 101625.0 | 93975.0 | 200.0 | 215.0 | 200.0 | 190.0 |
| 15 | 0 | 65 | 89150.0 | 84075.0 | 198.0 | 204.0 | 200.0 | 192.0 |
| 16 | 0 | 66 | 70825.0 | 72400.0 | 130.0 | 169.0 | 168.0 | 181.0 |
| 17 | 0 | 67 | 94325.0 | 95125.0 | 159.0 | 235.0 | 154.0 | 240.0 |
| 18 | 0 | 68 | 78000.0 | 86425.0 | 162.0 | 191.0 | 173.0 | 208.0 |
| 19 | 0 | 69 | 97675.0 | 96450.0 | 197.0 | 225.0 | 199.0 | 223.0 |
| 20 | 0 | 70 | 98750.0 | 104125.0 | 185.0 | 230.0 | 200.0 | 239.0 |
| 21 | 0 | 71 | 77100.0 | 81400.0 | 151.0 | 170.0 | 161.0 | 191.0 |
| 22 | 0 | 72 | 108825.0 | 105550.0 | 199.0 | 239.0 | 199.0 | 240.0 |
| 23 | 0 | 73 | 113975.0 | 105250.0 | 200.0 | 239.0 | 200.0 | 240.0 |
| 24 | 0 | 74 | 59250.0 | 57275.0 | 131.0 | 165.0 | 133.0 | 181.0 |
| 25 | 0 | 75 | 70375.0 | 75125.0 | 171.0 | 155.0 | 169.0 | 176.0 |
| 26 | 0 | 76 | 89925.0 | 95275.0 | 157.0 | 201.0 | 179.0 | 227.0 |
| 27 | 0 | 77 | 102850.0 | 99400.0 | 164.0 | 240.0 | 170.0 | 240.0 |
| 28 | 0 | 78 | 80225.0 | 71300.0 | 125.0 | 192.0 | 113.0 | 191.0 |
| 29 | 0 | 79 | 105225.0 | 105825.0 | 197.0 | 240.0 | 186.0 | 240.0 |
| 30 | 0 | 80 | 82200.0 | 84775.0 | 191.0 | 198.0 | 188.0 | 211.0 |
| 31 | 0 | 81 | 92375.0 | 83775.0 | 200.0 | 218.0 | 200.0 | 176.0 |
| 32 | 0 | 82 | 91350.0 | 85200.0 | 187.0 | 202.0 | 186.0 | 198.0 |
| 33 | 0 | 83 | 94075.0 | 95700.0 | 200.0 | 223.0 | 200.0 | 215.0 |
| 34 | 0 | 84 | 88500.0 | 81300.0 | 168.0 | 185.0 | 168.0 | 175.0 |
| 35 | 0 | 85 | 104200.0 | 97075.0 | 174.0 | 240.0 | 156.0 | 240.0 |
| 36 | 0 | 86 | 79375.0 | 90275.0 | 128.0 | 164.0 | 147.0 | 196.0 |
| 37 | 0 | 87 | 78925.0 | 86100.0 | 177.0 | 163.0 | 196.0 | 192.0 |
| 38 | 0 | 88 | 85375.0 | 85025.0 | 127.0 | 204.0 | 129.0 | 200.0 |
| 39 | 0 | 89 | 87900.0 | 102900.0 | 144.0 | 200.0 | 168.0 | 231.0 |
| 40 | 0 | 90 | 96050.0 | 90075.0 | 163.0 | 239.0 | 132.0 | 240.0 |
| 41 | 0 | 91 | 86075.0 | 85350.0 | 157.0 | 191.0 | 164.0 | 192.0 |
| 42 | 0 | 92 | 68100.0 | 82725.0 | 117.0 | 172.0 | 140.0 | 193.0 |
| 43 | 0 | 93 | 67125.0 | 71525.0 | 136.0 | 155.0 | 166.0 | 160.0 |
| 44 | 0 | 94 | 85025.0 | 80825.0 | 183.0 | 177.0 | 168.0 | 170.0 |
| 45 | 0 | 95 | 109325.0 | 108325.0 | 198.0 | 240.0 | 200.0 | 240.0 |
| 46 | 0 | 96 | 97700.0 | 90675.0 | 185.0 | 240.0 | 160.0 | 240.0 |
| 47 | 0 | 97 | 103900.0 | 100650.0 | 186.0 | 239.0 | 186.0 | 240.0 |
| 48 | 0 | 98 | 106075.0 | 104250.0 | 179.0 | 239.0 | 200.0 | 233.0 |
| 49 | 0 | 99 | 82300.0 | 79475.0 | 176.0 | 203.0 | 177.0 | 212.0 |
Users are free to process this callback data now however they like, with typical Python tools: analyze, visualize, interpret, etc.
# Visualize revenue difference between carriers across booking curve
import altair as alt
alt.Chart(
summary.callback_data.to_dataframe("daily").eval("DIFF = AL1 - AL2")
).mark_line().encode(
x=alt.X("days_prior", scale=alt.Scale(reverse=True)),
y="DIFF",
color="sample:N",
)
# Visualize "nogo" passengers over time, by market and segment
nogo = (
summary.callback_data.to_dataframe("daily")
.set_index(["days_prior", "sample"])
.drop(columns=["trial", "AL1", "AL2"])
)
nogo.columns = pd.MultiIndex.from_tuples(nogo.columns.str.split(".").to_list())
nogo.columns.names = ["nogo", "orig", "dest", "segment"]
nogo = nogo.stack([1, 2, 3], future_stack=True).dropna().reset_index()
mean_nogo = (
nogo.groupby(["days_prior", "orig", "dest", "segment"])
.nogo.mean()
.reset_index()
)
mean_nogo["market"] = mean_nogo.orig + "-" + mean_nogo.dest
alt.Chart(mean_nogo).mark_line().encode(
x=alt.X("days_prior", scale=alt.Scale(reverse=True)),
y="nogo",
color="segment:N",
strokeWidth="market:N",
strokeDash="market:N",
)
Configured Callbacks¶
Use the top-level callbacks mapping to select predefined callbacks in configurations, either in
the YAML or Python format. Each mapping key identifies a declaration of a callback that will be
triggered during simulation. Its registry name defaults to that key; use name when the declaration
ID differs from the registered implementation.
callbacks:
segmentation_detail:
parameters:
carriers: [AL1]
segments: [business, leisure]
selected_prices:
name: leg_bid_prices
parameters:
leg_ids: [101, 111]
priority: 1
You can load this configuration with Config.from_yaml, or modify an existing Config object in
Python to add callbacks. This config can then be passed to Simulation, MultiSimulation, or
Experiments. No Python attachment call is necessary. Callbacks are constructed during run
preparation, with fresh state for each simulation and each multi-sim trial worker. A single
Simulation running several trials retains a tracer’s existing accumulation across those trials.
Option |
Meaning |
|---|---|
|
Registered implementation; defaults to the declaration ID |
|
Explicit JSON-compatible constructor/factory options; defaults to |
|
Whether to attach this callback; defaults to |
|
Optional required implementation version; mismatch is a run-time validation error |
You can edit sim.config.callbacks before calling run(), including nested parameters. Changed
declarations are revalidated before execution; unchanged ones can reuse validation. Callback strings
pass through verbatim, without the format-tag expansion applied elsewhere in the config. This allows
braces in regular expressions and label templates.
Declarations merge by key when loading YAML overlays. For example, this overlay disables segmentation and changes the selected leg IDs without restating the other declarations:
callbacks:
segmentation_detail:
enabled: false
selected_prices:
parameters:
leg_ids: [101]
Existing keys retain their positions; new keys append in overlay order. Saving and reloading a
config preserves declaration order. At the same event time, configured callbacks execute in
declaration order. Daily priority remains an offset in seconds relative to the overnight event, so
different priorities can change execution order. Ordering relative to manual or RM events at exactly
the same timestamp retains the existing scheduler behavior; use the established priority options
when timing relative to RM updates matters.
Built-in Catalog¶
Built-ins callbacks and tracers (those that are part of the PassengerSim library) are per-registered for use, and do not require the user to register them:
Registry name |
Hook |
Parameters |
Result key |
|---|---|---|---|
|
daily |
Optional |
|
|
daily |
Required |
|
|
daily |
Required |
|
|
begin sample |
Required |
|
|
daily |
Required |
|
|
begin sample |
Required |
|
|
begin sample |
Required |
|
|
daily |
Required |
|
|
daily |
Required |
|
The last two are plain daily callbacks rather than tracers. They add leg-<id>-sold and
leg-<id>-bidprice entries to the shared daily callback data, which summaries expose as
leg_booking_detail and leg_bid_price_detail, with the figures fig_leg_booking_detail_rake,
fig_leg_bid_price_detail_rake, and fig_leg_bid_price_history. These summary members are always
available; no extra import is needed.
These adapters retain the tracers’ existing burn-period filtering, aggregation, and prerequisites.
Begin-sample adapters do not expose priority, which has no effect for that hook. Two configured
tracers cannot write the same result key, even under different declaration IDs or registry aliases.
A configured tracer also cannot share an output name with a manually or globally attached tracer.
Output renaming is not supported. The names initialize_sample, begin_sample, daily,
end_sample, and finalize_sample are reserved for ordinary callback data.
Custom Callback Factories¶
Use register_callback_factory or register_tracer_factory to register a custom callback or tracer
implementation. Registration makes it available by name in the configurations; it does not attach it
to simulations unless called for. Every name is unique, and repeated registration raises an error,
even for the same implementation. There is no replacement operation.
Factories receive one validated Pydantic model and return a fresh callable. Use extra="forbid" on
the parameter model to catch misspelled options. For example:
from collections.abc import Callable
from functools import partial
from pydantic import BaseModel
from passengersim import Simulation
from passengersim.callbacks import register_callback_factory
class RevenueOptions(BaseModel, extra="forbid"):
skip_burn: bool = True
def collect_revenue(sim: Simulation, *, skip_burn: bool) -> dict | None:
if skip_burn and sim.eng.sample < sim.eng.burn_samples:
return None
return {"carrier_revenue": {c.name: c.revenue for c in sim.eng.carriers}}
def make_revenue_callback(options: RevenueOptions) -> Callable:
return partial(collect_revenue, skip_burn=options.skip_burn)
register_callback_factory(
"my_carrier_revenue",
factory=make_revenue_callback,
when="end_sample",
parameters_model=RevenueOptions,
version="1",
)
Then select it in YAML:
callbacks:
my_carrier_revenue:
parameters:
skip_burn: true
Daily callbacks accept (sim, days_prior); begin/end-sample callbacks accept (sim). Return a
dictionary to collect ordinary callback data, or None. Stateful factories must construct
independent instances. Custom definitions are transported to multi-sim workers with the existing
dill-based mechanism; they must be serializable, and their dependencies must be available to
workers. YAML contains only names and options, not Python code or arbitrary import expressions.
For a GenericTracer subclass, declare its configuration on the class, beside the constructor it
describes, and register the class with the helper:
from typing import ClassVar, Literal
from pydantic import BaseModel
from passengersim.callbacks import register_tracer_factory
from passengersim.tracers.generic import GenericTracer
class MyTracerOptions(BaseModel, extra="forbid"):
leg_ids: list[int]
priority: int = 1 # Same default as the constructor.
class MyTracer(GenericTracer):
name = "my_tracer" # Canonical result key in callback_data.
hook: ClassVar[Literal["begin_sample", "daily", "end_sample"]] = "daily"
options_model: ClassVar[type[BaseModel]] = MyTracerOptions
options_version: ClassVar[str] = "1"
def __init__(self, leg_ids: list[int], *, priority: int = 1) -> None: ...
# reset(), fresh(), attach(), __call__(), and finalize() as for any tracer.
register_tracer_factory(MyTracer)
The helper calls MyTracer(**validated_options) and uses the declared hook, result name, options
model, and version. Keep the options model’s fields and defaults identical to the constructor’s, and
bump options_version when the tracer’s results change meaning. parameters_model= and version=
arguments override the class attributes, and name= registers an alias without renaming the output.
The tracer’s fresh() must preserve its output name and parameters, and its manual attach()
should use the same hook.
For a general factory returning a tracer, supply output_name equal to the tracer’s canonical name;
this allows collision checks before workers start.
The built-in catalog follows the same pattern: each tracer declares its options on its class, and
passengersim.callbacks.builtins only lists what is registered and under which names.
Caching and Saved Configurations¶
Configured callbacks participate in cache identity and experiment reuse through explicit
configuration only, including declaration order and disabled entries. Omitted options remain
omitted in saved configs. Explicit enabled: true and a name equal to the declaration ID are
retained when saving, because overlays may need them to override an inherited value. After overlays
are merged, these defaults are normalized only for cache identity and experiment reuse. Ordinary
find_differences() reports explicit differences; its normalize_callbacks=True option applies the
same reuse normalization without changing either config. Missing callback configs match other
missing configs, and an empty mapping is omitted to preserve existing cache hashes for configs
without callbacks.
Registered implementation versions and parameter defaults are not compared. Changing callback code,
a registered version, or a default alone therefore does not invalidate a cache. Change an explicit
config value or bypass reuse when those changes should take effect. An explicitly supplied YAML
version is compared like any other config value and checked against the registry when a new run is
prepared. Existing explicit cache-key and experiment reuse overrides still apply.
Callback declarations and collected data survive saved-result round trips. Older PassengerSim
versions can read configs without callback declarations, but cannot load configs containing the new
callbacks field.
Choosing an Approach¶
Manual attachment |
Configured callbacks |
|
|---|---|---|
Definition |
Callable or tracer in Python |
Named factory and parameter model |
Activation |
Attach to an individual object |
Enable via configuration |
Parameters |
Python code |
Per-config options |
Experiments and overlays |
Python attachment |
Adjust declarations by key |
Included in cache identity |
No |
Yes (explicit config only) |
Use configured callbacks for collection reused across runs, experiments, or caches. Manual attachment is convenient for one-off notebook work. You can also mix these approaches. Configured/manual tracer output collisions raise an error before execution, so you’ll be warned promptly if you’ve made a mistake.