experimentsimulator.py

This module is used for performing Monte-Carlo virtual experiments over a series of input simulation cases and sensor arrays.

class EExpSimPara(value)

Bases: Enum

Parallelisation strategy to use for simulated experiments.

ALL = 1

Each worker performs ‘ALL’ N simulated experiments for each combination of simulation data and sensor arrays. This is the best option of point sensors.

SPLIT = 2

Simulations are ‘SPLIT’ across workers each performing 1 of N simulations for any given combination of simulation data and sensor arrays. This is the best option for when each simulation is computationally heavy such as imaging workflows.

class ExpSimSaveKeys(meas='meas', sens_times='sens_times', sys='sys_errs', rand='rand_errs', truth=None, pert_sens_times='pert_sens_times', pert_sens_pos='pert_sens_pos')

Bases: object

Default string keys used for saving experiment simulation data in the returned data dictionary. These keys appear in the last position of the tuple key and indicate the data that is available. The first two positions in the tuple key indicate the simulation key and sensor array key. For example (sim_key,sensor_key,data_key). Setting any of the data keys in this class to None will mean that data is not saved from the simulation. This is useful if you only want the simulated measurements but not the error breakdown or if you are noy using field errors and don’t need the perturbed sensor data. Note that the measurement key must be specified.

meas

Default string key for the measurement array, must be specified.

sens_times

Default string key for the nominal sensor sampling times. Must be specified and stored such that resuls traces can be plotted.

sys

Deafult string key for the systematic error array. Set to None to not save the array.

rand

Deafult string key for the random error array. Set to None to not save the array.

truth

String key for the truth array. By default None as the truth array can be calculated from the measurement array and error arrays.

pert_sens_times

Default string key for perturbed sensor times when field errors are used. Set to None if there are no field errors or if the field error is not perturbing the sensor sampling times.

pert_sens_pos

Default string key for perturbed sensor positions when field errors are used. Set to None if there are no field errors or if the field error is not perturbing the sensor positions.

__init__(meas='meas', sens_times='sens_times', sys='sys_errs', rand='rand_errs', truth=None, pert_sens_times='pert_sens_times', pert_sens_pos='pert_sens_pos')

class ExpSimOpts(workers=None, para=EExpSimPara.ALL)

Bases: object

Experiment simulation options dataclass specifying options for what data arrays to store in the data dictionary and options for parallelisation of the simulated experiments.

workers

Number of workers when running simulations in parallel. Defaults to None. If None then simulations are run sequentially without multi-processing.

para

Options for running ‘ALL’ N simulations per worker or ‘SPLIT’ N simulations across workers. ‘ALL’ is most efficient for point sensors and ‘SPLIT’ should be used for computationally heavy single simulations.

__init__(workers=None, para=EExpSimPara.ALL)

class ExperimentSimulator(sim_dict, sensor_arrays, exp_sim_opts=None, exp_save_keys=None)

Bases: object

An experiment simulator for running Monte-Carlo simulation by applying a dictionary of sensor arrays to a dictionary of simulations over a given number of user defined experiments.

__init__(sim_dict, sensor_arrays, exp_sim_opts=None, exp_save_keys=None)

Parameters:

• sim_dict (dict[str,mh.SimData]) – The simulations

• sensor_arrays (dict[str,ISensorArray]) – The sensor arrays that will be applied to each simulation to generate the virtual experiment data.

get_exp_save_keys()

Gets the experiment simulation data keys.

Returns:

ExpSimSaveKeys – Dataclass containing the keys used to identify output data from the simulated experiments.

get_sim_dict()

Gets the dicitionary of simulations to run simulated experiments for.

Returns:

dict[str,mh.SimData] – Dictionary of simulation data objects.

get_sensor_array_dict()

Gets the sensor array dictionary for this experiment.

Returns:

dict[str,ISensorArray] – Dicitionary of sensor arrays for the simulated experiment.

run_experiments(num_exp_per_sim)

Runs the specified number of virtual experiments over the number of input simulation cases and virtual sensor arrays returning the results.

Parameters:

num_exp_per_sim (int) – Number of virtual experiments to perform for each combination of input physics simulations and sensor arrays. Must be a non-zero positive integer.

Returns:

dict[tuple[str,...],np.ndarray] – Dictionary of virtual experimental data arrays where the key is a tuple with form (sim_key,sens_key,data_key). The simulation and sensor keys correspond to the input simulation and sensor dictionaries and the data key returns a given output from the simulation. See the ExpSimSaveKeys dataclass for valid data keys. The ‘measurement ‘data arrays returned for simulated experiment output have shape=(n_exps,n_sens,n_comps,n_time_steps).

Raises:

ExpSimError – The number of virtual experiments to run is not a positive integer.