Simulation

class passengersim.driver.Simulation(config: Config, output_dir: Path | None = None, *, connection: Connection | None = None)[source]

Bases: BaseSimulation, CallbackMixin, Firehose

Initialize a Simulation instance.

Parameters:
config : Config

The simulation configuration object. Will be revalidated during initialization.

output_dir : pathlib.Path or None, optional

Directory for output files. If None, a temporary directory will be created automatically.

connection : sqlite3.Connection, optional

Existing connection shared with the native writer. The caller owns its transaction boundaries and is responsible for closing it.

Notes

This initializes the simulation with default parameters including DCP lists, choice models, and various data structures for tracking simulation results.

Methods

__init__(config[, output_dir, connection])

Initialize a Simulation instance.

add_callback_events()

Add callback events to the simulation event queue.

apply_callback_functions(sim)

Attach this object's manual callbacks to another simulation.

attach_firehose(topic, destination, *[, ...])

Attach a firehose logger destination for a topic.

backup_db(dst)

Back up this database to another copy.

begin_sample([sample])

Begin processing a new sample in the simulation.

begin_sample_callback([callback, priority, ...])

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

begin_trial(trial)

Beginning of trial processing.

callback_functions()

Get all manually attached callback functions.

capture_competitor_data()

Capture competitor pricing data for all markets.

capture_dcp_data(dcp_index[, closures_only])

Capture data control point (DCP) data for revenue management.

close()

Release this run's database; borrowed connections remain caller-owned.

daily_callback([callback, priority, ...])

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

end_sample()

End processing of the current sample.

end_sample_callback([callback, priority, ...])

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

end_trial()

End of trial processing.

extract_and_reset_bid_price_traces()

extract_segmentation_by_timeframe()

finalize_sample_callback([callback, ...])

Register a synchronous callback after sample bookkeeping finishes.

from_yaml(filenames[, output_dir])

Create a Simulation object from a YAML file.

generate_dcp_rm_events([debug])

Pushes an event per reading day (DCP) onto the queue.

generate_demands()

Generate demands following the procedure used in PODS.

generate_demands_gamma([system_rn, debug])

Using this as a quick test

get_choice_parameters(choicemodel)

Get the parameters for a choice model.

get_firehose(topic)

Return the cached writable firehose destination for a topic.

get_restriction_name(restriction_num)

Convert restriction number to a restriction name.

initialize_sample_callback([callback, ...])

Register a synchronous callback before sample demand generation.

license_info([certificate_filename])

parse_restriction_flags(restriction_flags)

Convert restriction flags to a list of restriction names.

path_names()

Get a mapping of path IDs to path names.

pathclasses_for_carrier(carrier)

Generator of all path classes for a given carrier.

remove_callback(callback, *[, missing_ok])

Detach manually attached callbacks or tracers.

reseed([seed])

Reseed the simulation's random number generator.

rm_data(carrier, kind[, set_value])

Access RM data (forecasts, optimizers, etc.) from the simulation.

run([log_reports, single_trial, summarizer, ...])

Run the simulation and compute reports.

run_single_sample()

Context manager to run the next sample in the current trial.

run_trial(trial[, summarizer])

save_simulation_state([force])

set_choice_parameters(choicemodel, values)

Set the parameters for a choice model.

set_classes(leg, _cabin[, debug])

setup_scenario()

Set up the scenario for the simulation.

use_registered_callbacks()

Adopt all globally registered callbacks (deprecated).

validate_license([certificate_filename, future])

vn_initial_mapping(carrier_code)

Set up initial virtual nesting mapping for a carrier.

Attributes

base_time

The base time for the simulation.

begin_sample_callbacks

Every callback attached to the begin_sample hook, in the order they run.

cnx

Deprecated alias for the PassengerSim database wrapper.

config

The configuration used for this Simulation.

daily_callbacks

Every callback attached to the daily hook, in the order they run.

database_available

Whether this simulation still has an accessible result database.

database_path

Absolute result path, retained for diagnostics after close.

db

The PassengerSim database wrapper, allocated only on first use.

db_writer

demands

Generator of all demands in the simulation.

end_sample_callbacks

Every callback attached to the end_sample hook, in the order they run.

fares

Generator of all fares in the simulation.

finalize_sample_callbacks

Every callback attached to the finalize_sample hook, in the order they run.

initialize_sample_callbacks

Every callback attached to the initialize_sample hook, in the order they run.

markets

Access markets in the simulation.

pathclasses

