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

Methods

__init__(config[, output_dir, pickle, html, ...])
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.
use_registered_callbacks()	Adopt all globally registered callbacks.
validate()	Validate the experiments.

Attributes

report_filename	Filename of the written report.
sims

property sims¶

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)[source]¶

Run the experiments.

Parameters:

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

This can either be a single value for all experiments, or a dictionary mapping tags to values. For each value, the behavior is as follows: If True, load from existing output pickle files if they exist, otherwise run the simulation for each experiment. If False, always run the simulation for each experiment. If “ignore”, load results from output pickle or pxsim files if they exist, otherwise skip each experiment. If “raise”, raise an error if the output pickle or pxsim files do not exist for any experiment.

tag : str, optional¶

If provided, only run the experiment with the given tag.

check_versions : bool, default True¶

If True, check the PassengerSim versions in the loaded summary (if any), and re-run the simulation if they do not match the current environment. If False, do not check the PassengerSim versions.

check_content : bool, default True¶

If True, check the content of the loaded summary (if any), and re-run the simulation if the config has changed. If False, do not check the content of the loaded summary.

single_process : bool, default False¶

If True, force all the simulations to run in single process mode. If False, run allow each experiment’s simulation to run multi-process, unless that individual experiment is set to run in single process mode.

retain_sims : bool, default False¶

If True, retain the simulation objects in the sims attribute after running each simulation. This is primarily useful for debugging.

write_report : path-like or bool, default True¶

If provided, write a report of the experiments to the given file. This will be relative to the output directory if that is set, and the filename given here is a relative path. If True, the report filename will be “experiments-summary.html”. If False, do not write a report.

cache_results : bool, default True¶

If True, cache the results of each experiment in the cached attribute of the corresponding Experiment object. This allows the results to be reused in future runs of the experiments, without needing to reload from disk.

Returns:

contrast.Contrast or SimulationTables

use_registered_callbacks()¶

Adopt all globally registered callbacks.

property report_filename : Path¶

Filename of the written report.

Unless disabled, a report is written to a file after running the experiments. The report filename is stored here for reference.

Raises:

ValueError – If no report has been written.

validate()[source]¶

Validate the experiments.

This checks that all the experiments can be initialized with the base config, and that there are no duplicate tags. This does not check that the modified configs are valid, since some modifications might be mutually incompatible but still be useful for comparison.