AMICI-dev · dweindl · Dec 12, 2025 · Dec 11, 2025
@@ -135,7 +135,8 @@ def install_doxygen():
     "numpy": ("https://numpy.org/devdocs/", None),
     "sympy": ("https://docs.sympy.org/latest/", None),
     "python": ("https://docs.python.org/3", None),
-    "jax": ["https://jax.readthedocs.io/en/latest/", None],
+    "jax": ("https://jax.readthedocs.io/en/latest/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
 # Add notebooks prolog with binder links
@@ -342,6 +343,21 @@ def install_doxygen():
     ),
 ]
 
+
+# Avoid issues with classes exported from multiple modules, until we have
+#  a better solution.
+#   WARNING: duplicate object description of XXX, other instance in YYY,
+#   use :no-index: for one of them
+import amici.importers.antimony
+import amici.importers.bngl
+import amici.importers.pysb
+import amici.importers.sbml
+
+amici.importers.sbml.__all__.remove("MeasurementChannel")
+amici.importers.pysb.__all__.remove("MeasurementChannel")
+amici.importers.antimony.__all__.remove("MeasurementChannel")
+amici.importers.bngl.__all__.remove("MeasurementChannel")
+
 # Custom processing routines for docstrings and signatures
 
 typemaps = {

@@ -73,7 +73,7 @@
   {
    "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.set_free_parameter_by_name](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.set_free_parameter_by_name). Here, we set the model parameter `p1` to a value of `1e-3`."
+   "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 [Model.set_free_parameter_by_name](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.set_free_parameter_by_name). Here, we set the model parameter `p1` to a value of `1e-3`."
   },
   {
    "cell_type": "code",
@@ -85,7 +85,7 @@
   {
    "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.set_absolute_tolerance](https://amici.readthedocs.io/en/latest/generated/amici.amici.Solver.html#amici.amici.Solver.set_absolute_tolerance). Here we set the absolute integration tolerances to `1e-10`."
+   "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 [Solver.set_absolute_tolerance](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver.set_absolute_tolerance). Here we set the absolute integration tolerances to `1e-10`."
   },
   {
    "cell_type": "code",
@@ -104,7 +104,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "Model simulations can be executed using the [Model.simulate](https://amici.readthedocs.io/en/latest/generated/amici.amici.html#amici.amici.Model.simulate) method (or, alternatively, [amici.run_simulation](https://amici.readthedocs.io/en/latest/generated/amici.html#amici.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.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",
@@ -120,9 +120,7 @@
   {
    "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."
-   ]
+   "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."
   },
   {
    "cell_type": "code",
@@ -136,7 +134,7 @@
   {
    "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.get_state_names](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.get_state_names)"
+   "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 [Model.get_state_names](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.get_state_names)"
   },
   {
    "cell_type": "code",
@@ -160,9 +158,7 @@
   {
    "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 [ExampleExperimentalConditions example](https://amici.readthedocs.io/en/latest/ExampleExperimentalConditions.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."
-   ]
+   "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 [extended example](https://amici.readthedocs.io/en/latest/examples/getting_started_extended/GettingStartedExtended.html) notebook gives more detail about the model employed here and goes into the basics of sensitivity analysis. The [ExampleEquilibrationLogic](https://amici.readthedocs.io/en/latest/examples/example_steady_states/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 [ExampleExperimentalConditions example](https://amici.readthedocs.io/en/latest/examples/example_presimulation/ExampleExperimentalConditions.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/examples/example_petab/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": {

@@ -337,7 +337,7 @@
    "source": [
     "import logging\n",
     "\n",
-    "sbml_importer.sbml2amici(\n",
+    "model = sbml_importer.sbml2amici(\n",
     "    model_name,\n",
     "    model_output_dir,\n",
     "    verbose=logging.INFO,\n",
@@ -352,7 +352,7 @@
    "source": [
     "### Importing the module and loading the model\n",
     "\n",
-    "If everything went well, we can now import the newly generated Python module containing our model:"
+    "A model instance for simulation is returned by `sbml2amici`, but we can also import the module containing the model class later using `amici.import_model_module`:"
    ]
   },
   {
@@ -1080,20 +1080,20 @@
    "source": [
     "model = model_module.get_model()\n",
     "model.set_timepoints(np.linspace(0, 10, 11))\n",
-    "model.require_sensitivities_for_all_parameters()  # sensitivities w.r.t. all parameters\n",
-    "# model.set_parameter_list([1, 2])                          # sensitivities\n",
-    "# w.r.t. the specified parameters\n",
-    "model.set_parameter_scale(\n",
-    "    ParameterScaling.none\n",
-    ")  # parameters are used as-is (not log-transformed)\n",
+    "\n",
+    "# sensitivities w.r.t. all parameters\n",
+    "model.require_sensitivities_for_all_parameters()\n",
+    "# sensitivities w.r.t. the specified parameters:\n",
+    "# model.set_parameter_list([1, 2])\n",
+    "\n",
+    "# parameters are used as-is (not log-transformed)\n",
+    "model.set_parameter_scale(ParameterScaling.none)\n",
     "\n",
     "solver = model.create_solver()\n",
-    "solver.set_sensitivity_method(\n",
-    "    SensitivityMethod.forward\n",
-    ")  # forward sensitivity analysis\n",
-    "solver.set_sensitivity_order(\n",
-    "    SensitivityOrder.first\n",
-    ")  # first-order sensitivities\n",
+    "# forward sensitivity analysis\n",
+    "solver.set_sensitivity_method(SensitivityMethod.forward)\n",
+    "# first-order sensitivities\n",
+    "solver.set_sensitivity_order(SensitivityOrder.first)\n",
     "\n",
     "rdata = run_simulation(model, solver)\n",
     "\n",
@@ -1141,11 +1141,12 @@
     ")\n",
     "\n",
     "# enable sensitivities\n",
-    "solver.set_sensitivity_order(SensitivityOrder.first)  # First-order ...\n",
-    "solver.set_sensitivity_method(\n",
-    "    SensitivityMethod.adjoint\n",
-    ")  # ... adjoint sensitivities\n",
-    "model.require_sensitivities_for_all_parameters()  # ... w.r.t. all parameters\n",
+    "# First-order ...\n",
+    "solver.set_sensitivity_order(SensitivityOrder.first)\n",
+    "# ... adjoint sensitivities\n",
+    "solver.set_sensitivity_method(SensitivityMethod.adjoint)\n",
+    "# ... w.r.t. all parameters\n",
+    "model.require_sensitivities_for_all_parameters()\n",
     "\n",
     "# compute adjoint sensitivities\n",
     "rdata = run_simulation(model, solver, edata)\n",

@@ -36,7 +36,7 @@ Solution Jump Discontinuities
 
 SUNDIALS by itself does not support solution jump discontinuities. We
 implement support by accessing private SUNDIALS API in
-:cpp:func:`amici::Solver::reset_tate`,
+:cpp:func:`amici::Solver::reset_state`,
 :cpp:func:`amici::Solver::reinit_post_process` and
 :cpp:func:`amici::Solver::reinit_post_process_b`. These functions reset interval
 variables to initial values to simulate a fresh integration start, but

@@ -217,7 +217,7 @@ variables control various behaviours during model import and compilation:
      - ``AMICI_IMPORT_NPROCS=4``
    * - ``AMICI_EXPERIMENTAL_SBML_NONCONST_CLS``
      - Compute conservation laws for non-constant species. SBML-import only.
-       See :py:func:`amici.sbml_import.SbmlImporter.sbml2amici`.
+       See :py:meth:`amici.sbml_import.SbmlImporter.sbml2amici`.
      -
 
 

@@ -14,6 +14,7 @@ AMICI Python API
    amici.importers.antimony
    amici.importers.petab
    amici.importers.petab.v1
+   amici.importers.utils
    amici.jax
    amici.sim.sundials
    amici.sim.sundials.plotting

@@ -910,7 +910,7 @@ class Model : public AbstractModel, public ModelDimensions {
      * C} \f$ will be added. This enables least-squares optimization for
      * variables with Gaussian noise assumption and parameter dependent standard
      * deviation sigma. The constant \f$ C \f$ can be set via
-     * :meth:`setMinimumSigmaResiduals`.
+     * :meth:`set_minimum_sigma_residuals`.
      *
      * @param sigma_res if true, additional residuals are added
      */

@@ -302,7 +302,7 @@ class Solver {
      * @brief Get the relative tolerances for the forward problem
      *
      * Same tolerance is used for the backward problem if not specified
-     * differently via setRelativeToleranceASA.
+     * differently via \ref Solver::set_relative_tolerance_b.
      *
      * @return relative tolerances
      */
@@ -312,7 +312,7 @@ class Solver {
      * @brief Sets the relative tolerances for the forward problem
      *
      * Same tolerance is used for the backward problem if not specified
-     * differently via setRelativeToleranceASA.
+     * differently via \ref Solver::set_relative_tolerance_b.
      *
      * @param rtol relative tolerance (non-negative number)
      */
@@ -322,7 +322,7 @@ class Solver {
      * @brief Get the absolute tolerances for the forward problem
      *
      * Same tolerance is used for the backward problem if not specified
-     * differently via setAbsoluteToleranceASA.
+     * differently via \ref Solver::set_absolute_tolerance_b.
      *
      * @return absolute tolerances
      */
@@ -332,7 +332,7 @@ class Solver {
      * @brief Sets the absolute tolerances for the forward problem
      *
      * Same tolerance is used for the backward problem if not specified
-     * differently via setAbsoluteToleranceASA.
+     * differently via \ref Solver::set_absolute_tolerance_b.
      *
      * @param atol absolute tolerance (non-negative number)
      */
@@ -482,7 +482,7 @@ class Solver {
      *
      * Steady state sensitivity simulation tolerances are the product of the
      * sensitivity simulation tolerances and this factor, unless manually set
-     * with `set(Absolute/Relative)ToleranceSteadyStateSensi()`.
+     * with `set_{absolute,relative}_tolerance_steady_state_sensi()`.
      *
      * @return steady state simulation tolerance factor
      */
@@ -493,7 +493,7 @@ class Solver {
      *
      * Steady state sensitivity simulation tolerances are the product of the
      * sensitivity simulation tolerances and this factor, unless manually set
-     * with `set(Absolute/Relative)ToleranceSteadyStateSensi()`.
+     * with `set_{absolute,relative}_tolerance_steady_state_sensi()`.
      *
      * @param factor tolerance factor (non-negative number)
      */
@@ -960,49 +960,56 @@ class Solver {
     void store_diagnosis_b(int which) const;
 
     /**
-     * @brief Accessor ns
+     * @brief Number of integration steps for the forward problem
+     * (dimension: nt).
      *
      * @return ns
      */
     std::vector<int> const& get_num_steps() const { return ns_; }
 
     /**
-     * @brief Accessor nsB
+     * @brief Number of integration steps for the backward problem
+     * (dimension: nt).
      *
      * @return nsB
      */
     std::vector<int> const& get_num_steps_b() const { return nsB_; }
 
     /**
-     * @brief Accessor nrhs
+     * @brief Number of right hand side evaluations for the forward problem
+     * (dimension: nt)
      *
      * @return nrhs
      */
     std::vector<int> const& get_num_rhs_evals() const { return nrhs_; }
 
     /**
-     * @brief Accessor nrhsB
+     * @brief Number of right hand side evaluations for the backward problem
+     * (dimension: nt)
      *
      * @return nrhsB
      */
     std::vector<int> const& get_num_rhs_evals_b() const { return nrhsB_; }
 
     /**
-     * @brief Accessor netf
+     * @brief Number of error test failures during the forward simulation
+     * (dimension: nt)
      *
      * @return netf
      */
     std::vector<int> const& get_num_err_test_fails() const { return netf_; }
 
     /**
-     * @brief Accessor netfB
+     * @brief Number of error test failures during the backward simulation
+     * (dimension: nt)
      *
      * @return netfB
      */
     std::vector<int> const& get_num_err_test_fails_b() const { return netfB_; }
 
     /**
-     * @brief Accessor nnlscf
+     * @brief Number of non-linear solver convergence failures during the
+     * forward simulation (dimension: nt).
      *
      * @return nnlscf
      */
@@ -1011,7 +1018,8 @@ class Solver {
     }
 
     /**
-     * @brief Accessor nnlscfB
+     * @brief Number of non-linear solver convergence failures during the
+     * backward simulation (dimension: nt).
      *
      * @return nnlscfB
      */
@@ -1185,7 +1193,7 @@ class Solver {
      * @brief Solves the forward problem until a predefined timepoint
      *
      * @param tout timepoint until which simulation should be performed
-     * @param itask task identifier, can be CV_NORMAL or CV_ONE_STEP
+     * @param itask task identifier, can be \c CV_NORMAL or \c CV_ONE_STEP
      * @return status flag indicating success of execution
      */
     virtual int solve(realtype tout, int itask) const = 0;
@@ -1195,24 +1203,24 @@ class Solver {
      * (adjoint only)
      *
      * @param tout timepoint until which simulation should be performed
-     * @param itask task identifier, can be CV_NORMAL or CV_ONE_STEP
+     * @param itask task identifier, can be \c CV_NORMAL or \c CV_ONE_STEP
      * @param ncheckPtr pointer to a number that counts the internal
      * checkpoints
      * @return status flag indicating success of execution
      */
     virtual int solve_f(realtype tout, int itask, int* ncheckPtr) const = 0;
 
     /**
-     * @brief reinit_post_process_f postprocessing of the solver memory after a
-     * discontinuity in the forward problem
+     * @brief Postprocess the solver memory after a discontinuity in the
+     * forward problem
      *
      * @param tnext next timepoint (defines integration direction)
      */
     virtual void reinit_post_process_f(realtype tnext) const = 0;
 
     /**
-     * @brief reinit_post_process_b postprocessing of the solver memory after a
-     * discontinuity in the backward problem
+     * @brief Postprocess the solver memory after a discontinuity in the
+     * backward problem
      *
      * @param tnext next timepoint (defines integration direction)
      */
@@ -2156,13 +2164,15 @@ class Solver {
     mutable std::vector<int> netfB_;
 
     /**
-     * number of linear solver convergence failures forward problem (dimension:
-     * nt) */
+     * number of non-linear solver convergence failures forward problem
+     * (dimension: nt)
+     */
     mutable std::vector<int> nnlscf_;
 
     /**
-     * number of linear solver convergence failures backward problem (dimension:
-     * nt) */
+     * number of non-linear solver convergence failures backward problem
+     * (dimension: nt)
+     */
     mutable std::vector<int> nnlscfB_;
 
     /** employed order forward problem (dimension: nt) */

@@ -181,7 +181,7 @@ class DEModel:
         partial derivative in the next recursion. prevents infinite recursion
 
     :ivar _simplify:
-        If not None, this function will be used to simplify symbolic
+        If not ``None``, this function will be used to simplify symbolic
         derivative expressions. Receives sympy expressions as only argument.
         To apply multiple simplifications, wrap them in a lambda expression.
 
@@ -219,8 +219,7 @@ def __init__(
             see :meth:`DEModel._simplify`
 
         :param cache_simplify:
-            Whether to cache calls to the simplify method. Can e.g. decrease
-            import times for models with events.
+            Whether to cache calls to the simplify method.
         """
         self._differential_states: list[DifferentialState] = []
         self._algebraic_states: list[AlgebraicState] = []