Using AMICI’s Python interface

In the following we will give a detailed overview how to specify models in Python and how to call the generated simulation files.

Model definition

This guide will guide the user on how to specify models to import and simulate them using the Python interface. Further examples are available in the AMICI repository in the python/examples directory.

SBML import

AMICI can import SBML models via the amici.sbml_import.SbmlImporter() class.

Status of SBML support in Python-AMICI

Python-AMICI currently passes 862 out of the 1780 (~48%) test cases from the semantic SBML Test Suite (current status).

In addition, we currently plan to add support for the following features (see corresponding issues for details and progress):

• Events (currently Matlab-only)

• Algebraic rules

contributions are welcome.

However, the following features are unlikely to be supported:

• SBML extensions

• factorial(), ceil(), floor(), due to incompatibility with symbolic sensitivity computations

• delay() due to missing SUNDIALS solver support

How to import an SBML model into AMICI

To import an SBML model into AMICI, first, load an SBML file using the amici.sbml_import.SbmlImporter() class:

import amici
sbml_importer = amici.SbmlImporter('model_steadystate_scaled.sbml')

the SBML model as imported by libSBML is available as:

sbml_model = sbml_importer.sbml

Constants

Model parameters that should be considered constants can be specified in a list of strings specifying the SBML ID of the respective parameter, e.g.:

constant_parameters=['k4']

Observables

Observables are specified as a dictionary with observable ID as key and observable formula as value.

A convenient way for specifying observables for an SBML model is storing them as AssignmentRules. Assignment rules that should be considered as observables can then be extracted using the amici.sbml_import.assignmentRules2observables() function, e.g.:

observables = amici.assignmentRules2observables(sbml, filter_function=lambda variable:
                                                variable.getId().startswith('observable_') and not variable.getId().endswith('_sigma'))

Standard deviations

Standard deviations can be specified as dictionaries, such as:

sigmas = {'observable_x1withsigma': 'observable_x1withsigma_sigma'}

Noise distributions

Various noise distributions including normal and Laplace and discrete distributions, and scale transformations including linear, log and log10 are supported:

noise_distributions = {'observable_x1withsigma': 'log-normal'}

Find details in amici.sbml_import.noise_distribution_to_cost_function().

Model compilation

To generate a Python module from the SBML model, call the method amici.sbml_import.SbmlImporter.sbml2amici(), passing all the previously defined model specifications:

sbml_importer.sbml2amici('test', 'test',
                         observables=observables,
                         constant_parameters=constant_parameters,
                         sigmas=sigmas)

Full example

See here for a full example.

PySB import

AMICI can import PySB models via amici.pysb_import.pysb2amici().

BioNetGen and Kappa models can be imported into AMICI using PySB.

PEtab import

AMICI can import PEtab-based model definitions and run simulations for the specified simulations conditions. For usage, see python/examples/example_petab/petab.ipynb.

Importing plain ODEs

The AMICI Python interface does not currently support direct import of ODEs. However, it is straightforward to encode them as RateRules in an SBML model. The yaml2sbml package may come in handy, as it facilitates generating SBML models from a YAML-based specification of an ODE model. Besides the SBML model it can also create PEtab files.

SED-ML import

We also plan to implement support for the Simulation Experiment Description Markup Language (SED-ML).

Model simulation

AMICI model import creates a Python module for simulation of the respective model. To use the model module, the model directory has to be manually added to the python path:

import sys
sys.path.insert(0, 'test')

the compiled model can then be imported as:

import test as model_module

It is usually more convenient to use amici.import_model_module() for that purpose.

To obtain a model instance call the getModel() method. This model instance will be instantiated using the default parameter values specified in the imported model:

model = model_module.getModel()

Specify the simulation timepoints via amici.Model.setTimepoints():

model.setTimepoints(np.linspace(0, 60, 60))

For simulation, we need to generate a solver instance:

solver = model.getSolver()

The model simulation can now be carried out using amici.runAmiciSimulation():

rdata = amici.runAmiciSimulation(model, solver)

Examples

• AMICI Python example “steadystate”
• Using PEtab
• AMICI Python example “presimulation”
• AMICI documentation example of the steady state solver logic

Miscellaneous

OpenMP support for parallelized simulation for multiple experimental conditions

AMICI can be built with OpenMP support, which allows to parallelize model simulations for multiple experimental conditions.

On Linux and OSX this is enabled by default. This can be verified using:

import amici
amici.compiledWithOpenMP()

If not already enabled by default, you can enable OpenMP support by setting the environment variables AMICI_CXXFLAGS and AMICI_LDFLAGS to the correct OpenMP flags of your compiler and linker, respectively. This has to be done for both AMICI package installation and model compilation. When using gcc on Linux, this would be:

# on your shell:
AMICI_CXXFLAGS=-fopenmp AMICI_LDFLAGS=-fopenmp pip3 install amici

# in python, before model compilation:
import os
os.environ['AMICI_CXXFLAGS'] = '-fopenmp'
os.environ['AMICI_LDFLAGS'] = '-fopenmp'