Summary Outputs¶

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

import passengersim as pax

pax.versions()

passengersim 0.80
passengersim.core 0.80

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()

database filename ':memory:' is not supported, using temporary file-based database at /var/folders/sb/mb_3f0t16lx0wm3tr8r5g9rm0000gn/T/tmpaekpooz9/passengersim_temp_db.sqlite

Task Completed after 2.69 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):

summary

<passengersim.summaries.SimulationTables created on 2026-06-12>
 * 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)
 * demand_history (NoneType)
 * 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.

summary.carriers

	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	rm_system	avg_price	yield	rasm	sys_lf	local_pct_leg_pax	local_pct_bookings
carrier
AL1	leg	90528.9375	284.7775	3	86.390937	590302.36	516913.210800	0.0	188.3000	381.2550	0.0	0.0	E	317.893575	0.175134	0.153360	87.567532	49.389516	66.121797
AL2	leg	90241.0000	285.0250	3	86.536354	590302.36	517512.527587	0.0	188.1975	381.8525	0.0	0.0	E	316.607315	0.174375	0.152873	87.669060	49.285392	66.028419

Metadata¶

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

summary.metadata()

{'time.created': '2026-06-12T19:10:03.367318+00:00',
 'machine.system': 'Darwin',
 'machine.release': '25.5.0',
 'machine.version': 'Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:12 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6050',
 'machine.machine': 'arm64',
 'machine.processor': 'arm',
 'machine.architecture': ('64bit', ''),
 'machine.node': 'Driftless.local',
 'machine.platform': 'macOS-26.5.1-arm64-arm-64bit',
 'machine.python_version': '3.12.13',
 'machine.cpu_count': 18,
 'version.passengersim': '0.80',
 'version.passengersim_core': '0.80',
 'outputs.disk_filename': PosixPath('/Users/jpn/Git/pax/documentation/user-guide/passengersim-output.20260612-141000.pxsim')}

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

summary.metadata("time")

{'created': '2026-06-12T19:10:03.367318+00:00'}

assert "created" in summary.metadata("time").keys()
assert "time.created" in summary.metadata().keys()

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.

summary.config

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: [Market(orig='BOS', dest='ORD', demand_multiplier=1.0, delta_t=None), Market(orig='ORD', dest='LAX', demand_multiplier=1.0, delta_t=None), Market(orig='BOS', dest='LAX', demand_multiplier=1.0, delta_t=None)]
  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.

# ensure the saved-outputs directory starts off empty
import shutil

shutil.rmtree("saved-outputs", ignore_errors=True)

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

PosixPath('saved-outputs/summary.20260612-141003.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.

from passengersim.utils.show_dir import display_directory_contents

display_directory_contents("saved-outputs")

saved-outputs/
  summary.20260612-141003.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.

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

<passengersim.summaries.SimulationTables created on 2026-06-12>
 * 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_history (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:

resummary.metadata("store")

{'filename': 'saved-outputs/summary.20260612-141003.pxsim'}

Accessing data will load just that table from the file. This includes accessing a table explicitly (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.

resummary.carriers

	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	rm_system	avg_price	yield	rasm	sys_lf	local_pct_leg_pax	local_pct_bookings
carrier
AL1	leg	90528.9375	284.7775	3	86.390937	590302.36	516913.210800	0.0	188.3000	381.2550	0.0	0.0	E	317.893575	0.175134	0.153360	87.567532	49.389516	66.121797
AL2	leg	90241.0000	285.0250	3	86.536354	590302.36	517512.527587	0.0	188.1975	381.8525	0.0	0.0	E	316.607315	0.174375	0.152873	87.669060	49.285392	66.028419

resummary.fig_fare_class_mix()

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.

resummary

<passengersim.summaries.SimulationTables created on 2026-06-12>
 * 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_history (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.

resummary.config

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: [Market(orig='BOS', dest='ORD', demand_multiplier=1.0, delta_t=None), Market(orig='ORD', dest='LAX', demand_multiplier=1.0, delta_t=None), Market(orig='BOS', dest='LAX', demand_multiplier=1.0, delta_t=None)]
  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 niceties 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.

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

display_directory_contents("saved-outputs")

saved-outputs/
  summary.20260612-141003.pxsim
  summary.20260612-141003.pkl.lz4

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.

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

<passengersim.summaries.SimulationTables created on 2026-06-12>
 * 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)
 * demand_history (NoneType)
 * 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.