Generator of all path classes in the simulation.

paths

Generator of all paths in the simulation.

random_generator

Access to the random generator for the simulation.

sample_done_callback

Progress sink called with completed and total samples, starting at zero.

snapshot_filters

Get the snapshot filters for the simulation.

segmentation_data_by_timeframe

Bookings and revenue segmentation by timeframe.

bid_price_traces

Bid price traces for each carrier.

displacement_traces

Displacement cost traces for each carrier.

callback_data

Data stored from callbacks.

eng

__init__(config: Config, output_dir: Path | None = None, *, connection: Connection | None = None)[source]

Initialize a Simulation instance.

Parameters:
config : Config

The simulation configuration object. Will be revalidated during initialization.

output_dir : pathlib.Path or None, optional

Directory for output files. If None, a temporary directory will be created automatically.

connection : sqlite3.Connection, optional

Existing connection shared with the native writer. The caller owns its transaction boundaries and is responsible for closing it.

Notes

This initializes the simulation with default parameters including DCP lists, choice models, and various data structures for tracking simulation results.

segmentation_data_by_timeframe : dict[int, pd.DataFrame]

Bookings and revenue segmentation by timeframe.

The key is the trial number, and the value is a DataFrame with a breakdown of bookings and revenue by timeframe, customer segment, carrier, and booking class.

bid_price_traces : dict[int, Any]

Bid price traces for each carrier.

The key is the trial number, and the value is a dictionary with carrier names as keys and bid price traces as values.

displacement_traces : dict[int, Any]

Displacement cost traces for each carrier.

The key is the trial number, and the value is a dictionary with carrier names as keys and displacement cost traces as values.

callback_data : CallbackData

Data stored from callbacks.

This allows a user to store arbitrary data during a simulation using callbacks, and access it later.

property sample_done_callback : Callable[[int, int], None]

Progress sink called with completed and total samples, starting at zero.

property db

The PassengerSim database wrapper, allocated only on first use.

property database_path

Absolute result path, retained for diagnostics after close.

property database_available

Whether this simulation still has an accessible result database.

close()[source]

Release this run’s database; borrowed connections remain caller-owned.

property random_generator : Generator

Access to the random generator for the simulation.

Returns:

passengersim.core.Generator – The random generator instance used for stochastic processes in the simulation.

property base_time : int

The base time for the simulation.

Returns:

int – The base time in seconds since the epoch.

property snapshot_filters : list[SnapshotFilter] | None

Get the snapshot filters for the simulation.

Returns:

list[SnapshotFilter] or None – List of snapshot filter objects, or None if simulation is not initialized.

property db_writer
parse_restriction_flags(restriction_flags: int) → list[str][source]

Convert restriction flags to a list of restriction names.

Parameters:
restriction_flags : int

Integer bit flags representing which restrictions are active.

Returns:

list[str] – List of restriction names corresponding to the set flags.

get_restriction_name(restriction_num: int) → str[source]

Convert restriction number to a restriction name.

Parameters:
restriction_num : int

The numeric identifier for the restriction (must be >= 1).

Returns:

str – The name of the restriction.

Raises:

IndexError – If restriction_num is less than 1 or exceeds the number of defined restrictions.

set_classes(leg: Leg, _cabin, debug=False)[source]
setup_scenario() → None[source]

Set up the scenario for the simulation.

This will delete any existing data in the database under the same simulation name, build the connections if needed, and then call the vn_initial_mapping method to set up the initial mapping for the carriers using virtual nesting.

vn_initial_mapping(carrier_code: str) → None[source]

Set up initial virtual nesting mapping for a carrier.

Parameters:
carrier_code : str

The carrier code to set up virtual nesting mapping for.

Notes

This method assigns index values to path classes for carriers using virtual nesting, which allows revenue management systems to map between physical and virtual booking classes. The first leg receives the path class index; connecting legs are reset to bucket zero so mappings from a previous run cannot affect initial offers.

begin_sample(sample: int | None = None)[source]

Begin processing a new sample in the simulation.

Parameters:
sample : int or None, optional

The sample number to set. If None, the current sample number will be incremented by 1.

Notes

This method handles sample initialization including setting the random seed (if configured) and preparing the simulation state for the new sample. Any registered initialize-sample callbacks are run after counters are reset and before sample demands are generated.

end_sample()[source]

End processing of the current sample.

Notes

This method records departure statistics to carrier-level counters, handles choice set and competitor data capture if configured, and performs other end-of-sample cleanup and data collection tasks.

