# 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 models via the class.

#### Status of SBML support in Python-AMICI¶

Python-AMICI currently passes 850 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

• Models without species

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 model into AMICI, first, load an SBML file using the class:

import amici


the SBML model as imported by libSBML is available as:

sbml_model = sbml_importer.sbml

##### Constants¶

Model parameters that should be considered 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 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'}

##### Model compilation¶

To generate a Python module from the SBML model, call the method , 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 models via .

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

### PEtab import¶

AMICI can import -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 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 :

rdata = amici.runAmiciSimulation(model, solver)


## 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'