Getting started tutorial

.github/workflows/test_python_cplusplus.yml

@@ -85,10 +85,18 @@ jobs:
           --cov-report=xml:"${AMICI_DIR}/build/coverage_py.xml" \
           --cov-append \
           ${AMICI_DIR}/python/tests
+
+    - name: example notebooks
+      run: |
+        scripts/runNotebook.sh python/examples/example_*/
+
+    - name: doc notebooks
+      run: |
+        scripts/runNotebook.sh documentation/GettingStarted.ipynb
 
     - name: Codecov Python
       uses: codecov/codecov-action@v1
-      with:
+      with: 
         token: ${{ secrets.CODECOV_TOKEN }}
         file: ./build/coverage_py.xml
         flags: python

.github/workflows/test_python_ver_matrix.yml

@@ -66,7 +66,3 @@ jobs:
           && pip3 install pytest \
           && pip3 install git+https://github.com/pysb/pysb \
           && python3 -m pytest --ignore-glob=*petab* ${AMICI_DIR}/python/tests
-
-    - name: notebooks
-      run: |
-        scripts/runNotebook.sh python/examples/example_*/

README.md

@@ -85,7 +85,7 @@ To install AMICI, first read the installation instructions for
 [Matlab](https://amici.readthedocs.io/en/develop/matlab_installation.html).
 
 To get you started with Python-AMICI, the best way might be checking out this
-[Jupyter notebook](https://github.com/AMICI-dev/AMICI/blob/master/python/examples/example_steadystate/ExampleSteadystate.ipynb).
+[Jupyter notebook](https://github.com/AMICI-dev/AMICI/blob/master/documentation/GettingStarted.ipynb).
 
 To get started with Matlab-AMICI, various examples are available
 in [matlab/examples/](https://github.com/AMICI-dev/AMICI/tree/master/matlab/examples).

documentation/GettingStarted.ipynb

@@ -0,0 +1,226 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting Started in AMICI\n",
+    "\n",
+    "This notebook is a brief tutorial for new users that explains the first steps necessary for model simulation in AMICI, including pointers to documentation and more advanced notebooks."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Model Compilation\n",
+    "Before simulations can be run, the model must be imported and compiled. In this process, AMICI performs all symbolic manipulations that later enable scalable simulations and efficient sensitivity computation. The first towards model compilation is the creation of an [SbmlImporter](https://amici.readthedocs.io/en/latest/generated/amici.sbml_import.SbmlImporter.html) instance, which requires an SBML Document that specifies the model using the [Systems Biology Markup Language (SBML)](http://sbml.org/Main_Page). \n",
+    "\n",
+    "For the purpose of this tutorial, we will use `model_steadystate_scaled.xml`, which is contained in the same directory as this notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import amici\n",
+    "sbml_importer = amici.SbmlImporter('model_steadystate_scaled.xml')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we will compile the model as python extension using the [amici.SBMLImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.sbml_import.SbmlImporter.html#amici.sbml_import.SbmlImporter.sbml2amici) method. The first two arguments of this method are the name of the model, which will also be the name of the generated python module, and the model directory, which defines the directory in which the model module will be placed. Compilation will take a couple of seconds."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_name = 'model_steadystate'\n",
+    "model_dir = 'model_dir'\n",
+    "sbml_importer.sbml2amici(model_name, model_dir)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Loading the model module\n",
+    "To run simulations, we need to instantiate [amici.Model](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html) and [amici.Solver](https://amici.readthedocs.io/en/latest/generated/amici.amici.Solver.html) instances. As simulations requires instances matching the imported model, they have to be imported from the generated model module. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# load the model module\n",
+    "model_module = amici.import_model_module(model_name, model_dir)\n",
+    "# instantiate model\n",
+    "model = model_module.getModel()\n",
+    "# instantiate solver\n",
+    "solver = model.getSolver()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The model allows the user to manipulate model related properties of simulations. This includes the values of model parameters that can be set by using [amici.Model.setParameterByName](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.setParameterByName). Here, we set the model parameter `p1` to a value of `1e-3`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model.setParameterByName('p1',1e-3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In contrast, the solver instance allows the specification of simulation related properties. This includes setting options for the SUNDIALS solver such as absolute tolerances via [amici.Solver.setAbsoluteTolerance](https://amici.readthedocs.io/en/latest/generated/amici.amici.Solver.html#amici.amici.Solver.setAbsoluteTolerance). Here we set the absolute integration tolerances to `1e-10`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "solver.setAbsoluteTolerance(1e-10)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Running Model Simulations"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Model simulations can be executed using the [amici.runAmiciSimulations](https://amici.readthedocs.io/en/latest/generated/amici.html#amici.runAmiciSimulation) routine. By default the model does not not contain any timepoints for which the model is to be simulated. Here we define a simulation timecourse with two timepoints at `0` and `1` and then run the simulation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# set timepoints\n",
+    "model.setTimepoints([0,1])\n",
+    "rdata = amici.runAmiciSimulation(model, solver)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Simulation results are returned as [ReturnData](https://amici.readthedocs.io/en/latest/generated/amici.amici.ReturnData.html) instance. The simulated SBML species are stored as `x` attribute, where rows correspond to the different timepoints and columns correspond to different species."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([[0.1       , 0.4       , 0.7       ],\n",
+       "       [0.98208413, 0.51167992, 0.10633388]])"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "rdata.x"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "All results attributes are always ordered according to the model. For species, this means that the columns of `rdata.x` match the ordering of species in the model, which can be accessed as [amici.Model.getStateNames](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.getStateNames)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('x1', 'x2', 'x3')"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model.getStateNames()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This notebook only explains the basics of AMICI simulations. In general, AMICI simulations are highly customizable and can also be used to simulate sensitivities. The [ExampleSteadystate](https://amici.readthedocs.io/en/latest/ExampleSteadystate.html) notebook in this folder gives more detail about the model employed here and goes into the basics of sensitivity analysis. The [ExampleEquilibrationLogic](https://amici.readthedocs.io/en/latest/ExampleEquilibrationLogic.html) notebook, builds on this by using a modified version of this model to give detailed insights into the methods and options to compute steady states before and after simulations, as well as respective sensitivities. The [Presimulation example](https://amici.readthedocs.io/en/latest/model_presimulation.html) notebook, goes into the details of how even more complex experimental setups, such as addition of drugs at predefined timepoints, can be simulated in AMICI. Finally, the [petab](https://amici.readthedocs.io/en/latest/petab.html) notebook explains how standardized definitions of experimental data and conditions in the [PEtab](https://github.com/PEtab-dev/PEtab) format can be imported in AMICI."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  },
+  "toc": {
+   "base_numbering": 1,
+   "nav_menu": {},
+   "number_sections": true,
+   "sideBar": true,
+   "skip_h1_title": false,
+   "title_cell": "Table of Contents",
+   "title_sidebar": "Contents",
+   "toc_cell": false,
+   "toc_position": {},
+   "toc_section_display": true,
+   "toc_window_display": false
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

documentation/model_steadystate_scaled.xml

@@ -0,0 +1 @@
+../python/examples/example_steadystate/model_steadystate_scaled.xml