begin_trial(trial: int)[source]

Beginning of trial processing.

Parameters:
trial : int

The trial number.

end_trial()[source]

End of trial processing.

extract_and_reset_bid_price_traces()[source]
extract_segmentation_by_timeframe()[source]
save_simulation_state(force: Path | None = None) → None[source]
run_single_sample() → int[source]

Context manager to run the next sample in the current trial.

On entry, the sample number is run through to departure, so all sales have happened, but per-sample wrap up (e.g. rolling history forward, resetting counters) is deferred until exit. Synchronous finalize-sample callbacks run on normal exit after that wrap up, observing post-bookkeeping state. This is useful for running a single sample in a testing framework.

Yields:

int – The sample number just completed.

capture_competitor_data()[source]

Capture competitor pricing data for all markets.

Notes

This method shops for the lowest prices in each market and stores competitor pricing information that can be used by revenue management systems for competitive analysis.

capture_dcp_data(dcp_index, closures_only=False)[source]

Capture data control point (DCP) data for revenue management.

Parameters:
dcp_index : int

The index of the data control point.

closures_only : bool, default False

Whether to capture only closure data or all DCP data.

Notes

This method captures seat availability, booking data, and other metrics at specific time points (DCPs) before departure, which is essential for revenue management decision-making.

generate_dcp_rm_events(debug=False)[source]

Pushes an event per reading day (DCP) onto the queue.

In older versions of PassengerSim, the DCP events activated a variety of processes, including carrier RM system updates, internal simulation data capture, and database writes. In the current version, carrier RM systems are triggered via callback events, but data capture and database writes are still tied to DCP events.

generate_demands()[source]

Generate demands following the procedure used in PODS.

DCP, daily and callback events are always queued. If simulation_controls.skip_demand_generation is set, the random demand draw and the timeframe allocation are skipped, so no booking events are created. An initialize-sample callback is then expected to replace them: it should set scenario_demand on each demand (this is not reset between samples, and is used in reporting and database output) and add the sample’s booking events, e.g. with sim.eng.add_booking_event.

generate_demands_gamma(system_rn=None, debug=False)[source]

Using this as a quick test

reseed(seed: int | list[int] | None = 42)[source]

Reseed the simulation’s random number generator.

Parameters:
seed : int, list[int], or None, default 42

Seed value(s) for the random number generator. Can be a single integer, a list of integers, or None.

Notes

This method updates the random seed for the simulation’s internal random number generator, affecting all subsequent random operations.

validate_license(certificate_filename=None, future: int = 0)[source]
license_info(certificate_filename=None)[source]
property config : Config

The configuration used for this Simulation.

add_callback_events()

Add callback events to the simulation event queue.

All callbacks due at the same timestamp are placed in one event. The native event queue orders events by time alone, so separate events at one timestamp would run in an arbitrary order. Within one event, they run in this order:

  1. RM systems;

  2. then the hooks in lifecycle order, so that at the first DCP every begin_sample callback runs before any daily one, and at the final DCP every daily callback runs before any end_sample one;

  3. within each hook, configured callbacks before manual ones, each in registration (or declaration) order.

RM systems stay first so that a priority of -1, the RM systems’ own, still runs a callback after them, as documented for each hook.

apply_callback_functions(sim: CallbackMixin) → None

Attach this object’s manual callbacks to another simulation.

Parameters:
sim : CallbackMixin

The simulation (or experiments) to receive the callbacks. Tracers are copied fresh; other callables are shared.

attach_firehose(topic: str, destination: str | bool | TextIO | None, *, orig: str | None = None, dest: str | None = None, segment: str | None = None) → None

Attach a firehose logger destination for a topic.

Parameters:
topic : str

Firehose topic name to route from the simulation engine.

destination : str or bool or file-like or None

Destination passed through to the engine. Writable destinations are also stored locally so they can be returned by get_firehose().

orig : str or None, default None

For the "choice" topic, only log customers whose demand has this origin.

dest : str or None, default None

For the "choice" topic, only log customers whose demand has this destination.

segment : str or None, default None

For the "choice" topic, only log customers whose demand has this segment.

Notes

Choice filters use exact, case-sensitive matches. Omitted filters are wildcards. Demand filters are not supported by other firehose topics.

begin_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None, *, priority: int | None = None, skip_burn: bool | None = None, name: str | None = None) → 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.

