experiment.runner¶

Runner for SimulationExperiments.

The ExperimentRunner is used to execute simulation experiments. This includes - loading of datasets - loading of models - running tasks (simulation on models) - creating outputs

ExperimentRunner ¶

ExperimentRunner(
    experiment_classes,
    base_path,
    data_path,
    simulator=None,
    ureg=None,
    on_error="log",
    **kwargs,
)

Class for running simulation experiments.

Initialize the runner.

Parameters:

Name	Type	Description	Default
`experiment_classes`	`type[SimulationExperiment] \| Iterable[type[SimulationExperiment]]`	the simulation experiments.	required
`base_path`	`Path \| None`	base path of the simulation experiments.	required
`data_path`	`Path \| Iterable[Path] \| None`	path or paths of the datasets of the simulation experiments.	required
`simulator`	`Simulator \| None`	the simulator of the tasks.	`None`
`ureg`	`UnitRegistry \| None`	the unit registry of the experiments.	`None`
`on_error`	`Literal['raise', 'log']`	what an error in the definition of an experiment does (its models, datasets, simulations, tasks, data, figures, fit mappings and their checks). `"log"` (the default) logs it with its traceback and goes on with the next experiment: the experiment is in `failed` and not in `experiments`, and `run_experiments` reports it as failed without running it. `"raise"` raises it, which is what a fit uses.	`'log'`
`**kwargs`	`Any`	settings of the experiments, `SimulationExperiment.settings`.	`{}`

set_simulator ¶

set_simulator(simulator)

Set simulator on the runner and experiments.

initialize ¶

initialize(experiment_classes, **kwargs)

Initialize ExperimentRunner.

Initialization is required in addition to construction to allow serialization of information for parallelization.

run_experiments ¶

run_experiments(
    output_path,
    show_figures=False,
    save_results=False,
    figure_formats=None,
    reduced_selections=True,
    keep_results=False,
    raise_on_failure=False,
    figure_settings=None,
)

Run the experiments and write their outputs.

Parameters:

Name	Type	Description	Default
`output_path`	`Path`	directory of the outputs, one directory per experiment.	required
`show_figures`	`bool`	show the matplotlib figures.	`False`
`save_results`	`bool`	write the results of the tasks.	`False`
`figure_formats`	`list[str] \| None`	formats of the figures.	`None`
`reduced_selections`	`bool`	simulate only the selections an experiment uses.	`True`
`keep_results`	`bool`	keep the results of every experiment after its outputs are written. By default they are released, so a run holds only the results of the experiment it runs and not of all experiments until its end; `SimulationExperiment.results` then raises.	`False`
`raise_on_failure`	`bool`	raise an `ExperimentRunError` after every experiment ran when an experiment or a figure failed. By default the failures are logged and recorded in the results (`ExperimentResult.failed`) only.	`False`
`figure_settings`	`FigureSettings \| Mapping[str, Any] \| None`	the settings of the figures of every experiment, a `FigureSettings` or overrides of its defaults, which the `figure_settings` of an experiment and the settings of a figure override.	`None`

Returns:

Type	Description
`list[ExperimentResult]`	The results of the experiments, which the report is created from.

Raises:

Type	Description
`ExperimentRunError`	with `raise_on_failure`, if something failed.
`ValueError`	if a key of `figure_settings` is no setting, before any experiment runs.

model_key ¶

model_key(abstract_model)

Get the key a loaded model is cached under.

Two experiments share a loaded model when they resolve to the same source, the same language, the same changes, the same added parameters and the same selections; the changes and the selections are part of it because they are applied to the roadrunner instance when it is created. The source of a file is its resolved path, the one of inline SBML its content and, for a hierarchical model, the directory its external models are resolved against, see RoadrunnerSBMLModel. The key is the description of the model and not the object: an experiment builds its own AbstractModel, which has no equality of its own, so caching on the object would never find anything and every experiment would load and compile the model again.

Parameters:

Name	Type	Description	Default
`abstract_model`	`AbstractModel`	the model of an experiment.	required

Returns:

Type	Description
`ModelKey`	The key, hashable and equal for two descriptions of the same model.

run_experiments ¶

run_experiments(
    experiments,
    output_path,
    base_path=None,
    data_path=None,
    show_report=False,
    raise_on_failure=False,
    figure_settings=None,
)

Run simulation experiments and write their report to the output path.

Parameters:

Name	Type	Description	Default
`experiments`	`type[SimulationExperiment] \| list[type[SimulationExperiment]]`	the simulation experiments.	required
`output_path`	`Path`	directory of the results and the report.	required
`base_path`	`Path \| None`	base path of the simulation experiments.	`None`
`data_path`	`Path \| Iterable[Path] \| None`	path or paths of the datasets of the simulation experiments.	`None`
`show_report`	`bool`	open the report in a web browser.	`False`
`raise_on_failure`	`bool`	raise an `ExperimentRunError` when an experiment or a figure failed, after every experiment ran and the report was written.	`False`
`figure_settings`	`FigureSettings \| Mapping[str, Any] \| None`	the settings of the figures of every experiment, see `ExperimentRunner.run_experiments`.	`None`

Returns:

Type	Description
`list[ExperimentResult]`	The results of the experiments.

Raises:

Type	Description
`ExperimentRunError`	with `raise_on_failure`, if something failed.