diff --git a/doc/conf.py b/doc/conf.py index acd761714d..833cf9296f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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 = { diff --git a/doc/examples/getting_started/GettingStarted.ipynb b/doc/examples/getting_started/GettingStarted.ipynb index 4b3d9447cc..b260ff6caf 100644 --- a/doc/examples/getting_started/GettingStarted.ipynb +++ b/doc/examples/getting_started/GettingStarted.ipynb @@ -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": { diff --git a/doc/examples/getting_started_extended/GettingStartedExtended.ipynb b/doc/examples/getting_started_extended/GettingStartedExtended.ipynb index c1672d3dc8..021bb58292 100644 --- a/doc/examples/getting_started_extended/GettingStartedExtended.ipynb +++ b/doc/examples/getting_started_extended/GettingStartedExtended.ipynb @@ -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", diff --git a/doc/implementation_discontinuities.rst b/doc/implementation_discontinuities.rst index cbe91cdce5..0bb395f3b5 100644 --- a/doc/implementation_discontinuities.rst +++ b/doc/implementation_discontinuities.rst @@ -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 diff --git a/doc/python_interface.rst b/doc/python_interface.rst index 34d1658581..13d60a4f09 100644 --- a/doc/python_interface.rst +++ b/doc/python_interface.rst @@ -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`. - diff --git a/doc/python_modules.rst b/doc/python_modules.rst index f17b9fa31d..7eeb000996 100644 --- a/doc/python_modules.rst +++ b/doc/python_modules.rst @@ -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 diff --git a/include/amici/model.h b/include/amici/model.h index b7e8e86a80..de0abe4eb9 100644 --- a/include/amici/model.h +++ b/include/amici/model.h @@ -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 */ diff --git a/include/amici/solver.h b/include/amici/solver.h index c7671a5d4b..1dc0cb5793 100644 --- a/include/amici/solver.h +++ b/include/amici/solver.h @@ -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 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 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 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 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 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 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,7 +1203,7 @@ 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 @@ -1203,16 +1211,16 @@ class Solver { 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 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 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 nnlscfB_; /** employed order forward problem (dimension: nt) */ diff --git a/python/sdist/amici/_symbolic/de_model.py b/python/sdist/amici/_symbolic/de_model.py index 6ac2650628..3ddf30fba1 100644 --- a/python/sdist/amici/_symbolic/de_model.py +++ b/python/sdist/amici/_symbolic/de_model.py @@ -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] = [] diff --git a/python/sdist/amici/exporters/sundials/de_export.py b/python/sdist/amici/exporters/sundials/de_export.py index b3aea445f4..32e4e2df5c 100644 --- a/python/sdist/amici/exporters/sundials/de_export.py +++ b/python/sdist/amici/exporters/sundials/de_export.py @@ -6,7 +6,7 @@ The user generally won't have to directly call any function from this module as this will be done by :py:func:`amici.importers.pysb.pysb2amici`, -:py:func:`amici.importers.sbml.SbmlImporter.sbml2amici` and +:py:meth:`amici.importers.sbml.SbmlImporter.sbml2amici` and :py:func:`amici.petab_import.import_model`. """ @@ -120,8 +120,8 @@ class DEExporter: path to the generated swig files :ivar allow_reinit_fixpar_initcond: - indicates whether reinitialization of - initial states depending on fixedParameters is allowed for this model + Indicates whether reinitialization of initial states depending on + fixed parameters is allowed for this model. :ivar _build_hints: If the given model uses special functions, this set contains hints for diff --git a/python/sdist/amici/importers/antimony/__init__.py b/python/sdist/amici/importers/antimony/__init__.py index 20505a0625..bd14e058b1 100644 --- a/python/sdist/amici/importers/antimony/__init__.py +++ b/python/sdist/amici/importers/antimony/__init__.py @@ -6,7 +6,13 @@ from pathlib import Path -__all__ = ["antimony2sbml", "antimony2amici"] +from ..utils import MeasurementChannel + +__all__ = [ + "antimony2sbml", + "antimony2amici", + "MeasurementChannel", +] def antimony2sbml(ant_model: str | Path) -> str: diff --git a/python/sdist/amici/importers/bngl/__init__.py b/python/sdist/amici/importers/bngl/__init__.py index 7da4296736..55a41ffaca 100644 --- a/python/sdist/amici/importers/bngl/__init__.py +++ b/python/sdist/amici/importers/bngl/__init__.py @@ -8,8 +8,12 @@ from pysb.importers.bngl import model_from_bngl from ..pysb import pysb2amici +from ..utils import MeasurementChannel -__all__ = ["bngl2amici"] +__all__ = [ + "bngl2amici", + "MeasurementChannel", +] def bngl2amici(bngl_model: str, *args, **kwargs) -> None: diff --git a/python/sdist/amici/importers/petab/_petab_importer.py b/python/sdist/amici/importers/petab/_petab_importer.py index 17c022766f..760dc93154 100644 --- a/python/sdist/amici/importers/petab/_petab_importer.py +++ b/python/sdist/amici/importers/petab/_petab_importer.py @@ -582,8 +582,11 @@ def import_module(self, force_import: bool = False) -> amici.ModelModule: self.outdir, ) - def create_model(self) -> amici.Model: - """Create a :class:`amici.Model` instance from the imported model.""" + def create_model(self) -> amici.sim.sundials.Model: + """ + Create a :class:`amici.sim.sundials.Model` instance from the imported + model. + """ return self.import_module().get_model() def create_simulator( diff --git a/python/sdist/amici/importers/petab/v1/sbml_import.py b/python/sdist/amici/importers/petab/v1/sbml_import.py index 2c7c308024..8143e4c078 100644 --- a/python/sdist/amici/importers/petab/v1/sbml_import.py +++ b/python/sdist/amici/importers/petab/v1/sbml_import.py @@ -256,8 +256,10 @@ def import_model_sbml( Print/log extra information. :param allow_reinit_fixpar_initcond: - See :class:`amici.de_export.ODEExporter`. Must be enabled if initial - states are to be reset after preequilibration. + Indicates whether reinitialization of initial states depending on + fixed parameters is allowed for this model. + Must be enabled if initial states are to be reset after + pre-equilibration. :param validate: Whether to validate the PEtab problem diff --git a/python/sdist/amici/importers/pysb/__init__.py b/python/sdist/amici/importers/pysb/__init__.py index ad09e75e73..d4871b0519 100644 --- a/python/sdist/amici/importers/pysb/__init__.py +++ b/python/sdist/amici/importers/pysb/__init__.py @@ -54,6 +54,7 @@ "pysb_model_from_path", "pysb2amici", "pysb2jax", + "MeasurementChannel", ] CL_Prototype = dict[str, dict[str, Any]] @@ -89,11 +90,12 @@ def pysb2jax( simulations. :param model: - pysb model, :attr:`pysb.core.Model.name` will determine the name of the - generated module + PySB model, :class:`model.name ` will determine the + name of the generated module. :param output_dir: - see :meth:`amici.de_export.ODEExporter.set_paths` + The directory where the generated model code is stored. + Will be created if it does not exist. :param observation_model: The different measurement channels that make up the observation @@ -113,13 +115,15 @@ def pysb2jax( if set to ``True``, conservation laws are automatically computed and applied such that the state-jacobian of the ODE right-hand-side has full rank. This option should be set to ``True`` when using the Newton - algorithm to compute steadystates + algorithm to compute steady states. :param simplify: - see :attr:`amici.DEModel._simplify` + 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. :param cache_simplify: - see :func:`amici.DEModel.__init__` + Whether to cache calls to the simplify method. Note that there are possible issues with PySB models: https://github.com/AMICI-dev/AMICI/pull/1672 @@ -190,11 +194,12 @@ def pysb2amici( simulations. :param model: - pysb model, :attr:`pysb.core.Model.name` will determine the name of the - generated module + PySB model, :class:`model.name ` will determine the + name of the generated module. :param output_dir: - see :meth:`amici.de_export.ODEExporter.set_paths` + The directory where the generated model code is stored. + Will be created if it does not exist. :param observation_model: The different measurement channels that make up the observation @@ -234,12 +239,14 @@ def pysb2amici( just generate the source code. :param simplify: - see :attr:`amici.DEModel._simplify` + 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. :param cache_simplify: - see :func:`amici.DEModel.__init__` - Note that there are possible issues with PySB models: - https://github.com/AMICI-dev/AMICI/pull/1672 + Whether to cache calls to the simplify method. + Note that there are possible issues with PySB models: + https://github.com/AMICI-dev/AMICI/pull/1672 :param generate_sensitivity_code: if set to ``False``, code for sensitivity computation will not be @@ -341,12 +348,14 @@ def ode_model_from_pysb_importer( see :func:`amici.importers.pysb.pysb2amici` :param simplify: - see :attr:`amici.DEModel._simplify` + 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. :param cache_simplify: - see :func:`amici.DEModel.__init__` - Note that there are possible issues with PySB models: - https://github.com/AMICI-dev/AMICI/pull/1672 + Whether to cache calls to the simplify method. + Note that there are possible issues with PySB models: + https://github.com/AMICI-dev/AMICI/pull/1672 :param verbose: verbosity level for logging, True/False default to :attr:`logging.DEBUG`/:attr:`logging.ERROR` @@ -1599,7 +1608,8 @@ def _get_changed_stoichiometries( def pysb_model_from_path(pysb_model_file: str | Path) -> pysb.Model: - """Load a pysb model module and return the :class:`pysb.Model` instance + """ + Load a PySB model module and return the :class:`pysb.core.Model` instance. :param pysb_model_file: Full or relative path to the PySB model module :return: The pysb Model instance diff --git a/python/sdist/amici/importers/sbml/__init__.py b/python/sdist/amici/importers/sbml/__init__.py index 55cb4b3079..a39e997142 100644 --- a/python/sdist/amici/importers/sbml/__init__.py +++ b/python/sdist/amici/importers/sbml/__init__.py @@ -325,7 +325,10 @@ def sbml2amici( extension, e.g. ``/usr/bin/clang``. :param allow_reinit_fixpar_initcond: - See :class:`amici.de_export.DEExporter`. + Indicates whether reinitialization of initial states depending on + fixed parameters is allowed for this model. + Must be enabled if initial states are to be reset after + pre-equilibration. :param compile: If ``True``, compile the generated Python package, @@ -349,10 +352,14 @@ def sbml2amici( case of stoichiometric coefficients with many significant digits. :param simplify: - See :attr:`amici.DEModel._simplify`. + 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. :param cache_simplify: - See :meth:`amici.DEModel.__init__`. + Whether to cache calls to the simplify method. + Note that there are possible issues with PySB models: + https://github.com/AMICI-dev/AMICI/pull/1672 :param generate_sensitivity_code: If ``False``, the code required for sensitivity computation will @@ -486,10 +493,14 @@ def sbml2jax( case of stoichiometric coefficients with many significant digits. :param simplify: - see :attr:`amici.DEModel._simplify` + 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. :param cache_simplify: - see :meth:`amici.DEModel.__init__` + Whether to cache calls to the simplify method. + Note that there are possible issues with PySB models: + https://github.com/AMICI-dev/AMICI/pull/1672 :param hybridization: dict representation of the hybridization information in the PEtab YAML file, see @@ -2763,7 +2774,7 @@ def _sympify( :param var_or_math: A math expression to sympify: - * a string (see `sympy.sympify`) + * a string (see :func:`sympy.core.sympify.sympify`) * a number * a libSBML ASTNode * a libSBML object that has a ``getMath()`` function diff --git a/python/sdist/amici/importers/utils.py b/python/sdist/amici/importers/utils.py index b813c0539e..80dbb2ecb2 100644 --- a/python/sdist/amici/importers/utils.py +++ b/python/sdist/amici/importers/utils.py @@ -16,6 +16,11 @@ from sympy.logic.boolalg import BooleanAtom from toposort import toposort +__all__ = [ + "MeasurementChannel", +] + +# Symbols reserved by AMICI. Model entities with these IDs will be renamed. RESERVED_SYMBOLS = [ "x", "k", @@ -28,11 +33,6 @@ "NULL", ] -try: - import pysb -except ImportError: - pysb = None - class SBMLException(Exception): """Exception for SBML related errors. @@ -141,11 +141,93 @@ def __init__( """ Initialize a measurement channel. + + + The noise distributions listed in the following are supported. + :math:`m` denotes the measurement, :math:`y` the simulation, + and :math:`\\sigma` a distribution scale parameter + (currently, AMICI only supports a single distribution parameter). + + - `'normal'`, `'lin-normal'`: A normal distribution: + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma}\\ + exp\\left(-\\frac{(m-y)^2}{2\\sigma^2}\\right) + + - `'log-normal'`: A log-normal distribution (i.e. log(m) is + normally distributed): + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma m}\\ + exp\\left(-\\frac{(\\log m - \\log y)^2}{2\\sigma^2}\\right) + + - `'log10-normal'`: A log10-normal distribution (i.e. log10(m) is + normally distributed): + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{\\sqrt{2\\pi}\\sigma m \\log(10)}\\ + exp\\left(-\\frac{(\\log_{10} m - \\log_{10} y)^2}{2\\sigma^2}\\right) + + - `'laplace'`, `'lin-laplace'`: A laplace distribution: + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma} + \\exp\\left(-\\frac{|m-y|}{\\sigma}\\right) + + - `'log-laplace'`: A log-Laplace distribution (i.e. log(m) is Laplace + distributed): + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma m} + \\exp\\left(-\\frac{|\\log m - \\log y|}{\\sigma}\\right) + + - `'log10-laplace'`: A log10-Laplace distribution (i.e. log10(m) is + Laplace distributed): + + .. math:: + \\pi(m|y,\\sigma) = \\frac{1}{2\\sigma m \\log(10)} + \\exp\\left(-\\frac{|\\log_{10} m - \\log_{10} y|}{\\sigma}\\right) + + - `'binomial'`, `'lin-binomial'`: A (continuation of a discrete) binomial + distribution, parameterized via the success probability + :math:`p=\\sigma`: + + .. math:: + \\pi(m|y,\\sigma) = \\operatorname{Heaviside}(y-m) \\cdot + \\frac{\\Gamma(y+1)}{\\Gamma(m+1) \\Gamma(y-m+1)} + \\sigma^m (1-\\sigma)^{(y-m)} + + - `'negative-binomial'`, `'lin-negative-binomial'`: A (continuation of a + discrete) negative binomial distribution, with `mean = y`, + parameterized via success probability `p`: + + .. math:: + + \\pi(m|y,\\sigma) = \\frac{\\Gamma(m+r)}{\\Gamma(m+1) \\Gamma(r)} + (1-\\sigma)^m \\sigma^r + + where + + .. math:: + r = \\frac{1-\\sigma}{\\sigma} y + + The distributions above are for a single data point. + For a collection :math:`D=\\{m_i\\}_i` of data points and corresponding + simulations :math:`Y=\\{y_i\\}_i` and noise parameters + :math:`\\Sigma=\\{\\sigma_i\\}_i`, AMICI assumes independence, + i.e. the full distributions is + + .. math:: + \\pi(D|Y,\\Sigma) = \\prod_i\\pi(m_i|y_i,\\sigma_i) + + AMICI uses the logarithm :math:`\\log(\\pi(m|y,\\sigma)`. + .. note:: When providing expressions for (event) observables and their sigmas as strings (see below), those will be passed to - :func:`sympy.sympify`. The supported grammar is not well-defined. + :func:`sympy.core.sympify.sympify`. + The supported grammar is not well-defined. Note there can be issues with, for example, ``==`` or n-ary (n>2) comparison operators. Also note that operator precedence and function names may differ @@ -167,10 +249,14 @@ def __init__( and parameters. :param noise_distribution: Noise distribution associated with the observable. - This is usually a string identifier (e.g., 'normal', 'log-normal'; - see - :func:`amici.importers.utils.noise_distribution_to_cost_function`). - If ``None``, a normal distribution is assumed. + This is usually a string identifier: + + {`'normal'`, `'lin-normal'`, `'log-normal'`, `'log10-normal'`, + `'laplace'`, `'lin-laplace'`, `'log-laplace'`, `'log10-laplace'`, + `'binomial'`, `'lin-binomial'`, `'negative-binomial'`, + `'lin-negative-binomial'`} + + For the meaning of the values see above. Alternatively, a callable can be passed to account for a custom noise model. The callable must take a single argument diff --git a/python/sdist/amici/sim/sundials/plotting.py b/python/sdist/amici/sim/sundials/plotting.py index 5e3eea37d1..990f866da2 100644 --- a/python/sdist/amici/sim/sundials/plotting.py +++ b/python/sdist/amici/sim/sundials/plotting.py @@ -36,7 +36,7 @@ def plot_state_trajectories( :param rdata: AMICI simulation results as returned by - :func:`run_amici_simulation`. + :func:`amici.sim.sundials.run_simulation`. :param state_indices: Indices of state variables for which trajectories are to be plotted. :param ax: @@ -99,7 +99,7 @@ def plot_observable_trajectories( :param rdata: AMICI simulation results as returned by - :func:`run_simulation`. + :func:`amici.sim.sundials.run_simulation`. :param observable_indices: Indices of observables for which trajectories are to be plotted. :param ax: