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

initialize_sample

Synchronous

After the sample number, random seed, and counters are initialized, before demand generation

begin_sample

Event queue

One second after the first DCP, after its RM processing, unless the callback sets a priority

daily

Event queue

Each day, one second after the overnight trigger unless the callback sets a priority

end_sample

Event queue

One second after the final DCP, unless the callback sets a priority

finalize_sample

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

type

Registered implementation; defaults to the declaration ID

parameters

Explicit JSON-compatible constructor/factory options; defaults to {}

enabled

Whether to attach this callback; defaults to true

version

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

segmentation_detail

daily

Optional markets, carriers, segments, priority (default 1)

segmentation_detail

leg_bid_prices

daily

Required leg_ids; optional priority (default 1)

leg_bid_prices

path_bid_prices

daily

Required path_ids; optional priority (default 1)

path_bid_prices

leg_bid_price_arrays

begin sample

Required leg_ids; optional priority (default 1)

leg_bid_price_arrays

leg_bid_price_vectors

daily

Required leg_ids; optional priority (default 2)

leg_bid_price_vectors

selected_leg_forecasts

begin sample

Required leg_ids

selected_leg_forecasts

selected_path_forecasts

begin sample

Required path_ids

selected_path_forecasts

leg_booking_detail

daily

Required leg_ids; optional priority (default 1)

leg_booking_detail

leg_bid_price_detail

daily

Required leg_ids; optional include_sold_out, priority

leg_bid_price_detail

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

name

Registry name; defaults to the function’s name (required for a lambda)

priority

Offset in seconds for a begin_sample, daily, or end_sample callback; defaults to 1

skip_burn

Whether burn-in samples are skipped; defaults to false

version

Implementation version, checked when a configuration requires one; defaults to "1"

parameters_model

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_callback

  • register_begin_sample_callback

  • register_daily_callback

  • register_end_sample_callback

  • register_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.