It runs at an offset, in seconds, from the trigger time of the first DCP. The offset is the priority option if given, else the callback’s own priority attribute if it has one, and otherwise one second, which is after the first DCP’s RM systems (-1) and bookkeeping (0). A negative priority runs it before that bookkeeping, or, below -1, before the first DCP’s RM steps as well. No customer arrives within five seconds of a DCP, so a priority from 1 to 4 always runs before the first arrival; a larger one may not. A priority of zero is not allowed, as for a daily callback.

Parameters:
callback : Callable[[Simulation], dict | None] or GenericTracer, optional

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. Omit it to use this method as a decorator with options.

priority : int, optional

Offset in seconds from the first DCP’s trigger time; see above.

skip_burn : bool, optional

If True, the callback is not called during burn-in samples.

name : str, optional

Store returned dictionaries under callback_data.<name> instead of the shared hook key; for a tracer, its result name.

Returns:

Callable or GenericTracer – The callback, or the fresh copy of a tracer. Without callback, a decorator that registers the function it decorates.

property begin_sample_callbacks : tuple[Callable, ...]

Every callback attached to the begin_sample hook, in the order they run.

Includes RM systems and configured callbacks. This is a read-only snapshot: use the begin_sample_callback method to attach a callback.

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

Get all manually attached callback functions.

Callbacks constructed from config.callbacks declarations are excluded. They are owned by this object’s config and are rebuilt by any simulation that runs that config, so copying them elsewhere (e.g. via apply_callback_functions() or worker forwarding) would attach them twice. Carrier RM systems are excluded for the same reason: every simulation builds its own.

Returns:

dict[str, list[Callable]] – Mapping of "<hook>_callbacks" to the manual callbacks for each hook, in registration order. A tracer is listed as itself under each hook it runs on.

property cnx

Deprecated alias for the PassengerSim database wrapper.

daily_callback(callback: collections.abc.Callable[[CallbackMixin, int], dict | None] | GenericTracer | RmSys | None = None, *, priority: int | None = None, skip_burn: bool | None = None, name: str | None = None) → collections.abc.Callable[[CallbackMixin, int], dict | None] | GenericTracer

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

The callback runs at an offset, in seconds, from the overnight trigger time. The offset is the priority option if given, else the callback’s own priority attribute if it has one, and otherwise one second. RM systems run at -1 and the simulation’s own DCP and daily data capture at 0, so by default a callback sees each day after both have finished. Use a negative priority to run it before the simulation’s bookkeeping, or below -1 to run it before the RM systems as well.

A priority of zero is not allowed, because it would tie with the simulation’s own bookkeeping in an arbitrary order. It is rejected here, and again when a run starts if it was set after registration. The priority must also be a whole number of seconds: a value that clearly names one, such as 1.0 or "1", is used as that integer, and anything else (0.5, "1.5", True, "high") is rejected rather than rounded. A callback attached while a sample is running takes effect from the next sample.

The options can be given with the callback, or to use this method as a decorator:

@sim.daily_callback(priority=-5, skip_burn=True, name="nogo")
def count_nogo(sim, days_prior): ...
Parameters:
callback : Callable[[Simulation, int], dict | None] or GenericTracer, optional

The callback function to register. It should accept two arguments, which will be the Simulation object and the days_prior, and return a dictionary of interesting things to store, or nothing. Omit it to use this method as a decorator with options.

priority : int, optional

Offset in seconds from the overnight trigger time; see above.

skip_burn : bool, optional

If True, the callback is not called during burn-in samples.

name : str, optional

Store returned dictionaries under callback_data.<name> instead of the shared daily key, so they cannot collide with other callbacks’ keys; for a tracer, its result name.

Returns:

Callable or GenericTracer – The callback, or the fresh copy of a tracer. Without callback, a decorator that registers the function it decorates.

Raises:

ValueError – If the priority is zero or not a whole number of seconds, the name is reserved or used by a tracer, or the callback is a tracer declaring a hook other than daily.

property daily_callbacks : tuple[Callable, ...]

Every callback attached to the daily hook, in the order they run.

Includes RM systems and configured callbacks. This is a read-only snapshot: use the daily_callback method to attach a callback.

property demands

Generator of all demands in the simulation.

Returns:

DemandIterator – Iterator object for accessing demand data.

end_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None, *, priority: int | None = None, skip_burn: bool | None = None, name: str | None = None) → 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.

It runs at an offset, in seconds, from the trigger time of the final DCP (the day of departure). The offset is the priority option if given, else the callback’s own priority attribute if it has one, and otherwise one second, which is after the final DCP’s RM systems (-1) and bookkeeping (0). A negative priority runs it before that bookkeeping, or, below -1, before the RM systems as well. A priority of zero is not allowed, as for a daily callback.

Parameters:
callback : Callable[[Simulation], dict | None] or GenericTracer, optional

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. Omit it to use this method as a decorator with options.

priority : int, optional

Offset in seconds from the final DCP’s trigger time; see above.

skip_burn : bool, optional

If True, the callback is not called during burn-in samples.

name : str, optional

Store returned dictionaries under callback_data.<name> instead of the shared hook key; for a tracer, its result name.

Returns:

Callable or GenericTracer – The callback, or the fresh copy of a tracer. Without callback, a decorator that registers the function it decorates.

property end_sample_callbacks : tuple[Callable, ...]

Every callback attached to the end_sample hook, in the order they run.

Includes RM systems and configured callbacks. This is a read-only snapshot: use the end_sample_callback method to attach a callback.

property fares

Generator of all fares in the simulation.

Returns:

FareIterator – Iterator object for accessing fare data.

finalize_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None, *, skip_burn: bool | None = None, name: str | None = None) → Callable[[CallbackMixin], dict | None] | GenericTracer

Register a synchronous callback after sample bookkeeping finishes.

Callbacks run after departure statistics, history rollover, database commit, and other bookkeeping updates. They observe post-bookkeeping state and cannot change statistics already recorded. Use end_sample to access pre-bookkeeping state. Their execution is included in sample timing, before diagnostics are published. They run only on successful completion, not as exception cleanup; callback failures propagate after bookkeeping has completed. Configured callbacks run first, followed by manual callbacks, each in registration order. Event priority does not apply. Exceptions propagate.

Parameters:
callback : Callable[[Simulation], dict | None] or GenericTracer, optional

Callback receiving the simulation. Returned dictionaries are stored under callback_data.finalize_sample with trial/sample keys. Omit it to use this method as a decorator with options.

skip_burn : bool, optional

If True, the callback is not called during burn-in samples.

name : str, optional

Store returned dictionaries under callback_data.<name> instead of the shared hook key; for a tracer, its result name.

Returns:

Callable or GenericTracer – The callback, or the fresh copy of a tracer. Without callback, a decorator that registers the function it decorates.

property finalize_sample_callbacks : tuple[Callable, ...]

Every callback attached to the finalize_sample hook, in the order they run.

Includes RM systems and configured callbacks. This is a read-only snapshot: use the finalize_sample_callback method to attach a callback.

classmethod from_yaml(filenames: Path | list[Path], output_dir: Path | None = None)

Create a Simulation object from a YAML file.

Parameters:
filenames : pathlib.Path | list[pathlib.Path]

output_dir : pathlib.Path | None, optional

Returns:

Simulation

get_firehose(topic: str) → TextIO | None

Return the cached writable firehose destination for a topic.

Parameters:
topic : str

Firehose topic name to look up.

Returns:

TextIO or None – The cached writable destination for topic, if one was attached.

Notes

Pending firehose log output is flushed from the engine before the cached destination is returned.

initialize_sample_callback(callback: Callable[[CallbackMixin], dict | None] | GenericTracer | None = None, *, skip_burn: bool | None = None, name: str | None = None) → Callable[[CallbackMixin], dict | None] | GenericTracer

Register a synchronous callback before sample demand generation.

The sample number, random seed, and counters have been initialized, but the new sample’s RM steps have not run. Changes to demand inputs affect this sample. Callbacks run in registration order, with configured callbacks first; event priority does not apply.

Parameters:
callback : Callable[[Simulation], dict | None] or GenericTracer, optional

Callback receiving the simulation. Returned dictionaries are stored under callback_data.initialize_sample with trial/sample keys. Omit it to use this method as a decorator with options.

skip_burn : bool, optional

If True, the callback is not called during burn-in samples.

name : str, optional

Store returned dictionaries under callback_data.<name> instead of the shared hook key; for a tracer, its result name.

Returns:

Callable or GenericTracer – The callback, or the fresh copy of a tracer. Without callback, a decorator that registers the function it decorates.

property initialize_sample_callbacks : tuple[Callable, ...]

Every callback attached to the initialize_sample hook, in the order they run.

Includes RM systems and configured callbacks. This is a read-only snapshot: use the initialize_sample_callback method to attach a callback.

property markets : Mapping[str, Market]

Access markets in the simulation.

Returns:

