diff --git a/doc/examples/getting_started/GettingStarted.ipynb b/doc/examples/getting_started/GettingStarted.ipynb index 94e81d458d..e182825c63 100644 --- a/doc/examples/getting_started/GettingStarted.ipynb +++ b/doc/examples/getting_started/GettingStarted.ipynb @@ -6,7 +6,7 @@ "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." + "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. Here, we focus on AMICI's SUNDIALS backend. Users interested in using the JAX backend can find a respective tutorial in the [ExampleJAX](https://amici.readthedocs.io/en/latest/examples/example_jax/ExampleJax.html) notebook." ] }, { @@ -14,7 +14,8 @@ "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 step 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)](https://sbml.org/).\n", + "\n", + "Before any 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 step towards model compilation is the creation of an [SbmlImporter](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.SbmlImporter) instance, which requires an SBML Document that specifies the model using the [Systems Biology Markup Language (SBML)](https://sbml.org/).\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." ] @@ -34,9 +35,7 @@ { "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." - ] + "source": "Next, we will compile the model as python extension using the [SBMLImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.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", @@ -54,7 +53,9 @@ "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 require instances matching the imported model, they have to be imported from the generated model module." + "\n", + "To run simulations, we need to instantiate [amici.sim.sundials.Model](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model) and [amici.sim.sundials.Solver](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver) instances.\n", + "As simulations require instances matching the imported model, they have to be imported from the generated model module." ] }, { @@ -109,7 +110,7 @@ { "cell_type": "markdown", "metadata": {}, - "source": "Model simulations can be executed using the [Model.simulate](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.simulate) method (or, alternatively, [amici.run_simulation](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.run_simulation)). By default, the model does not contain any output timepoints for which the model is to be simulated. Here we define a simulation timecourse with two output timepoints at `0` and `1` and then run the simulation." + "source": "Model simulations can be executed using the [Model.simulate](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.simulate) method (or, alternatively, [amici.sim.sundials.run_simulation](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.run_simulation)). By default, the model does not contain any output timepoints for which the model is to be simulated. Here we define a simulation timecourse with two output timepoints at `0` and `1` and then run the simulation." }, { "cell_type": "code", @@ -125,7 +126,7 @@ { "cell_type": "markdown", "metadata": {}, - "source": "Simulation results are returned as [ReturnData](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.ReturnData) instance. The simulated SBML species are stored as `x` attribute, where rows correspond to the different timepoints and columns correspond to different species." + "source": "Simulation results are returned as [amici.sim.sundials.ReturnData](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.ReturnData) 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", @@ -175,6 +176,17 @@ "plot_state_trajectories(rdata)" ] }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Summary\n", + "\n", + "This notebook explained the first steps necessary to run simulations in AMICI. The main steps include the compilation of the model, importing the resulting model module, instantiation of model and solver objects, and running simulations using those objects.\n", + "\n", + "![amici objects](../../gfx/amici_objects.png \"The main AMICI objects and their relationships\")" + ] + }, { "cell_type": "markdown", "metadata": {}, diff --git a/doc/examples/getting_started_extended/GettingStartedExtended.ipynb b/doc/examples/getting_started_extended/GettingStartedExtended.ipynb index 812e05911a..9fc598ec28 100644 --- a/doc/examples/getting_started_extended/GettingStartedExtended.ipynb +++ b/doc/examples/getting_started_extended/GettingStartedExtended.ipynb @@ -147,7 +147,7 @@ "\n", "Specifying the observation model (i.e., the quantities that are observed, as well as the respective error models) is beyond the scope of SBML. Here we define that manually.\n", "\n", - "If you are looking for a more scalable way of defining observables, then checkout [PEtab](https://github.com/PEtab-dev/PEtab). Another possibility is using SBML's [`AssignmentRule`s](https://sbml.org/software/libsbml/5.18.0/docs/formatted/python-api/classlibsbml_1_1_assignment_rule.html) to specify model outputs within the SBML file.\n", + "If you are looking for a more scalable way of defining observables, then checkout [PEtab](https://github.com/PEtab-dev/PEtab). Another possibility is using SBML's [AssignmentRules](https://sbml.org/software/libsbml/5.18.0/docs/formatted/python-api/classlibsbml_1_1_assignment_rule.html) to specify model outputs within the SBML file.\n", "\n", "\n", "\n", diff --git a/doc/gfx/amici_objects.png b/doc/gfx/amici_objects.png new file mode 100644 index 0000000000..4bd15eb1d3 Binary files /dev/null and b/doc/gfx/amici_objects.png differ diff --git a/doc/gfx/amici_objects.svg b/doc/gfx/amici_objects.svg new file mode 100644 index 0000000000..3b9d1a0b0b --- /dev/null +++ b/doc/gfx/amici_objects.svg @@ -0,0 +1,580 @@ + + + +ModelReturnDataxt=f(x)dxdtACBhigh-levelmodelSolverExpData=f(x)dxdtmodel moduleclass Modeldef get_model()