doc: Fix formatting, update names, fix swig-ignores (#3156)

* doc: Fix formatting, update names, fix swig-ignores

Fix formatting, update object names, fix swig-ignores

* escape underscores; fixes #3153

* update links

Author: dweindl

doc/examples/example_errors.ipynb

@@ -137,9 +137,9 @@
     "\n",
     "The number of steps the solver has to take is closely related to the chosen error tolerance. More accurate results, more steps. Therefore, this problem can be solved in two ways:\n",
     "\n",
-    "1. Increasing the maximum number of steps via [Solver.set_max_steps](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.Solver.html#amici.sim.sundials.Solver.set_max_steps). Note that this will increase the time required for simulation, and that simulation may still fail eventually. Sometimes it may be preferable to not increase this limit but rather fail fast. Also note that increasing the number of allowed steps increase RAM requirements (even if fewer steps are actually taken), so don't set this to ridiculously large values in order to avoid this error.\n",
+    "1. Increasing the maximum number of steps via [Solver.set_max_steps](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver.set_max_steps). Note that this will increase the time required for simulation, and that simulation may still fail eventually. Sometimes it may be preferable to not increase this limit but rather fail fast. Also note that increasing the number of allowed steps increase RAM requirements (even if fewer steps are actually taken), so don't set this to ridiculously large values in order to avoid this error.\n",
     "\n",
-    "2. Reducing the number of steps CVODES has to take. This is determined by the required error tolerance. There are various solver error tolerances than can be adjusted. The most relevant ones are those controlled via [Solver.set_relative_tolerance()](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.Solver.html#amici.sim.sundials.Solver.set_relative_tolerance) and [Solver.set_absolute_tolerance()](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.Solver.html#amici.sim.sundials.Solver.set_absolute_tolerance).\n",
+    "2. Reducing the number of steps CVODES has to take. This is determined by the required error tolerance. There are various solver error tolerances than can be adjusted. The most relevant ones are those controlled via [Solver.set_relative_tolerance()](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver.set_relative_tolerance) and [Solver.set_absolute_tolerance()](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver.set_absolute_tolerance).\n",
     "\n",
     "So, let's fix that:"
    ]

doc/examples/example_large_models/example_performance_optimization.ipynb

@@ -19,7 +19,7 @@
     "4. Compiling the generated code\n",
     "5. Simulating the model\n",
     "\n",
-    "![AMICI workflow](https://raw.githubusercontent.com/AMICI-dev/AMICI/master/doc/gfx/amici_workflow.png)\n",
+    "![AMICI workflow](https://raw.githubusercontent.com/AMICI-dev/AMICI/main/doc/gfx/amici_workflow.png)\n",
     "\n",
     "There are various options to speed up individual steps of this process. Generally, faster import comes with slower simulation and vice versa. During parameter estimation, a model is often imported only once, and then millions of simulations are run. Therefore, faster simulation will easily compensate for slower import (one-off cost). In other cases, many models may to have to be imported, but only few simulations will be executed. In this case, faster import may be more relevant.\n",
     "\n",
@@ -71,15 +71,15 @@
     "\n",
     "#### Fixing parameters\n",
     "\n",
-    "By default, AMICI will generate sensitivity equations with respect to all model parameters. If it is clear upfront, that sensitivities with respect to certain parameters will not be required, their IDs can be passed to [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.SbmlImporter.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html?highlight=pysb2amici#amici.importers.pysb.pysb2amici) via the `fixed_parameters` argument to not generate the respective equations. This will reduce CPU time and RAM requirements during import and simulation.\n",
+    "By default, AMICI will generate sensitivity equations with respect to all model parameters. If it is clear upfront, that sensitivities with respect to certain parameters will not be required, their IDs can be passed to [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html#amici.importers.pysb.pysb2amici) via the `fixed_parameters` argument to not generate the respective equations. This will reduce CPU time and RAM requirements during import and simulation.\n",
     "The PEtab import will automatically pass all parameters with `petab.ESTIMATE==False` as `fixed_parameters` arguments.\n",
     "\n",
     "See also the following section for the case that no sensitivities are required at all.\n",
     "\n",
     "\n",
     "#### Not generating sensitivity code\n",
     "\n",