Mapping[str, Market] – A mapping of market names to Market objects.

path_names()

Get a mapping of path IDs to path names.

Returns:

dict – Dictionary mapping path IDs to string representations of paths.

property pathclasses

Generator of all path classes in the simulation.

Yields:

pathclass – Path class objects from all paths in the simulation.

pathclasses_for_carrier(carrier: str)

Generator of all path classes for a given carrier.

Parameters:
carrier : str

The carrier name to filter path classes by.

Yields:

pathclass – Path class objects for the specified carrier.

property paths

Generator of all paths in the simulation.

Returns:

generator – Generator yielding path objects from the simulation.

remove_callback(callback: Callable | GenericTracer | str, *, missing_ok: bool = False) → int

Detach manually attached callbacks or tracers.

Parameters:
callback : Callable or GenericTracer or str

What to remove:

  • a function (or other callable) previously attached, with or without options, is removed from every hook it is attached to; a bound method matches when it binds the same function to the same object, even if it is a new obj.method expression;

  • a tracer, or a tracer’s result name, removes the attached tracer of that name from all its hooks;

  • a name given to callbacks with name= removes those callbacks.

missing_ok : bool, default False

Return 0 instead of raising if nothing matches.

Returns:

int – The number of hook registrations removed.

Raises:

ValueError – If nothing matches and missing_ok is False. Callbacks built from config.callbacks and carrier RM systems cannot be removed this way: disable a configured callback in the configuration instead.

Notes

A callback removed while a sample is running may still be called for the rest of that sample; the removal takes effect from the next one.

use_registered_callbacks() → None

Adopt all globally registered callbacks (deprecated).

Warning

This method emits a DeprecationWarning. For reusable callbacks, register them with register_callback (functions) or register_tracer (tracer classes) and select them in config.callbacks; those register for configuration rather than attaching to every simulation. For development and testing, attach callbacks directly with the simulation’s hook methods, or use an explicit CallbackMixin bundle and bundle.apply_callback_functions(sim). Registration APIs, including the factory ones, are not deprecated.

eng : SimulationEngine
run(log_reports: bool = False, *, single_trial: int | None = None, summarizer: type[SimulationTablesT] | SimulationTablesT | None = None, rich_progress: Progress | None = None, cache_dir: Path | None = None) → SimulationTablesT[source]

Run the simulation and compute reports.

Parameters:
log_reports : bool

Unused; accepted only for backward compatibility.

single_trial : int, optional

Run only a single trial, with the given trial number (to get the correct fixed random seed, for example).

summarizer : type[SimulationTables] | SimulationTables, optional

Use this summarizer to compute the reports. A valid summarizer must be a subclass or instance of GenericSimulationTables. If not provided, the default summarizer will be used.

rich_progress : Progress, optional

A rich Progress object to use for displaying progress. If not provided, a new Progress object will be created unless the simulation configuration specifies not to show progress.

cache_dir : pathlib.Path, optional

If given, reuse a cached summary for this configuration from this directory when one exists, or run and save the summary there.

Returns:

SimulationTables

run_trial(trial: int, summarizer: type[SimulationTablesT] | SimulationTablesT | None = None) → SimulationTablesT[source]
backup_db(dst: Path | str | Connection)[source]

Back up this database to another copy.

Parameters:
dst : Path-like or sqlite3.Connection

get_choice_parameters(choicemodel: str | ChoiceModel)[source]

Get the parameters for a choice model.

Parameters:
choicemodel : str or ChoiceModel

The choice model name (string) or ChoiceModel object to get parameters from.

Returns:

dict – Dictionary containing the choice model parameters, including restrictions and their associated sigma values.

set_choice_parameters(choicemodel: str | ChoiceModel, values: dict[str, float])[source]

Set the parameters for a choice model.

Parameters:
choicemodel : str or ChoiceModel

The choice model name (string) or ChoiceModel object to update.

values : dict[str, float]

Dictionary of parameter names and their new values. Can include restriction parameters using the format ‘restrictions_{name}’.

rm_data(carrier: str, kind: str, set_value: Any = None) → Any[source]

Access RM data (forecasts, optimizers, etc.) from the simulation.

If the requested data for the carrier and kind do not exist, an empty dictionary is returned.

Parameters:
carrier : str

The carrier name and data type.

kind : str

The carrier name and data type.

set_value : Any, optional

If provided, this value will be set for the carrier and kind instead of retrieving the existing value.

Returns:

Any – The existing value for this carrier and data type, or an empty dict.