Summary Outputs¶

When you run a simulation in PassengerSim, you will get a SimulationTables object. This objects embeds a variety of summary infomation from the run.

In [1]:

import passengersim as pax

pax.versions()

import passengersim as pax pax.versions()

passengersim 0.62
passengersim.core 0.62

In [2]:

cfg = pax.Config.from_yaml(pax.demo_network("3MKT/08-untrunc-em"))
cfg.simulation_controls.num_samples = 300
cfg.simulation_controls.num_trials = 2
sim = pax.Simulation(cfg)
summary = sim.run()

cfg = pax.Config.from_yaml(pax.demo_network("3MKT/08-untrunc-em")) cfg.simulation_controls.num_samples = 300 cfg.simulation_controls.num_trials = 2 sim = pax.Simulation(cfg) summary = sim.run()

Task Completed after 4.17 seconds

The simple repr of this object has a bit of information about what data is in there. You can view this in a Jupyter notebook by putting the object as the last line of a cell (or just by itself):

In [3]:

summary

summary

Out[3]:

<passengersim.summaries.SimulationTables created on 2026-01-28>
 * bid_price_history (256 row DataFrame)
 * cabins (3200 row DataFrame)
 * carriers (2 row DataFrame)
 * carrier_history2 (800 row DataFrame)
 * forecast_accuracy (NoneType)
 * cp_segmentation (12 row DataFrame)
 * demand_to_come_summary (34 row DataFrame)
 * demands (6 row DataFrame)
 * displacement_history (68 row DataFrame)
 * fare_class_mix (12 row DataFrame)
 * legbuckets (48 row DataFrame)
 * legs (8 row DataFrame)
 * pathclasses (72 row DataFrame)
 * path_legs (16 row DataFrame)
 * paths (12 row DataFrame)
 * segmentation_by_timeframe (336 row DataFrame)
<*>

We can see here there are a variety of tables stored as pandas DataFrames. We can access the raw values of any of these dataframes directly in Python as an attribute on the SimulationTables object.

In [4]:

summary.carriers

summary.carriers

Out[4]:

	control	avg_rev	avg_sold	truncation_rule	avg_leg_lf	asm	rpm	ancillary_rev	avg_local_leg_pax	avg_total_leg_pax	cp_sold	cp_revenue	avg_price	yield	rasm	sys_lf	local_pct_leg_pax	local_pct_bookings
carrier
AL1	leg	90523.1875	285.0625	3	86.595521	590302.497298	518762.573736	0.0	187.865	382.260	0.0	0.0	317.55558	0.174498	0.153351	87.880803	49.145869	65.903091
AL2	leg	91018.0000	286.0075	3	86.806250	590302.497298	519870.597612	0.0	188.850	383.165	0.0	0.0	318.23641	0.175078	0.154189	88.068507	49.286861	66.029737

Metadata¶

There is also some metadata stored on the summary, which can be accessed via the metadata method.

In [5]:

summary.metadata()

summary.metadata()

Out[5]:

{'time.created': '2026-01-28T19:53:30.756370+00:00',
 'machine.system': 'Darwin',
 'machine.release': '24.6.0',
 'machine.version': 'Darwin Kernel Version 24.6.0: Wed Nov  5 21:28:03 PST 2025; root:xnu-11417.140.69.705.2~1/RELEASE_ARM64_T8122',
 'machine.machine': 'arm64',
 'machine.processor': 'arm',
 'machine.architecture': ('64bit', ''),
 'machine.node': 'Nightshade.local',
 'machine.platform': 'macOS-15.7.3-arm64-arm-64bit',
 'machine.python_version': '3.12.11',
 'machine.cpu_count': 8,
 'version.passengersim': '0.62',
 'version.passengersim_core': '0.62'}

You can access the metadata for a specific key by passing that key as an argument to the method.

In [6]:

summary.metadata("time")

summary.metadata("time")

Out[6]:

{'created': '2026-01-28T19:53:30.756370+00:00'}

Configuration Used¶

The summary also includes the complete configuration used for this simulation run, to make it easy for users to see how the results were generated, and to replicate them if needed.

In [8]:

summary.config

summary.config

Out[8]:

passengersim.Config:
  tags: 
  scenario: '3MKT'
  simulation_controls: <simulation controls with 2 trials, 300 samples, 100 burn>
  db: <database config, engine=sqlite, filename=:memory:>
  outputs: <outputs config>
  rm_systems: 
  blf_curves: 
  frat5_curves: <dict of 0 frat5_curves>
  load_factor_curves: 
  todd_curves: 
  choice_models: <dict of 2 choice_models>
  carriers: 
    AL1: <carrier config, rm_system=E>
    AL2: <carrier config, rm_system=E>
  places: <dict of 3 places>
  circuity_rules: []
  classes: ['Y0', 'Y1', 'Y2', 'Y3', 'Y4', 'Y5']
  dcps: [63, 56, 49, 42, 35, 31, 28, 24, 21, 17, 14, 10, 7, 5, 3, 1]
  booking_curves: <dict of 2 booking_curves>
  legs: <list of 8 legs>
  demands: <list of 6 demands>
  fares: <list of 36 fares>
  paths: <list of 0 paths>
  markets: []
  other_controls: 
  snapshot_filters: []
  dwm_tolerance: []

Saving and Restoring¶

Running a PassengerSim simulation on a practical network can take some time, so it is desirable to save your results after a run. This allows you to come back to the analyze those results later, or compare against other future scenario permutations. Results can be saved using the SummaryTables.to_file method.

In [10]:

summary.to_file("saved-outputs/summary")

summary.to_file("saved-outputs/summary")

Out[10]:

PosixPath('saved-outputs/summary.20260128-135330.pxsim')

The method will automatically add the appropriate file extension and write the file to disk. By default, it will also add a timestamp, so that you will not overwrite existing similar files.

In [11]:

from passengersim.utils.show_dir import display_directory_contents

display_directory_contents("saved-outputs")

from passengersim.utils.show_dir import display_directory_contents display_directory_contents("saved-outputs")

saved-outputs/
  summary.20260128-135330.pxsim

Restoring from this file can be done, surprisingly enough, using the SummaryTables.from_file classmethod. You can call this function with the same filename as to_file, and it will load the file with the most recent timestamp if there is one or more matching file(s) with various timestamps. To load a specific file that may or may not be the most recent, you can call this method with the complete actual filename, including the timestamp and ".pxsim" suffix.

In [12]:

resummary = pax.SimulationTables.from_file("saved-outputs/summary")
resummary

resummary = pax.SimulationTables.from_file("saved-outputs/summary") resummary

Out[12]:

<passengersim.summaries.SimulationTables created on 2026-01-28>
 * bid_price_history (available in file storage)
 * cabins (available in file storage)
 * carrier_history2 (available in file storage)
 * carriers (available in file storage)
 * cp_segmentation (available in file storage)
 * demand_to_come_summary (available in file storage)
 * demands (available in file storage)
 * displacement_history (available in file storage)
 * fare_class_mix (available in file storage)
 * forecast_accuracy (available in file storage)
 * legbuckets (available in file storage)
 * legs (available in file storage)
 * path_legs (available in file storage)
 * pathclasses (available in file storage)
 * paths (available in file storage)
 * segmentation_by_timeframe (available in file storage)
<*>

When opening the file, only the most basic metadata is actually loaded by the from_file method, and the rest is identified as available on demand from storage. You can confirm which file is used as the storage, as that is added to the metadata at load time:

In [13]:

resummary.metadata("store")

resummary.metadata("store")

Out[13]:

{'filename': 'saved-outputs/summary.20260128-135330.pxsim'}

Accessing data will load just that table from the file. This includes accessing a table explicity (by calling for it), or implicitly (e.g. by creating a figure using the data). The loading process happens transparently -- you don't need to specifically load anything, it will just happen automatically as needed.

In [14]:

resummary.carriers

resummary.carriers

Out[14]:

	control	avg_rev	avg_sold	truncation_rule	avg_leg_lf	asm	rpm	ancillary_rev	avg_local_leg_pax	avg_total_leg_pax	cp_sold	cp_revenue	avg_price	yield	rasm	sys_lf	local_pct_leg_pax	local_pct_bookings
carrier
AL1	leg	90523.1875	285.0625	3	86.595521	590302.497298	518762.573736	0.0	187.865	382.260	0.0	0.0	317.55558	0.174498	0.153351	87.880803	49.145869	65.903091
AL2	leg	91018.0000	286.0075	3	86.806250	590302.497298	519870.597612	0.0	188.850	383.165	0.0	0.0	318.23641	0.175078	0.154189	88.068507	49.286861	66.029737

In [15]:

resummary.fig_fare_class_mix()

resummary.fig_fare_class_mix()

Out[15]:

We can see in the objects repr that the carriers and fare_class_mix tables have been loaded, but the rest are still only in the storage file.

In [16]:

resummary

resummary

Out[16]:

<passengersim.summaries.SimulationTables created on 2026-01-28>
 * carriers (2 row DataFrame)
 * fare_class_mix (12 row DataFrame)
 * bid_price_history (available in file storage)
 * cabins (available in file storage)
 * carrier_history2 (available in file storage)
 * cp_segmentation (available in file storage)
 * demand_to_come_summary (available in file storage)
 * demands (available in file storage)
 * displacement_history (available in file storage)
 * forecast_accuracy (available in file storage)
 * legbuckets (available in file storage)
 * legs (available in file storage)
 * path_legs (available in file storage)
 * pathclasses (available in file storage)
 * paths (available in file storage)
 * segmentation_by_timeframe (available in file storage)
<*>

In addition to the summary data tables, the complete configuration used is also still available, in case it is needed.

In [17]:

resummary.config

resummary.config

Out[17]:

passengersim.Config:
  tags: 
  scenario: '3MKT'
  simulation_controls: <simulation controls with 2 trials, 300 samples, 100 burn>
  db: <database config, engine=sqlite, filename=:memory:>
  outputs: <outputs config>
  rm_systems: 
  blf_curves: 
  frat5_curves: <dict of 0 frat5_curves>
  load_factor_curves: 
  todd_curves: 
  choice_models: <dict of 2 choice_models>
  carriers: 
    AL1: <carrier config, rm_system=E>
    AL2: <carrier config, rm_system=E>
  places: <dict of 3 places>
  circuity_rules: []
  classes: ['Y0', 'Y1', 'Y2', 'Y3', 'Y4', 'Y5']
  dcps: [63, 56, 49, 42, 35, 31, 28, 24, 21, 17, 14, 10, 7, 5, 3, 1]
  booking_curves: <dict of 2 booking_curves>
  legs: <list of 8 legs>
  demands: <list of 6 demands>
  fares: <list of 36 fares>
  paths: <list of 0 paths>
  markets: []
  other_controls: 
  snapshot_filters: []
  dwm_tolerance: []

Pickling¶

In addition to the pxsim file format, PassengerSim also supports pickle serialization.
This file format loses some of the nicities of the pxsim format, such as lazy data loading.
But it is a widely adopted standard format for Python serialization which is used across many Python libraries. If the LZ4 library is available, it will also use that for compression, which can result in a marginally smaller filesize than the pxsim format.

In [18]:

summary.to_pickle("saved-outputs/summary")

display_directory_contents("saved-outputs")

summary.to_pickle("saved-outputs/summary") display_directory_contents("saved-outputs")

saved-outputs/
  summary.20260128-135330.pkl.lz4
  summary.20260128-135330.pxsim

Restoring from this pickle file can be done, surprisingly enough, using the from_pickle method. You can call this method with the same filename as to_pickle, and it will load the file with the most recent timestamp if there is one or more matching file(s) with various timestamps. To load a specific pickle file that may or may not be the most recent, you can call this method with the complete actual filename, including the timestamp and ".pkl" or ".pkl.lz4" suffix.

In [19]:

resummary2 = pax.SimulationTables.from_pickle("saved-outputs/summary")
resummary2

resummary2 = pax.SimulationTables.from_pickle("saved-outputs/summary") resummary2

Out[19]:

<passengersim.summaries.SimulationTables created on 2026-01-28>
 * bid_price_history (256 row DataFrame)
 * cabins (3200 row DataFrame)
 * carriers (2 row DataFrame)
 * carrier_history2 (800 row DataFrame)
 * forecast_accuracy (NoneType)
 * cp_segmentation (12 row DataFrame)
 * demand_to_come_summary (34 row DataFrame)
 * demands (6 row DataFrame)
 * displacement_history (68 row DataFrame)
 * fare_class_mix (12 row DataFrame)
 * legbuckets (48 row DataFrame)
 * legs (8 row DataFrame)
 * pathclasses (72 row DataFrame)
 * path_legs (16 row DataFrame)
 * paths (12 row DataFrame)
 * segmentation_by_timeframe (336 row DataFrame)
<*>

You may note the summary that is reloaded from the pickle file is fully populated, with every table showing as a DataFrame instead of "available from store". Since the pickle format does not include lazy data access, loading anything from a pickle requires loading everything from the pickle, which may take some time for larger simulations.