-    "If only forward simulations of a model are required, a modest import speedup can be obtained from not generating sensitivity code. This can be enabled via the `generate_sensitivity_code` argument of [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.SbmlImporter.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html?highlight=pysb2amici#amici.importers.pysb.pysb2amici).\n",
+    "If only forward simulations of a model are required, a modest import speedup can be obtained from not generating sensitivity code. This can be enabled via the `generate_sensitivity_code` argument of [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html#amici.importers.pysb.pysb2amici).\n",
     "\n",
     "Example:\n",
     "```bash\n",
@@ -219,7 +219,7 @@
     "\n",
     "By default, AMICI will try to perform some basic simplification of model expressions. For complex model expressions, or for large models, this can become costly. It very much depends on the model expressions, whether the benefits outweigh the cost.\n",
     "\n",
-    "Simplification of model expressions can be disabled by passing `simplify=None` to [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.SbmlImporter.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html?highlight=pysb2amici#amici.importers.pysb.pysb2amici).\n",
+    "Simplification of model expressions can be disabled by passing `simplify=None` to [amici.importers.sbml.SbmlImporter.sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.SbmlImporter.sbml2amici) or [amici.importers.pysb.pysb2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.pysb.html#amici.importers.pysb.pysb2amici).\n",
     "\n",
     "Depending on the given model, different simplification schemes may be cheaper or more beneficial than the default. SymPy's simplification functions are [well documented](https://docs.sympy.org/latest/modules/simplify/simplify.html)."
    ]
@@ -477,24 +477,23 @@
     "\n",
     "### Sensitivities w.r.t. a subset of parameters\n",
     "\n",
-    "If only sensitivities with respect to a subset of model parameters are of interest to you (see also *Fixing parameters* above), you can speed up the simulation by selecting the relevant parameter indices via [amici.Model.setParameterList](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.setParameterList).\n"
+    "If only sensitivities with respect to a subset of model parameters are of interest to you (see also *Fixing parameters* above), you can speed up the simulation by selecting the relevant parameter indices via [amici.sim.sundials.Model.set_parameter_list](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.set_parameter_list).\n"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "af4bd3d5",
    "metadata": {},
    "source": [
-    "\n",
     "### Parallel simulation of multiple conditions\n",
     "\n",
-    "Whenever there are multiple independent simulations to perform, you can use [amici.runAmiciSimulations(..., num_threads=...)](https://amici.readthedocs.io/en/latest/generated/amici.amici.html#amici.amici.runAmiciSimulations) instead of [amici.runAmiciSimulations(...)](https://amici.readthedocs.io/en/latest/generated/amici.amici.html#amici.amici.runAmiciSimulation) to run them in parallel. Note that all simulation results have to be kept in memory, which may become problematic for very large numbers of simulations.\n",
+    "Whenever there are multiple independent simulations to perform, you can use [amici.sim.sundials.run_simulations(..., num_threads=...)](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.run_simulations) instead of `amici.sim.sundials.run_simulations(...)` to run them in parallel. Note that all simulation results have to be kept in memory, which may become problematic for very large numbers of simulations.\n",
     "Parallelization is based on OpenMP and does not come with the issues associated with Python's multiprocessing or multithreading (spawning extra processes or limitations related to the global interpreter lock).\n",
     "\n",
     "### Reporting mode\n",
     "\n",
     "During model simulation, many quantities are calculated, but not all might be of interest for you. For example, for parameter estimation you might only be interested in the likelihood and gradient. In this case, you can save time and memory using\n",
-    "[amici.Solver.setReturnDataReportingMode(amici.RDataReporting.likelihood)](https://amici.readthedocs.io/en/latest/generated/amici.amici.Solver.html#amici.amici.Solver.setReturnDataReportingMode)."
+    "[amici.sim.sundials.Solver.set_return_data_reporting_mode(amici.sim.sundials.RDataReporting.likelihood)](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Solver.set_return_data_reporting_mode)."
    ]
   }
  ],

doc/examples/example_steady_states/ExampleEquilibrationLogic.ipynb

