Experiment¶

class passengersim.experiments.Experiment(title: str | None, tag: str | None = None, multiprocess: bool = True, *, external: GenericSimulationTables | str | bytes | PathLike | None = None)[source]¶

Bases: object

A single experiment definition and its associated config-transforming callable.

Instances are normally created via the Experiments factory methods or by decorating a function with an Experiment instance. The instance stores the experiment metadata (title, tag, multiprocess flag), the config-transforming function, and optionally pre-loaded or cached results.

Initialize an experiment definition.

Parameters:

title : str or None¶

Human-friendly title for the experiment. Used in HTML reports. If None, the tag is used as the title.

tag : str, optional¶

A short machine-friendly tag for the experiment. Ideally this tag will not have spaces or other special character other than underscores. This tag is used as a key in the results dictionary returned by Experiments.run(), and it is used in generating filenames for the experiment outputs. If not provided, the name of the decorated function is used as the tag.

multiprocess : bool, default True¶

If True, run the simulation for this experiment in multi-process mode. If False, run the simulation for this experiment in single-process mode. Note that multi-process mode is not compatible with all environments, and may cause issues in interactive environments such as Jupyter notebooks. In those cases, set this to False to run in single-process mode.

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.

Methods

__init__(title[, tag, multiprocess, external])

Initialize an experiment definition.

__init__(title: str | None, tag: str | None = None, multiprocess: bool = True, *, external: GenericSimulationTables | str | bytes | PathLike | None = None)[source]¶

Initialize an experiment definition.

Parameters:

title : str or None¶

Human-friendly title for the experiment. Used in HTML reports. If None, the tag is used as the title.

tag : str, optional¶

A short machine-friendly tag for the experiment. Ideally this tag will not have spaces or other special character other than underscores. This tag is used as a key in the results dictionary returned by Experiments.run(), and it is used in generating filenames for the experiment outputs. If not provided, the name of the decorated function is used as the tag.

multiprocess : bool, default True¶

If True, run the simulation for this experiment in multi-process mode. If False, run the simulation for this experiment in single-process mode. Note that multi-process mode is not compatible with all environments, and may cause issues in interactive environments such as Jupyter notebooks. In those cases, set this to False to run in single-process mode.

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.