Tracers¶
A tracer watches a simulation as it runs and produces a table you can read afterward. For example, a booking-detail tracer can keep every day’s sales for two flights, while a forecast tracer can average the forecasts for those flights across samples. You choose the tracer according to the question you want the table to answer.
Callbacks and tracers observe the simulation at the same points, called hooks. A callback is a function that can act on the simulation or return a dictionary of observations from one call. A tracer is an object that can remember earlier calls, use several hooks, and decide how to lay out its results. Either can record individual observations. See the callback guide for the hooks available and when they run.
Run a built-in tracer¶
Suppose you want to see how sales build up on two legs of the 3MKT demo network. Create a tracer with their leg IDs and attach it before running the simulation. The tracer knows which hook to use.
import passengersim as pax
from passengersim.callbacks.booking_detail import LegBookingDetailTracer
cfg = pax.Config.from_yaml(pax.demo_network("3MKT"))
cfg.simulation_controls.num_trials = 1
cfg.simulation_controls.num_samples = 800
cfg.simulation_controls.burn_samples = 50
cfg.simulation_controls.show_progress_bar = False
cfg.db = None
cfg.outputs.reports.clear()
cfg.outputs._write_no_files()
with pax.Simulation(cfg) as sim:
LegBookingDetailTracer(leg_ids=[101, 111]).attach(sim)
summary = sim.run()
summary.callback_data["leg_booking_detail"].head()
| leg_id | 101 | 111 | ||
|---|---|---|---|---|
| trial | sample | days_prior | ||
| 0 | 50 | 63 | 0.0 | 0.0 |
| 62 | 0.0 | 2.0 | ||
| 61 | 0.0 | 3.0 | ||
| 60 | 6.0 | 13.0 | ||
| 59 | 8.0 | 17.0 |
Each row gives the cumulative seats sold on those legs for one trial, sample, and day before departure. The built-in tracers skip burn-in samples. A fresh run starts with empty tracers. Each worker in a multi-process run collects its own results, which PassengerSim combines at the end.
Select a tracer via configuration¶
Registration gives a tracer a name that a configuration file can refer to. PassengerSim already registers the built-ins. To collect the same booking table from YAML, add this to your configuration and run the simulation normally.
callbacks:
leg_booking_detail:
parameters:
leg_ids: [101, 111]
Here the declaration ID, leg_booking_detail, selects the tracer and names its result table. To
keep outbound and return sales in separate tables, declare the same tracer twice. Give each
declaration its own ID and use type to select the tracer:
callbacks:
outbound_sales:
type: leg_booking_detail
parameters:
leg_ids: [101]
return_sales:
type: leg_booking_detail
parameters:
leg_ids: [111]
After the run, summary.callback_data["outbound_sales"] contains leg 101 and
summary.callback_data["return_sales"] contains leg 111. To use the standard booking-detail summary
and figures for one group, give that declaration the default ID, leg_booking_detail. To collect
both legs in a single table, include both IDs in its leg_ids list.
The callbacks section accepts registered callback functions and tracers. See
Writing a Tracer to register your own. The pages below give the registered type
and parameters for each built-in tracer.
In Python, you can attach two instances of a tracer to watch different groups. Give the second a
distinct name, for example LegBookingDetailTracer([111], name="return_sales").attach(sim), and
read its table with summary.callback_data["return_sales"].
Attaching a manual tracer with the same name twice replaces the first with a warning. Keep in mind that the standard figures on most tracer read the default result name, so you’ll likely also need to write custom figure methods to visualize the second tracer’s results.
Built-in tracers¶
Use the name in the first column to enable a tracer under callbacks in YAML. Follow its link for a
working example.
Name |
Description |
|---|---|
Records cumulative seats sold on selected legs each day of each retained sample. |
|
Records the daily bid price for selected legs in each retained sample, so you can inspect individual prices or calculate percentiles. |
|
Reports the daily mean bid price, standard deviation, and observation count for each selected leg. |
|
Reports the daily mean, standard deviation, and observation count for the total bid price of each selected itinerary. |
|
Averages the bid-price schedules seen at the start of each sample, by leg, seats sold, and days before departure. |
|
Tracks how the bid price at each seats-sold level changes day by day, averaged across samples for each selected leg. |
|
Averages start-of-sample forecasts for selected legs by booking class and days before departure. |
|
Averages start-of-sample forecasts and adjusted fares for selected itineraries by booking class and timeframe. |
|
Reports average cumulative sales and realized revenue by carrier, market, booking class, and passenger segment at each data collection point. |
Writing a Tracer¶
A tracer is a subclass of GenericTracer. It needs a name for its results, a reset method that
empties its accumulators, and a finalize method that turns them into a DataFrame. It observes the
simulation through one or more hook methods, named for the lifecycle hooks: on_initialize_sample,
on_begin_sample, on_daily, on_end_sample, and on_finalize_sample. The tracer is attached to
every hook whose method it defines, and a single copy of the tracer receives all of those calls, so
it can compare what it saw at different points of each sample.
The example below measures sales between two hooks. It saves the starting count (which should
typically be zero, but might not be if a different callback modifies the count earlier), subtracts
it from the final count, and reports mean sales per leg. The decorator registers the class under its
result name, leg_sales.
import pandas as pd
from passengersim.callbacks import register_tracer
from passengersim.tracers.generic import GenericTracer
@register_tracer
class LegSalesTracer(GenericTracer):
name = "leg_sales"
skip_burn = True # The simulation skips burn-in samples for every hook.
def __init__(self, leg_ids: list[int], *, name: str | None = None):
self.leg_ids = list(leg_ids)
self._set_name(name) # Optional instance-level result name.
self.reset()
def reset(self):
self.legs = None
self.at_start = {}
self.totals = dict.fromkeys(self.leg_ids, 0)
self.samples = 0
def setup(self, sim):
# Look up the legs once per run, so a bad leg ID fails before any sample.
self.legs = {leg_id: sim.eng.legs.select(leg_id=leg_id) for leg_id in self.leg_ids}
def on_begin_sample(self, sim):
self.at_start = {leg_id: leg.sold for leg_id, leg in self.legs.items()}
def on_end_sample(self, sim):
for leg_id, leg in self.legs.items():
self.totals[leg_id] += leg.sold - self.at_start[leg_id]
self.samples += 1
def finalize(self):
mean = {leg_id: total / max(self.samples, 1) for leg_id, total in self.totals.items()}
df = pd.DataFrame({"mean_sold": mean})
df.attrs["n_samples"] = self.samples
df.attrs["aggregation_process"] = "wgt_by_samples"
return df
The decorator makes leg_sales available to the configuration as soon as this class definition
runs. In a separate Python session, import the module containing the class before starting the
simulation. The constructor annotation leg_ids: list[int] tells PassengerSim how to validate the
configured IDs.
The following cell reads the same callbacks section you could put in a YAML file. When the run
starts, PassengerSim looks up leg_sales, creates the tracer with those IDs, and attaches its
hooks.
import yaml
settings = yaml.safe_load("""
callbacks:
leg_sales:
parameters:
leg_ids: [101, 111]
""")
cfg.callbacks = settings["callbacks"]
with pax.Simulation(cfg) as sim:
summary = sim.run()
Read the result under the registered name. Each row gives one leg’s average increase in seats sold between the beginning and end of a retained sample.
summary.callback_data["leg_sales"]
| mean_sold | |
|---|---|
| 101 | 83.546667 |
| 111 | 107.216000 |
Hook methods take the same arguments as the corresponding callback functions: the simulation, plus
the days prior to departure for on_daily. Like a callback function, a hook method may return a
dictionary to store as ordinary callback data, though most tracers keep what they observe and report
it from finalize. A tracer can set a priority attribute, which works as it does for a callback:
it is the offset in seconds from each DCP’s trigger time. A tracer has just one priority, which
applies to all of its queued hook methods (on_begin_sample, on_daily, and on_end_sample), so
the tracer observes every DCP from the same side of the RM systems and the simulation’s bookkeeping.
A priority given when attaching the tracer, as in
sim.begin_sample_callback(tracer, priority=-5), likewise applies to all of these methods,
whichever registration method was used. When two of a tracer’s methods fall at the same moment, they
run in lifecycle order: on_begin_sample before the first on_daily call of a sample, and the last
on_daily call before on_end_sample. The same order holds between different callbacks and tracers
that share a moment (after any RM systems, which always run first). A tracer that needs different
timing for different hooks can be split into two tracers.
For each run, the simulation takes the tracer through these steps:
reset(), once, at the start of the run. A tracer is never reset between the trials of one run, so its results cover all of them.The scenario is built: the network, fares, and demands now exist.
setup(sim), once. This is the place to look up the legs, paths, or fares the tracer will observe, to allocate its arrays, and to report problems before the run gets going. The default does nothing.The hook methods, for every trial and sample of the run (skipping burn-in samples, if
skip_burnis set).finalize(), once, after the last trial. Its result is stored incallback_dataunder the tracer’s name.
If setup or a hook method raises an exception, the run stops, finalize is not called, and no
result is stored. Running again starts over from reset. When a multi-process simulation runs, each
worker gets its own fresh copy of the tracer, so no state is shared between workers, or between
experiments.
Combining results¶
When a simulation runs in several processes, or results are added together, the tables from each
part are combined. A tracer chooses how by setting df.attrs["aggregation_process"] on the table
its finalize method returns:
Process |
Combination |
|---|---|
(none) |
The tables are added together with |
|
A mean weighted by |
|
A mean weighted by |
|
Exact pooling of the |
|
The rows of both tables are stacked, for tables that keep every observation. |
Two tables declaring different processes cannot be combined, and raise an error. A tracer can define
its own process with passengersim.callbacks.register_combiner, giving it a function that combines
two such tables into a new one. Register it in the module that defines the tracer, since saved
results only record the process’s name: combining saved results in a new session raises an error
naming the process until that module has been imported. Once results using a process exist, never
change what the process name means; choose a new name instead.
Legacy tracers¶
Tracers written before hook methods existed set a hook class attribute and define __call__
instead. They work as before, on that one hook. A tracer uses one form or the other: defining hook
together with any hook method is an error.