@@ -51,7 +51,7 @@
     "\n",
     "$$\n",
     "\\begin{array}{llll}\n",
-    "    \\dot{s} = (\\text{synthesis_substrate} + k_{\\text{create}}) - k_{\\text{bind}}\\cdot s \\cdot e + k_{\\text{unbind}}\\cdot c,\\\\\n",
+    "    \\dot{s} = (\\text{synthesis\\_substrate} + k_{\\text{create}}) - k_{\\text{bind}}\\cdot s \\cdot e + k_{\\text{unbind}}\\cdot c,\\\\\n",
     "    \\dot{e} = - k_{\\text{bind}}\\cdot s \\cdot e + k_{\\text{unbind}}\\cdot c + k_{\\text{convert}}\\cdot c,\\\\\n",
     "    \\dot{c} = k_{\\text{bind}}\\cdot s \\cdot e - k_{\\text{unbind}}\\cdot c - k_{\\text{convert}}\\cdot c,\\\\\n",
     "    \\dot{p} = k_{\\text{convert}}\\cdot c - k_{\\text{decay}}\\cdot p,\n",
@@ -73,7 +73,7 @@
     "\n",
     "It's easy to see that the first two columns (or the second and the third row) are linearly dependent and the determinant is equal to zero.\n",
     "\n",
-    "If one is able to identify a conserved quantity, the model dimension can be reduced by excluding one of the states. For example, for the model above one can remove the second ODE and redefine $e$ as $\\text{enzyme_total} - c$, where $\\text{enzyme_total}$ is a constant specifying the total concentration of the enzyme. In general, conserved quantities or conserved moieties are functions of state variables of the dynamical system that remain constant over time. They can be automatically removed in the SBML import of AMICI, if an environment variable ``AMICI_EXPERIMENTAL_SBML_NONCONST_CLS`` is set, using a heuristic-based conserved moieties identification approach presented in [De Martino et al. (2014)](https://doi.org/10.1371/journal.pone.0100750).\n",
+    "If one is able to identify a conserved quantity, the model dimension can be reduced by excluding one of the states. For example, for the model above one can remove the second ODE and redefine $e$ as $\\text{enzyme\\_total} - c$, where $\\text{enzyme\\_total}$ is a constant specifying the total concentration of the enzyme. In general, conserved quantities or conserved moieties are functions of state variables of the dynamical system that remain constant over time. They can be automatically removed in the SBML import of AMICI, if an environment variable ``AMICI_EXPERIMENTAL_SBML_NONCONST_CLS`` is set, using a heuristic-based conserved moieties identification approach presented in [De Martino et al. (2014)](https://doi.org/10.1371/journal.pone.0100750).\n",
     "\n",
     "In the following, we will consider two versions of this model, with and without eliminating the conserved quantity, to demonstrate the failure of Newton's method for steady-state computation and of two different approaches for sensitivities computation that are not applicable if the Jacobian is singular."
    ]
@@ -1070,7 +1070,7 @@
     "$$\n",
     "`rtol` and `atol` denote relative and absolute tolerances, respectively.\n",
     "\n",
