Experiments¶

class passengersim.experiments.Experiments(config: Config, output_dir: Path | None | False = None, *, pickle: bool | str = False, html: bool | str = 'passengersim_output', hide_from_git: bool = True)[source]¶

Bases: CallbackMixin

Manage and run a collection of PassengerSim experiments.

This class stores a base Config, creates per-experiment configurations, orchestrates sequential or parallel execution, and collects the results into a Contrast dictionary. It also manages output paths, report generation, and optional result caching.

Initialize the experiment manager.

Parameters:

config : Config¶

Base configuration used to create per-experiment deep copies.

output_dir : pathlib.Path or None or False, optional¶

Directory where all experiment outputs are written. If None (default), outputs are placed in tag-named subdirectories of the current directory. If False, output is disabled.

pickle : bool or str, default False¶

If truthy, ensure the base config is set up to write pickle output. If True, the default filename stem "passengersim_output" is used.

html : bool or str, default "passengersim_output"¶

If truthy, ensure the base config is set up to write HTML output. If True, the default filename stem "passengersim_output" is used.

hide_from_git : bool, default True¶

If True and output_dir is set, write a .gitignore file that prevents git from tracking generated outputs.

Returns:

None

Methods

__init__(config[, output_dir, pickle, html, ...])	Initialize the experiment manager.
add_callback_events()	Add callback events to the simulation event queue.
apply_callback_functions(sim)
begin_sample_callback(callback)	Register a function to be triggered at the beginning of each sample.
callback_functions()	Get all callback functions.
daily_callback(callback)	Register a function to be triggered each day during a sample.
end_sample_callback(callback)	Register a function to be triggered at the end of each sample.
existing([external])	Create an experiment that uses existing results, rather than running a simulation.
run([use_existing, tag, check_versions, ...])	Run the experiments, choosing sequential or parallel execution automatically.
use_registered_callbacks()	Adopt all globally registered callbacks.
validate()	Validate all experiment tags and callables against the base config.

Attributes

report_filename	Path of the HTML report written after the most recent run.
sims	Retained simulation objects from the most recent run.

__init__(config: Config, output_dir: Path | None | False = None, *, pickle: bool | str = False, html: bool | str = 'passengersim_output', hide_from_git: bool = True)[source]¶

Initialize the experiment manager.

Parameters:

config : Config¶

Base configuration used to create per-experiment deep copies.

output_dir : pathlib.Path or None or False, optional¶

Directory where all experiment outputs are written. If None (default), outputs are placed in tag-named subdirectories of the current directory. If False, output is disabled.

pickle : bool or str, default False¶

If truthy, ensure the base config is set up to write pickle output. If True, the default filename stem "passengersim_output" is used.

html : bool or str, default "passengersim_output"¶

If truthy, ensure the base config is set up to write HTML output. If True, the default filename stem "passengersim_output" is used.

hide_from_git : bool, default True¶

If True and output_dir is set, write a .gitignore file that prevents git from tracking generated outputs.

Returns:

None

property sims : dict[str, Simulation | MultiSimulation]¶

Retained simulation objects from the most recent run.

Returns:

dict[str, Simulation or MultiSimulation] – Mapping from experiment tag to the simulation instance that produced the corresponding results.

Raises:

ValueError – If retain_sims=True was not passed to run().

existing(external: GenericSimulationTables | str | bytes | PathLike | None = None) → Experiment[source]¶

Create an experiment that uses existing results, rather than running a simulation.

Parameters:

external : GenericSimulationTables or path-like, optional¶

If provided, this should be an existing SimulationTables result or a path to an existing output file containing the results for this experiment. If this is provided, the experiment will skip running the simulation and instead load the results from the given file. This is useful for cases where the simulation has already been run and the results are saved, but you want to include those results in a report with other experiments, without re-running the simulation. If given a path but the given file does not exist or cannot be loaded, an error will be raised.

Returns:

Experiment – An experiment that will use the given existing results when run, rather than running a simulation.

add_callback_events()¶

Add callback events to the simulation event queue.

apply_callback_functions(sim: CallbackMixin)¶

begin_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer)¶

Register a function to be triggered at the beginning of each sample.

The callback function will be triggered after initial setup including all RM steps for the initial DCP, but before any customers can arrive.

Parameters:

callback : Callable[[Simulation], dict | None]¶

The callback function to register. It should accept a single argument, which will be the Simulation object, and return a dictionary of interesting things to store, or nothing.

callback_functions() → dict[str, list[Callable]]¶

Get all callback functions.

daily_callback(callback: collections.abc.Callable[[CallbackMixin, int], dict | None] | GenericTracer | RmSys)¶

Register a function to be triggered each day during a sample.

The callback function will be triggered after all RM steps when the day coincides with a DCP.

Parameters:

callback : Callable[[Simulation, int], dict | None]¶

The callback function to register. It should accept two arguments, which will be the Simulation object and the days_prior, and return None.

end_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer)¶

Register a function to be triggered at the end of each sample.

The callback function will be triggered before counters are reset or history buffers are rolled over.

Parameters:

callback : Callable[[Simulation], None]¶

The callback function to register. It should accept a single argument, which will be the Simulation object, and return a dictionary of interesting things to store, or nothing.

run(use_existing: UseExistingT | dict[str, UseExistingT] = True, *, tag: str | None = None, check_versions: bool = True, check_content: bool = True, single_process: bool = False, retain_sims: bool = False, write_report: PathLike | bool | None = True, cache_results: bool = True) → contrast.Contrast | GenericSimulationTables[source]¶

Run the experiments, choosing sequential or parallel execution automatically.

When single_process=True the experiments are run in sequence via _run_experiments_in_sequence(); otherwise they are dispatched to the parallel job executor via _run_together().

Parameters:

use_existing : Literal[True, False, "ignore", "raise"] or dict, default True¶

Single value applied to all experiments, or a mapping from experiment tag to a per-experiment value.

• True – load from an existing output file if one is found, otherwise run the simulation.

• False – always run the simulation.

• "ignore" – load from an existing output file if found, otherwise skip the experiment entirely.

• "raise" – raise an error if the output file is missing.

tag : str, optional¶

If provided, run only the experiment with this tag and return its result directly rather than a Contrast.

check_versions : bool, default True¶

If True, re-run the simulation when a loaded summary was produced by a different PassengerSim version.

check_content : bool, default True¶

If True, re-run the simulation when a loaded summary’s config differs from the current config.

single_process : bool, default False¶

If True, force all experiments to run in single-process mode and execute them sequentially.

retain_sims : bool, default False¶

If True, keep simulation objects in sims after completion. Primarily useful for debugging.

write_report : path-like or bool or None, default True¶

If truthy, write an HTML report when all experiments finish. Pass a path-like value to specify the destination; True uses the default filename "experiments-summary.html".

cache_results : bool, default True¶

If True, cache each experiment’s result on the corresponding Experiment object so it can be reused without reloading.

Returns:

contrast.Contrast or GenericSimulationTables – A Contrast mapping tags to results, or a single result when tag selects exactly one experiment.

use_registered_callbacks()¶

Adopt all globally registered callbacks.

property report_filename : Path¶

Path of the HTML report written after the most recent run.

Unless reporting is disabled, a report is written to a file after run() completes. The resulting path is stored here.

Returns:

pathlib.Path – The path of the written report file.

Raises:

ValueError – If no report has been written yet.

validate() → None[source]¶

Validate all experiment tags and callables against the base config.

Checks that every experiment has a unique tag and that its config-transforming callable runs without error when given a deep copy of the base config. Does not verify that modified configs are mutually compatible.

Returns:

None

Raises:

ValueError – If any experiment is missing a tag, has a duplicate tag, or its callable raises an exception against the base config.