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.
For callbacks or collections of callbacks that will be reused, prefer the configured callback interface. Manual attachment is primarily a convenience for development and testing. The examples below start with manual attachment to make it easy to try callback functions, then show how to configure them for reuse.
import pandas as pd
import passengersim as pax
pax.versions()
passengersim 0.95
passengersim.core 0.95
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-v0.95/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, unless the callback sets a |
|
Event queue |
Each day, one second after the overnight trigger unless the callback sets a |
|
Event queue |
One second after the final DCP, unless the callback sets a |
|
Synchronous |
After all queued events and sample bookkeeping, before timing and diagnostics publication |
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 post-bookkeeping state: departure statistics have been recorded, histories
have rolled forward, database writes have been committed, choice-set data has been cleared, and
market shares have been updated. Some per-DCP counters are also cleared during history rollover; use
end_sample to inspect or modify pre-bookkeeping state. Finalizers cannot change statistics or
output already recorded. Their execution is included in sample timing, before diagnostics are
published and progress reports the sample as completed. Progress reporting is separate from the user
callback registry and includes burn-in samples. In run_single_sample(), finalization runs on
normal context exit after both the caller’s context body and 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, bookkeeping, or the single-sample context body raises an exception. If a
finalizer raises, bookkeeping has already completed and is not rolled back. 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.
Each stored row is automatically tagged with the trial and sample it came from, plus
days_prior for a daily callback. Those three key names are therefore reserved: a callback that
returns a dictionary using any of them raises a ValueError, so give such a value a different name
(for example, my_days_prior).
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}
Each day, a daily callback runs one second after the overnight trigger time. Carrier RM systems run
one second before the trigger, and the simulation’s own DCP and daily data capture happens at
the trigger, so your callback sees each day after both have finished. To run at a different moment,
give it a priority: an offset in seconds from the trigger. The sign says which side of the
simulation’s own bookkeeping the callback runs on: a positive value runs after it, and a negative
value runs before it. A value below -1 also runs before the RM systems. For example, this callback
runs before the RM systems do their daily work:
@sim.daily_callback(priority=-5)
def before_rm(sim: pax.Simulation, days_prior: int) -> dict | None: ...
The same option can be given when attaching a function directly, as in
sim.daily_callback(before_rm, priority=-5). Setting a priority attribute on the function itself
(before_rm.priority = -5) also still works; an option given when attaching takes precedence.
A priority of zero is not allowed. It would share the exact moment of the simulation’s own
bookkeeping, and the two would run in an arbitrary order, so there would be no telling whether your
callback sees the day before or after it. Attaching a daily callback with a zero priority raises a
ValueError, which says to use 1 to run after the bookkeeping or a negative value to run before it.
Because priority is read from the callback each sample, a zero set after attaching is caught too,
when the run starts. The same rule applies to tracers’ priority options and to RM systems.
A priority must also be a whole number of seconds. A value that plainly names one, such as 1.0
or the text "1", is accepted and treated as that integer. Anything else, such as 0.5, "1.5",
True, or "high", raises a ValueError rather than being rounded, because rounding could quietly
move your callback to the other side of the simulation’s bookkeeping.
The other two queued hooks accept a priority in the same way. A begin_sample callback is timed
from the first DCP of the sample, and an end_sample callback from the final DCP, on the day of
departure. The default of one second runs them after that DCP’s RM processing and bookkeeping; a
negative value runs them before the bookkeeping, and a value below -1 before the RM systems as well.
For example, this callback runs before the RM systems process the first DCP of each sample:
@sim.begin_sample_callback(priority=-5)
def before_first_dcp(sim: pax.Simulation) -> dict | None: ...
No customer arrives within five seconds of a DCP, so a begin_sample callback with a priority
from 1 to 4 still runs before the first customer of the sample; a larger value may not. Zero is
rejected for these hooks too. The synchronous initialize_sample and finalize_sample hooks are
not scheduled, so they take no priority.
Callbacks are scheduled at the start of each sample. A callback attached while a sample is running (for example, by another callback) therefore takes effect from the next sample.
When several callbacks are due at the same moment, they run in a fixed order: RM systems first, then
configured callbacks (described below) in the order they are declared, then callbacks you attached
yourself in the order you attached them. This includes callbacks on different hooks that share a
moment, such as a daily callback and an end_sample callback on the day of departure.
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. 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). By default, the dictionaries they return are merged into one shared table per hook, so the named values in the return values of each callback function must be unique, or else they will overwrite one another.
To keep a callback’s data apart, give it a name when attaching it. Its returned dictionaries are
then stored under callback_data.<name>, instead of the shared hook table, and cannot collide with
other callbacks’ keys. The skip_burn option skips the callback during burn-in samples, so it does
not need to check for them itself. Every registration method accepts name and skip_burn, and the
queued hooks (begin_sample_callback, daily_callback, and end_sample_callback) also accept
priority; they can be given with the function, or with the method used as a decorator:
@sim.end_sample_callback(name="carrier_sales", skip_burn=True)
def carrier_sales(sim: pax.Simulation) -> dict:
return {c.name: c.sold for c in sim.eng.carriers}
# ... after running:
summary.callback_data.carrier_sales
The options belong to that one attachment: the function itself is not changed, so it can be attached elsewhere with different options. A name cannot be one of the hook names, nor the result name of a tracer attached to the same simulation.
The rest of this example uses the shared tables.
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}
Trying Callback Functions on Another Simulation¶
During development and testing, you can attach the same function to another simulation by calling its hook method directly. The decorator attaches the function without otherwise modifying it. For callbacks or collections intended for reuse, prefer configured callbacks rather than repeating manual attachments.
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.59 seconds
All the usual summary data remains available for review and analysis.
summary.fig_carrier_revenues()
Removing Callbacks¶
To detach a callback, pass it to remove_callback. It is removed from every hook it was attached
to, whether or not it was attached with options. A tracer can be removed by its name, or by passing
the tracer object you attached:
sim.remove_callback(collect_carrier_revenue)
sim.remove_callback("leg_bid_prices") # a tracer, or callbacks attached with name=
The method returns the number of registrations removed, and raises a ValueError if nothing matches
(pass missing_ok=True to get 0 instead). Callbacks enabled in a configuration are removed by
disabling them there, and carrier RM systems cannot be removed. A callback removed while a sample is
running takes effect from the next sample.
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. Each run collects into its own callback_data, so running a
simulation again starts from empty tables and leaves the earlier summary unchanged.
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. The optional type field selects the registered callback or tracer.
When you omit type, PassengerSim looks up the mapping key instead.
callbacks:
segmentation_detail:
parameters:
carriers: [AL1]
segments: [business, leisure]
selected_prices:
type: leg_bid_prices
parameters:
leg_ids: [101, 111]
priority: 1
Here, selected_prices identifies the declaration and names its table in
summary.callback_data["selected_prices"]. Both tracers and functions registered with
@register_callback store their results under the declaration ID.
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 |
Earlier versions called the type field name. A declaration that still uses name loads with a
deprecation warning, as if it said type; giving both is an 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. A priority remains an offset in seconds relative to the overnight event, so
different priorities can change execution order. At exactly the same timestamp, RM systems run
first. Then the hooks run in lifecycle order: at the first DCP of a sample, every begin_sample
callback runs before any daily one, and at the final DCP every daily callback runs before any
end_sample one. Within each hook, configured callbacks run before manually attached ones. A
declared priority of zero is rejected when the run starts, before any worker process is launched.
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 |
Default result key |
|---|---|---|---|
|
daily |
Optional |
|
|
daily |
Required |
|
|
daily |
Required |
|
|
begin sample |
Required |
|
|
daily |
Required |
|
|
begin sample |
Required |
|
|
begin sample |
Required |
|
|
daily |
Required |
|
|
daily |
Required |
|
Both leg-detail tracers default to priority: 1. The bid-price detail tracer defaults to
include_sold_out: true. The last two keep every observation rather than summary statistics: one
row per trial, sample, and day, with one column per selected leg. Summaries expose them as
leg_booking_detail and leg_bid_price_detail (the distribution of the observations by day), 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.
Results saved by earlier versions, which kept the same observations as leg-<id>-sold and
leg-<id>-bidprice entries of the shared daily callback data, are read by the same summary
members.
These adapters retain the tracers’ existing burn-period filtering, aggregation, and prerequisites.
For the daily tracers, priority is the offset in seconds from the overnight trigger, as for any
daily callback: the defaults of 1 and 2 record each day after the RM systems and the simulation’s
own bookkeeping, a negative value records it before the bookkeeping, and zero is an error. For
leg_bid_price_arrays, priority is the offset from the first DCP of each sample, as for any
begin-sample callback; the forecast adapters do not expose it. You can declare the same tracer type
several times. Each declaration stores its own table under its ID. Standard plots and summary
properties look up the default result key in the catalog above. Use
summary.callback_data["your_id"] to access a custom-named table. A declaration ID must be distinct
from the result names of manual tracers and named manual callbacks. See the
two-leg example. The names initialize_sample,
begin_sample, daily, end_sample, and finalize_sample are reserved for ordinary callback
data.
Registering Custom Callbacks¶
Use the register_callback decorator to make your own callback function available by name in
configurations, and register_tracer for a tracer class. Registration does not attach anything to a
simulation: a callback runs only when a configuration declares it.
from passengersim import Simulation
from passengersim.callbacks import register_callback
@register_callback(when="end_sample", skip_burn=True)
def carrier_revenue(sim: Simulation, *, carriers: list[str] | None = None) -> dict:
return {c.name: c.revenue for c in sim.eng.carriers if carriers is None or c.name in carriers}
Then select it in YAML:
callbacks:
carrier_revenue:
parameters:
carriers: [AL1, AL2]
The function is registered under its own name, here carrier_revenue, and is returned unchanged, so
you can still call it or attach it by hand. Instead of decorating, you can also register an existing
function directly with register_callback(carrier_revenue, when="end_sample").
Arguments. The first positional parameters receive the hook’s arguments: (sim), or
(sim, days_prior) for the daily hook. Every other parameter must be keyword-only, declared after
*. These are the callback’s configuration parameters, given under parameters in a declaration.
Each needs a type annotation, which is used to validate the configured value, and keeps its default.
One without a default must be given in the configuration. Unknown parameters are rejected, so a
misspelled option is caught when the run starts. The annotations of the hook arguments and the
return value are not used, so they may name types imported only for type checking.
Options. when is required: the hook is never guessed. The other keyword options are:
Option |
Meaning |
|---|---|
|
Registry name; defaults to the function’s name (required for a lambda) |
|
Offset in seconds for a |
|
Whether burn-in samples are skipped; defaults to false |
|
Implementation version, checked when a configuration requires one; defaults to |
|
A Pydantic model for the configuration parameters, used instead of the one built from the function itself |
priority and skip_burn are fixed when the callback is registered; a configuration cannot change
them, and a configuration parameter cannot use either name. A priority follows the usual rules for
queued callbacks: a whole number of seconds other than zero. The synchronous initialize_sample and
finalize_sample hooks have no priority, so giving one is an error.
A parameters_model must declare extra="forbid" and have exactly one field for each keyword-only
parameter. It then decides the types, defaults, and required parameters of configured runs, even
where these differ from the function’s own: every field’s value, including its default, is passed to
the function. Use one to document the options, or to validate them in ways an annotation cannot.
Results. Dictionaries returned by a registered callback are stored under the declaration’s ID,
not the shared hook key. In the example above, they are in callback_data.carrier_revenue. This
lets one function be declared several times with different parameters:
callbacks:
al1_revenue:
type: carrier_revenue
parameters:
carriers: [AL1]
al2_revenue:
type: carrier_revenue
parameters:
carriers: [AL2]
These produce callback_data.al1_revenue and callback_data.al2_revenue. A declaration ID cannot
be one of the hook names, and cannot be the same as a tracer’s result name or a named manual
callback’s.
Important
The registration options apply only when the callback runs from a configuration. Attaching the same
function by hand, as with sim.end_sample_callback(carrier_revenue), follows the ordinary rules for
manual callbacks: it runs at the default priority, during burn-in samples too, with its own default
parameter values, and stores its results under the hook’s name (here end_sample). Give those
options to the attaching method if you need them there.
What can be registered. register_callback accepts plain functions only. A tracer class or
instance, any other class, a callable object, a functools.partial, a method, and a coroutine or
generator function are all refused with an error explaining what to use instead. Callable objects
are refused because they can carry state from one simulation into another. A callback that needs to
accumulate state across a run should be a tracer, which is copied fresh for every run.
Registering again. Re-running a notebook cell, or reloading a module, registers the same function again. This replaces the earlier registration, as long as it is the same module-level function. Any other use of a registered name is an error, so two different callbacks can never silently share a name. A replacement takes effect the next time a simulation prepares to run, even for a simulation object that has run before.
Registering Tracers¶
For a GenericTracer subclass, declare its configuration on the class, beside the constructor it
describes, and register the class with register_tracer, which also works as a class decorator:
from typing import ClassVar, Literal
from pydantic import BaseModel
from passengersim.callbacks import register_tracer
from passengersim.tracers.generic import GenericTracer
class MyTracerOptions(BaseModel, extra="forbid"):
leg_ids: list[int]
priority: int = 1 # Same default as the constructor.
@register_tracer
class MyTracer(GenericTracer):
name = "my_tracer" # Default result key when attached manually.
hook: ClassVar[Literal["begin_sample", "daily", "end_sample"]] = "daily"
skip_burn: ClassVar[bool] = True # The simulation skips burn-in samples for you.
options_model: ClassVar[type[BaseModel]] = MyTracerOptions
options_version: ClassVar[str] = "1"
def __init__(self, leg_ids: list[int], *, priority: int = 1, name: str | None = None) -> None:
self.leg_ids = leg_ids
self.priority = priority
self._set_name(name) # Optional instance-level result key.
self.reset()
# reset(), __call__(), and finalize() as for any tracer.
register_tracer accepts only GenericTracer subclasses; a function, or a tracer instance, is
refused with an error naming the right decorator. A tracer written with hook methods (see
Writing a Tracer) leaves out hook, and is attached to every hook
whose method it defines. A configured tracer is built as MyTracer(**validated_options) and uses
the declared hooks, options model, and version. Its declaration ID names its result table. If the
class declares no options_model, one is built from the constructor’s signature: each keyword
parameter becomes an option, with its annotation as the type and its default, except name (a
configured tracer always uses its declaration ID). Declare the model yourself to document the
options, or when the constructor takes *args or **kwargs. Keep the options model’s fields and
defaults identical to the constructor’s, and bump options_version when the tracer’s results change
meaning. @register_tracer(parameters_model=..., version=...) overrides the class attributes, and
name= registers an alternative type name. GenericTracer provides attach(), which uses the
declared hook, and fresh(), which returns a reset deep copy. A tracer that overrides fresh()
must preserve its parameters; its instance name is re-applied by the simulation when it is attached.
Registering the same module-level class again replaces the earlier registration, as for callbacks.
Each built-in tracer uses @register_tracer on the class that declares its config name and options.
Importing passengersim.callbacks loads these tracers so their names are available in YAML.
Callback Factories¶
register_callback_factory and register_tracer_factory register a factory: a function that
receives one validated Pydantic model and returns a fresh callback for each run. They remain
available, and are useful when a callback needs per-run setup kept in closure state. Unlike the
decorators, every factory name is unique, and registering one again is an error, even for the same
implementation; there is no replacement. 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",
)
Daily callbacks accept (sim, days_prior); begin/end-sample callbacks accept (sim). Return a
dictionary to collect ordinary callback data, or None. A factory-built callback stores its results
under the shared hook key (here end_sample), not the declaration ID. Stateful factories must
construct independent instances. register_tracer_factory(MyTracer) registers a tracer class
exactly as register_tracer does, except for the rule on registering again.
For a general factory returning a tracer, supply output_name equal to the tracer’s canonical name;
this identifies the factory as producing a tracer. The configured instance receives its declaration
ID as its name. Such a factory may pass when=None, so that the tracer it returns is attached to
the hooks it declares itself.
Registered callbacks, tracers, and factories 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.
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 type 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.
Migrating Global Callback Registration¶
The process-global callback attachment APIs are deprecated and emit DeprecationWarning:
use_registered_callbacks()register_initialize_sample_callbackregister_begin_sample_callbackregister_daily_callbackregister_end_sample_callbackregister_finalize_sample_callback
They continue to work during deprecation, including decorator options and tracer attachment. Importing these APIs does not warn; calling them does.
The preferred replacement for reusable callbacks and collections of callbacks is the configured
callback interface. Register a callback function with register_callback, or a tracer class with
register_tracer, and select it through config.callbacks. Despite the similar names, these differ
from the deprecated register_*_callback functions: they make a callback available to
configurations, and attach nothing to any simulation by themselves. Keep a collection’s declarations
together in configuration so it can be reused and adjusted across runs and experiments. See
Configured Callbacks and
Registering Custom Callbacks for examples.
The registration functions, including register_callback_factory and register_tracer_factory, are
not deprecated: they make definitions available, while configuration explicitly selects which
callbacks execute. After migrating your global registrations to configured callbacks, remove
sim.use_registered_callbacks().
Manual attachment is primarily for development and testing. For that workflow, replace a global
decorator with the corresponding simulation method, such as @sim.end_sample_callback or
@sim.daily_callback(skip_burn=True), and remove sim.use_registered_callbacks(). If a development
or test setup needs several manual callbacks, an explicit CallbackMixin bundle with
bundle.apply_callback_functions(sim) is also supported. Use configured callbacks when turning that
setup into a reusable collection.
Choosing an Approach¶
Configured callbacks |
Manual attachment |
|
|---|---|---|
Recommended use |
Reusable callbacks and callback collections |
Development and testing convenience |
Definition |
Registered function or tracer class |
Callable or tracer in Python |
Activation |
Enable via configuration |
Attach to an individual object |
Parameters |
Per-config options |
Python code |
Experiments and overlays |
Adjust declarations by key |
Python attachment |
Included in cache identity |
Yes (explicit config only) |
No |
Prefer configured callbacks whenever a callback or collection will be reused. Manual attachment makes it convenient to develop and test callback implementations before registering them for configuration. You can mix these approaches while developing or testing. Configured/manual tracer output collisions raise an error before execution, so you’ll be warned promptly if you’ve made a mistake.