-    "The respective tolerances for equilibrating a system with AMICI can be controlled by the user via the getter/setter functions `[get|set][Absolute|Relative]ToleranceSteadyState[Sensi]`:"
+    "The respective tolerances for equilibrating a system with AMICI can be controlled by the user via the getter/setter functions `[get|set]_[absolute|relative]_tolerance_steady_state[_sensi]`:"
    ]
   },
   {

include/amici/model_dimensions.h

@@ -131,16 +131,16 @@ struct ModelDimensions {
      */
     std::vector<int> ndJydy;
 
-    /** Number of nonzero elements in the \f$ x \f$ derivative of \f$ x_rdata
+    /** Number of nonzero elements in the \f$ x \f$ derivative of \f$ x\_rdata
      * \f$ */
     int ndxrdatadxsolver{0};
 
-    /** Number of nonzero elements in the \f$ tcl\f$ derivative of \f$ x_rdata
+    /** Number of nonzero elements in the \f$ tcl\f$ derivative of \f$ x\_rdata
      * \f$ */
     int ndxrdatadtcl{0};
 
-    /** Number of nonzero elements in the \f$ x_rdata\f$ derivative of
-     *  \f$ total_cl \f$ */
+    /** Number of nonzero elements in the \f$ x\_rdata\f$ derivative of
+     *  \f$ total\_cl \f$ */
     int ndtotal_cldx_rdata{0};
 
     /** Number of nonzero entries in Jacobian */

include/amici/solver.h

@@ -432,7 +432,8 @@ class Solver {
      *
      * Steady state simulation tolerances are the product of the simulation
      * tolerances and this factor, unless manually set with
-     * `set(Absolute/Relative)ToleranceSteadyState()`.
+     * `set_relative_tolerance_steady_state()` /
+     * `set_absolute_tolerance_steady_state()`.
      *
      * @return steady state simulation tolerance factor
      */
@@ -443,7 +444,8 @@ class Solver {
      *
      * Steady state simulation tolerances are the product of the simulation
      * tolerances and this factor, unless manually set with
-     * `set(Absolute/Relative)ToleranceSteadyState()`.
+     * `set_relative_tolerance_steady_state()` /
+     * `set_absolute_tolerance_steady_state()`.
      *
      * @param factor tolerance factor (non-negative number)
      */
@@ -640,17 +642,17 @@ class Solver {
      * @brief Gets KLU / SuperLUMT state ordering mode
      *
      * @return State-ordering as integer according to
-     * SUNLinSolKLU::StateOrdering or SUNLinSolSuperLUMT::StateOrdering (which
-     * differ).
+     * `SUNLinSolKLU::StateOrdering` or `SUNLinSolSuperLUMT::StateOrdering`
+     * (which differ).
      */
     int get_state_ordering() const;
 
     /**
      * @brief Sets KLU / SuperLUMT state ordering mode
      *
-     * This only applies when linsol is set to LinearSolver::KLU or
-     * LinearSolver::SuperLUMT. Mind the difference between
-     * SUNLinSolKLU::StateOrdering and SUNLinSolSuperLUMT::StateOrdering.
+     * This only applies when the linear solver is set to `LinearSolver::KLU`
+     * or `LinearSolver::SuperLUMT`. Mind the difference between
+     * `SUNLinSolKLU::StateOrdering` and `SUNLinSolSuperLUMT::StateOrdering`.
      *
      * @param ordering state ordering
      */
@@ -900,21 +902,21 @@ class Solver {
     /**
      * @brief number of state variables with which the solver was initialized
      *
-     * @return x.getLength()
+     * @return Number of solver state variables.
      */
     int nx() const;
 
     /**
      * @brief number of parameters with which the solver was initialized
      *
-     * @return sx.getLength()
+     * @return Number of parameters w.r.t. which sensitivities are computed.
      */
     int nplist() const;
 
     /**
      * @brief number of quadratures with which the solver was initialized
      *
-     * @return xQB.getLength()
+     * @return Number of quadratures with which the solver was initialized.
      */
     int nquad() const;
 

python/sdist/amici/sim/sundials/petab/_v2.py

@@ -57,7 +57,8 @@ def __init__(
         :param model: The AMICI model to use.
         :param petab_problem: The PEtab problem to use.
             This is expected to be the output of
-            :class:`petab.v2.ExperimentsToSbmlConverter` or an equivalent problem.
+            :class:`petab.v2.converters.ExperimentsToSbmlConverter` or an
+            equivalent problem.
             This object must not be modified after the creation of this
             :class:`ExperimentManager` instance.
         """

swig/solver.i

@@ -50,10 +50,10 @@ using namespace amici;
 %ignore get_num_rhs_evals_b;
 %ignore get_num_steps;
 %ignore get_num_steps_b;
-%ignore gett;
-%ignore startTimer;
-%ignore switchForwardSensisOff;
-%ignore timeExceeded;
+%ignore get_t;
+%ignore start_timer;
+%ignore switch_forward_sensis_off;
+%ignore time_exceeded;
 %ignore getSunContext;
 %ignore get_adjoint_state;
 %ignore get_adjoint_derivative_state;