Monte Carlo

class MonteCarlo(investigated_object, num_samples, evaluators=None, batch_size=None, num_actors=None, console=None, console_mode=ConsoleMode.INTERACTIVE, ray_address=None, ray_port=6379, cpus_per_actor=1, runtime_env=False, catch_exceptions=True, progress_log_interval=4.0, debug=False)

Bases: Generic[MO]

Grid of parameters over which to iterate the simulation.

Parameters:

• investigated_object (TypeVar(MO)) – Object to be investigated during the simulation runtime.

• num_samples (int) – Number of generated samples per grid element.

• evaluators (Sequence[Evaluator] | None) – Evaluators used to process the investigated object sample state.

• batch_size (int | None) – Number of samples collected by inidividual actors. Refer to batch_size for more information.

• num_actors (int | None) – Number of dedicated actors spawned during simulation. By default, the number of actors will be the number of available CPU cores.

• console (Console | None) – Console the simulation writes to.

• console_mode (ConsoleMode) – The printing behaviour of the simulation during runtime.

• batch_size – Number of samples per section block. By default, the size of the simulation grid is selected.

• ray_address (str | None) – The address of the ray head node. If None is provided, the head node will be launched in this machine.

• cpus_per_actor (int) – Number of CPU cores reserved per actor. One by default.

• runtime_env (bool) – Create a virtual environment on each host. Disabled by default.

• catch_exceptions (bool) – Catch exceptions occuring during simulation runtime. Enabled by default.

• progress_log_interval (float) – Interval between result logs in seconds. 1 second by default.

• debug (bool) – Enables debug mode during simulation runtime. Debug mode will add performance-related information to the output and enable the ray dashboard.

add_dimension(dimension)

Add a new dimension to the simulation grid.

Parameters:

dimension (GridDimension) – Dimension to be added.

Raises:

ValueError – If the dimension already exists within the grid.

Return type:

None

add_evaluator(evaluator)

Add new evaluator to the Monte Carlo simulation.

Parameters:

evaluator (Evaluator) – The evaluator to be added.

Return type:

None

new_dimension(dimension, sample_points, *args, **kwargs)

Add a dimension to the simulation grid.

Must be a property of the investigated object.

Parameters:

• dimension (str) – String representation of dimension location relative to the investigated object.

• sample_points (list[object]) – list points at which the dimension will be sampled into a grid. The type of points must be identical to the grid arguments / type.

• args (object) – References to the object the dimension belongs to. Resolved to the investigated object by default, but may be an attribute or sub-attribute of the investigated object.

• kwargs – Additional initialization arguments passed to GridDimension.

Return type:

GridDimension

Returns: The newly created dimension object.

remove_dimension(dimension)

Remove an existing dimension from the simulation grid.

Parameters:

dimension (GridDimension) – The dimension to be removed.

Raises:

ValueError – If the dimension does not exist.

Return type:

None

simulate(actor, additional_dimensions=None, stage_arguments=None)

Launch the Monte Carlo simulation.

Parameters:

• actor (Type[MonteCarloActor]) – The actor from which to generate the simulation samples.

• additional_dimensions (set[GridDimension] | None) – Additional dimensions to be added to the simulation grid.

• stage_arguments (dict[str, object] | None) – Arguments to be passed to the simulation stages. If the argument is a sequence, the respective stage will iterate over the sequence.

Return type:

MonteCarloResult

Returns: A MonteCarloResult dataclass containing the simulation results.

property batch_size: int

Number of discrete samples generated by

Raises:

ValueError – If the block size is smaller than one.

catch_exceptions: bool

property console: Console

Console the Simulation writes to.

property console_mode: ConsoleMode

Console output behaviour during simulation runtime.

property cpus_per_actor: int

Number of CPU cores reserved for each actor.

Raises:

ValueError – If the number of cores is smaller than one

property dimensions: list[GridDimension]

Simulation grid dimensions which make up the grid.

property evaluators: list[Evaluator]

Evaluators used to process the investigated object sample state.

property investigated_object: object

The object to be investigated during the simulation runtime.

property num_actors: int

Number of dedicated actors spawned during simulation runs.

Raises:

ValueError – If the number of actors is smaller than zero.

property num_samples: int

Number of samples per simulation grid section.

This represents the maximum number of samples a parameter combination will be sampled. The final number of collected samples may be smaller if the configured evaluators report confidence in their results before the maximum number of samples is reached.

Raises:

ValueError – If number of samples is smaller than one.

runtime_env: bool

class MonteCarloResult(grid, evaluators, results, performance_time)

Bases: object

Result of a Monte Carlo simulation.

Parameters:

• grid (Sequence[GridDimension]) – Dimensions over which the simulation has swept.

• evaluators (Sequence[Evaluator]) – Evaluators used to evaluated the simulation artifacts.

• results (Sequence[EvaluationResult]) – Evaluation results generated by the evaluators.

• performance_time (float) – Time required to compute the simulation.

Raises:

ValueError – If the dimensions of samples do not match the supplied sweeping dimensions and evaluators.

plot()

Plot evaluation figures for all contained evaluator artifacts.

Returns: Container of all generated plots.

Return type:

list[PlotVisualization]

print(console=None)

Print a text representation of the simulation result.

Parameters:

console (Console | None) – Rich console to print to. If not provided, a new one will be initialized.

Return type:

None

save_to_matlab(file)

Save simulation results to a matlab file.

Parameters:

file (str) – File location to which the results should be saved.

Return type:

None

property evaluation_results: Sequence[EvaluationResult]

Access individual evaluation results.

property performance_time: float

Simulation runtime in seconds.

class MO

Type of Monte Carlo object under investigation.

alias of TypeVar(‘MO’)