diff --git a/documentation/PYTHON.md b/documentation/PYTHON.md index 4935aada46..eb2deb944c 100644 --- a/documentation/PYTHON.md +++ b/documentation/PYTHON.md @@ -1,87 +1,150 @@ # Python Interface {#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. +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 in Python using SBML. For example implementations see the examples in the python/examples directory. +This guide will guide the user on how to specify models to import and simulate +them using the Python interface. +For example implementations see the examples in the `python/examples` +directory. -### SBML input +### SBML import -First, import an sbml file using the `amici.sbml_import.SbmlImporter` class: +[SBML](http://sbml.org/) is a commonly used format for specifying systems +biology models. To import an SBML model into AMICI, first, load an SBML file +using the `amici.sbml_import.SbmlImporter` class: import amici - sbmlImporter = amici.SbmlImporter('model_steadystate_scaled.sbml') - -the sbml document as imported by [libSBML](http://sbml.org/Software/libSBML) is available as + sbml_importer = amici.SbmlImporter('model_steadystate_scaled.sbml') - sbml = sbmlImporter.sbml +the SBML model as imported by [libSBML](http://sbml.org/Software/libSBML) +is available as -### Constants + sbml_model = sbml_importer.sbml -parameters that should be considered constants can be specified in a list of strings specifying the respective SbmlId of a parameter. +#### Constants - constantParameters=['k4'] +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.: -### Observables + constant_parameters=['k4'] -Assignment rules that should be considered as observables can extracted using the `amici.assignmentRules2observables` function. +#### 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 `AssignmentRule`s. Assignment rules that should be considered as observables +can then be extracted using the `amici.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 -standard deviations can be specified as dictionaries ... +Standard deviations can be specified as dictionaries ... sigmas = {'observable_x1withsigma': 'observable_x1withsigma_sigma'} -## Model Compilation +#### Model Compilation -to compile the sbml as python module, the user has to call the method `amici.sbml_import.SbmlImporter.sbml2amici`, passing all the previously defined model specifications +To generate a Python module from the SBML model, call the method +`amici.sbml_import.SbmlImporter.sbml2amici`, passing all the previously defined +model specifications: - sbmlImporter.sbml2amici('test', 'test', - observables=observables, - constantParameters=constantParameters, - sigmas=sigmas) + sbml_importer.sbml2amici('test', 'test', + observables=observables, + constant_parameters=constant_parameters, + sigmas=sigmas) -Note: To build AMICI with OpenMP support, which allows to parallelize model simulations of multiple -experimental conditions, set 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, use: +### PySB import - # on your shell: - AMICI_CXXFLAGS=-fopenmp AMICI_LDFLAGS=-fopenmp pip3 install amici +[PySB](http://pysb.org/) is a tool for specifying rule-based systems biology +models as Python code. AMICI can import PySB models via +[`amici.pysb_import.pysb2amici`](https://amici.readthedocs.io/en/latest/generated/amici.pysb_import.html#amici.pysb_import.pysb2amici). - # in python, before model compilation: - import os - os.environ['AMICI_CXXFLAGS'] = '-fopenmp' - os.environ['AMICI_LDFLAGS'] = '-fopenmp' +[BioNetGen](https://www.csb.pitt.edu/Faculty/Faeder/?page_id=409) and +[Kappa](https://kappalanguage.org/) models can be imported into AMICI using +PySB. + +### PEtab import + +[PEtab](https://github.com/PEtab-dev/PEtab) is a format for specifying +parameter estimation problems. It is based on an SBML model and tab-separated +value files specifying the observation mdoel and experimental conditions. + +AMICI can import PEtab-based model definitions and run simulations for the +specified simulations conditions. For usage, see +[python/examples/example_petab/petab.ipynb](https://github.com/AMICI-dev/AMICI/blob/develop/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](https://github.com/martamatos/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](https://github.com/PEtab-dev/PEtab) files. ## Model Simulation -currently the model folder has to be manually added to the python path - +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 now be imported as python module - - import test as modelModule -to obtain a model instance call the `getModel()` method. This model instance will be instantiated using the defautl parameter values specified in the sbml. +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 = modelModule.getModel() + model = model_module.getModel() -then pass the simulation timepoints to `amici.Model.setTimepoints` +Specify the simulation timepoints via `amici.Model.setTimepoints`: model.setTimepoints(np.linspace(0, 60, 60)) - -for simulation we need to generate a solver instance + +For simulation, we need to generate a solver instance: solver = model.getSolver() - -the model simulation can now be carried out using `amici.runAmiciSimulation` - + +The model simulation can now be carried out using `amici.runAmiciSimulation`: + rdata = amici.runAmiciSimulation(model, solver) + +## Building models with OpenMP support + +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'