amici.sim.sundials.petab

Functionality for simulating PEtab problems.

This submodule contains all functionality related to simulating PEtab problems.

See also amici.importers.petab for importing PEtab problems.

For simulating PEtab v2 problems, the relevant classes are:

PetabSimulator: Simulate PEtab problems with AMICI.
ExperimentManager: Create amici.ExpData objects for PEtab experiments.

See PEtab 2.0 import for example usage. Note that the PEtab v2 API is still under development and may change in future releases.

The PEtab v1 legacy functionality is still available under amici.simulations.sim.sundials.petab.v1. Note that this functionality will be deprecated once the PEtab v2 import is stable.

Classes

`PetabSimulator`(em, *[, solver, num_threads])	Simulator for PEtab2 problems.
`ExperimentManager`(model, petab_problem)	Handles the creation of `ExpData` objects for a given model and PEtab problem.
`PetabSimulationResult`([edatas, rdatas, ...])	Container for results of a PEtab simulation.

class amici.sim.sundials.petab.ExperimentManager(model, petab_problem)[source]

Handles the creation of ExpData objects for a given model and PEtab problem.

The assumption is that we have a set of ExpData objects, one for each PEtab experiment. Those are updated based on a set of global parameters (PEtab problem parameters, as opposed to model parameters for a single experiment period).

__init__(model, petab_problem)[source]

Initialize the ExperimentManager.

Parameters:

model (amici._installation.amici.Model) – The AMICI model to use.
petab_problem (petab.v2.core.Problem) – The PEtab problem to use. This is expected to be the output of petab.v2.ExperimentsToSbmlConverter or an equivalent problem. This object must not be modified after the creation of this ExperimentManager instance.

apply_parameters(edata, problem_parameters)[source]

Apply problem parameters.

Update the parameter-dependent values of the given ExpData instance according to the provided problem parameters (i.e., values of the parameters in the PEtab parameter table).

This assumes that:

the ExpData instance was created by create_edata(),
no other changes except for calls to apply_parameters() were made,
and the PEtab problem was not modified since the creation of this ExperimentManager instance.

Parameters:

edata (amici._installation.amici.ExpData) – The ExpData instance to be updated. In case of errors, the state of edata is undefined.
problem_parameters (dict[str, float]) – Problem parameters to be applied.

Return type:

None

create_edata(experiment, problem_parameters=None)[source]

Create an ExpData object for a single experiment.

Sets timepoints, measurements, initial conditions, … based on the given experiment and the nominal parameters of the PEtab problem.

Parameters:

experiment (petab.v2.core.Experiment | str | None) – The experiment or experiment ID to create the ExpData for.
problem_parameters (dict[str, float] | None) – Optional dictionary of problem parameters to apply to the ExpData. If None, the nominal parameters of the PEtab problem are used.

Return type:

amici._installation.amici.ExpData

Returns:

The created ExpData object for the given experiment.

create_edatas()[source]

Create ExpData objects for all experiments.

Return type:: list[amici._installation.amici.ExpData]

property model: Model: The AMICI model used by this ExperimentManager.

property petab_problem: Problem

The PEtab problem used by this ExperimentManager.

This must not be modified.

class amici.sim.sundials.petab.PetabSimulationResult(edatas=<factory>, rdatas=<factory>, sllh=None, s2llh=None, sres=None)[source]

Container for results of a PEtab simulation.

Holds the per-experiment AMICI data objects and aggregated metrics produced by PetabSimulator.simulate.

__init__(edatas=<factory>, rdatas=<factory>, sllh=None, s2llh=None, sres=None)

edatas: list[ExpData]: List of amici.sim.sundials.ExpData instances, one per simulated experiment. These objects may be modified by subsequent operations.

property llh: float: The total log-likelihood across all experiments.

rdatas: list[ReturnDataView]: List of amici.sim.sundials.ReturnDataView instances, one per simulated experiment containing simulation outputs.

res()[source]

Concatenated residuals.

Return type:: numpy.ndarray | None
Returns:: Concatenated residuals from all experiments as a 1D numpy.ndarray, or None if not available.

s2llh: ndarray | None = None: Aggregated second-order sensitivities (Hessian or FIM-based) as a 2D numpy.ndarray in the order of Problem.x_free_ids. None if second-order sensitivities were not computed.

sllh: dict[str, float] | None = None: Aggregated first-order sensitivities of the log-likelihood with respect to PEtab problem parameters. Mapping from parameter ID to sensitivity value, or None if sensitivities were not computed.

sres: ndarray | None = None: Sensitivities of the residuals (if computed) as a numpy.ndarray, or None when not computed.

class amici.sim.sundials.petab.PetabSimulator(em, *, solver=None, num_threads=1)[source]

Simulator for PEtab2 problems.

This class is used to simulate all experiments of a given PEtab problem using a given AMICI model and solver, and to aggregate the results.

__init__(em, *, solver=None, num_threads=1)[source]

Initialize the simulator.

Parameters:

em (amici.sim.sundials.petab._v2.ExperimentManager) – The ExperimentManager to generate the amici.ExpData objects.
solver (amici._installation.amici.Solver | None) – The AMICI solver to use for the simulations. If not provided, a new solver with default settings will be used.
num_threads (int) – The number of threads to use for parallel simulation of experiments. Only relevant if multiple experiments are present in the PEtab problem, and if AMICI was compiled with OpenMP support.

property exp_man: ExperimentManager: The ExperimentManager used by this simulator.

property model: Model: The AMICI model used by this simulator.

simulate(problem_parameters=None)[source]

Simulate all experiments of the given PEtab problem.

Return type:

amici.sim.sundials.petab._v2.PetabSimulationResult

Returns:

A PetabSimulationResult instance containing the per-experiment data objects and aggregated results.

Note that the returned amici.sim.sundials.ExpData instances may be changed by subsequent calls to this function. Create a copy if needed.

Aggregated residual sensitivities are not implemented yet.

property solver: Solver: The AMICI solver used by this simulator.