diff --git a/doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb b/doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb index a80554f293..033f75937d 100644 --- a/doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb +++ b/doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb @@ -5,14 +5,12 @@ "metadata": {}, "source": [ "# AMICI Python example \"Experimental Conditions\"\n", - "In this example we will explore some more options for the initialization of experimental conditions, including how to reset initial conditions based on changing values for `fixedParameters` as well as an additional presimulation phase on top of preequilibration. This notebook is expected to run from the `python/example_presimulation` directory." + "In this example we will explore some more options for the initialization of experimental conditions, including how to reset initial conditions based on changing values for fixed parameters as well as an additional presimulation phase on top of preequilibration. This notebook is expected to run from the `python/example_presimulation` directory." ] }, { "cell_type": "code", - "execution_count": 1, "metadata": {}, - "outputs": [], "source": [ "# SBML model we want to import\n", "sbml_file = \"model_presimulation.xml\"\n", @@ -28,56 +26,21 @@ "import numpy as np\n", "from amici.sim.sundials import ExpData, run_simulation\n", "from amici.sim.sundials.plotting import plot_observable_trajectories" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Model Loading\n", - "Here we load a simple model of protein phosphorylation that can be inhibited by a drug. This model was created using PySB (see `createModel.py`)" + "Here we load a simple model of protein phosphorylation that can be inhibited by a drug. This model was created using PySB (see `createModelPresimulation.py`)" ] }, { "cell_type": "code", - "execution_count": 2, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Species:\n", - "[('__s0', \"PROT(kin=None, drug=None, phospho='u')\"),\n", - " ('__s1', 'DRUG(bound=None)'),\n", - " ('__s2', 'KIN(bound=None)'),\n", - " ('__s3', \"DRUG(bound=1) ._br_PROT(kin=None, drug=1, phospho='u')\"),\n", - " ('__s4', \"KIN(bound=1) ._br_PROT(kin=1, drug=None, phospho='u')\"),\n", - " ('__s5', \"PROT(kin=None, drug=None, phospho='p')\")]\n", - "\n", - "Reactions:\n", - "PROT_DRUG_bind: __s0 + __s1 <-> __s3\t\t[-(koff_prot_drug * __s3) + kon_prot_drug * __s0 * __s1]\n", - "PROT_KIN_bind: __s0 + __s2 -> __s4\t\t[kon_prot_kin * __s0 * __s2]\n", - "PROT_KIN_phospho: __s4 -> __s2 + __s5\t\t[kphospho_prot_kin * __s4]\n", - "PROT_dephospho: __s5 -> __s0\t\t[kdephospho_prot * __s5]\n", - "Parameters:\n", - "[('initProt', 'initProt'),\n", - " ('initDrug', 'initDrug'),\n", - " ('initKin', 'initKin'),\n", - " ('pPROT_obs', 'pPROT_obs'),\n", - " ('PROT_0', 'PROT_0'),\n", - " ('DRUG_0', 'DRUG_0'),\n", - " ('KIN_0', 'KIN_0'),\n", - " ('kon_prot_drug', 'kon_prot_drug'),\n", - " ('koff_prot_drug', 'koff_prot_drug'),\n", - " ('kon_prot_kin', 'kon_prot_kin'),\n", - " ('kphospho_prot_kin', 'kphospho_prot_kin'),\n", - " ('kdephospho_prot', 'kdephospho_prot'),\n", - " ('__obs0', 'pPROT'),\n", - " ('__obs1', 'tPROT')]\n" - ] - } - ], "source": [ "sbml_reader = libsbml.SBMLReader()\n", "sbml_doc = sbml_reader.readSBML(sbml_file)\n", @@ -120,54 +83,30 @@ "\n", "print(\"Parameters:\")\n", "pprint([(p.getId(), p.getName()) for p in sbml_model.getListOfParameters()])" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "code", - "execution_count": 3, "metadata": { "scrolled": false }, - "outputs": [], "source": [ "# Create an SbmlImporter instance for our SBML model\n", "sbml_importer = amici.SbmlImporter(sbml_file)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": [ - "For this example we want to specify the initial drug and kinase concentrations as experimental conditions. Accordingly, we specify them as `fixedParameters`. The meaning of `fixedParameters` is defined in the [Glossary](https://amici.readthedocs.io/en/latest/glossary.html#term-fixed-parameters), which we display here for convenience." - ] + "source": "For this example we want to specify the initial drug and kinase concentrations as experimental conditions. Accordingly, we specify them as `fixed_parameters`. The meaning of `fixed_parameters` is defined in the [Glossary](https://amici.readthedocs.io/en/latest/glossary.html#term-fixed-parameters), which we display here for convenience." }, { "cell_type": "code", - "execution_count": 4, "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "\n", - " \n", - " " - ], - "text/plain": [ - "" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], "source": [ "from IPython.display import IFrame\n", "\n", @@ -176,38 +115,29 @@ " width=600,\n", " height=175,\n", ")" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "fixed_parameters = [\"DRUG_0\", \"KIN_0\"]" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": "The SBML model specifies a single observable named `pPROT` which describes the fraction of phosphorylated Protein. We load this observable using [amici.assignment_rules_to_observables](https://amici.readthedocs.io/en/latest/generated/amici.sbml_import.html#amici.sbml_import.assignment_rules_to_observables)." + "source": "The SBML model specifies a single observable named `pPROT` which describes the fraction of phosphorylated Protein. We load this observable using [amici.assignment_rules_to_observables](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.assignment_rules_to_observables)." }, { "cell_type": "code", - "execution_count": 6, "metadata": { "scrolled": true }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Observables:\n", - "{'__obs0': {'formula': '__s5', 'name': 'pPROT'}}\n" - ] - } - ], "source": [ "# Retrieve model output names and formulae from AssignmentRules and remove the respective rules\n", "observables = amici.assignment_rules_to_observables(\n", @@ -216,18 +146,18 @@ ")\n", "print(\"Observables:\")\n", "pprint(observables)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": "Now the model is ready for compilation using [sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.sbml_import.SbmlImporter.html#amici.sbml_import.SbmlImporter.sbml2amici). Note that we here pass `fixed_parameters`, which ensures faster compilation by disabling sensitivity calculations for these parameters:" + "source": "Now the model is ready for compilation using [sbml2amici](https://amici.readthedocs.io/en/latest/generated/amici.importers.sbml.html#amici.importers.sbml.SbmlImporter.sbml2amici). Note that we here pass `fixed_parameters`, which ensures faster compilation by disabling sensitivity calculations for these parameters:" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "sbml_importer.sbml2amici(\n", " model_name,\n", @@ -238,98 +168,94 @@ ")\n", "# load the generated module\n", "model_module = amici.import_model_module(model_name, model_output_dir)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": [ - "To simulate the model we need to create an instance via the `getModel()` method in the generated model module." - ] + "source": "To simulate the model we need to create an instance via the `get_model()` method in the generated model module." }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "# Create Model instance\n", "model = model_module.get_model()\n", "\n", "# Create solver instance\n", "solver = model.create_solver()" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": "The only thing we need to simulate the model is a timepoint vector, which can be specified using the [setTimepoints](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.setTimepoints) method. If we do not specify any additional options, the default values for `fixedParameters` and `parameters` that were specified in the SBML file will be used." + "source": "The only thing we need to simulate the model is a timepoint vector, which can be specified using the [Model.set_timepoints](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model.set_timepoints) method. If we do not specify any additional options, the default values for `fixed_parameters` and `free_parameters` that were specified in the SBML file will be used." }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "# Run simulation using default model parameters and solver options\n", "model.set_timepoints(np.linspace(0, 60, 60))\n", "rdata = run_simulation(model, solver)\n", "plot_observable_trajectories(rdata)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": [ - "Simulation options can be specified either in the [Model](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html) or in an [ExpData](https://amici.readthedocs.io/en/latest/generated/amici.amici.ExpData.html) instance. The `ExpData` instance can also carry experimental data. To initialize an `ExpData` instance from simulation results, amici offers some [convenient constructors](https://amici.readthedocs.io/en/latest/generated/amici.amici.ExpData.html#amici.amici.ExpData). In the following we will initialize an `ExpData` object from simulation results, but add noise with standard deviation `0.1` and specify the standard deviation accordingly. Moreover, we will specify custom values for `DRUG_0=0` and `KIN_0=2`. If `fixedParameter` is specified in an `ExpData` instance, [runAmiciSimulation](https://amici.readthedocs.io/en/latest/generated/amici.html#amici.runAmiciSimulation) will use those parameters instead of the ones specified in the `Model` instance." - ] + "source": "Simulation options can be specified either in the [Model](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.Model) or in an [ExpData](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.ExpData) instance. The `ExpData` instance can also carry experimental data. To initialize an `ExpData` instance from simulation results, amici offers some [convenient constructors](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.ExpData). In the following we will initialize an `ExpData` object from simulation results, but add noise with standard deviation `0.1` and specify the standard deviation accordingly. Moreover, we will specify custom values for `DRUG_0=0` and `KIN_0=2`. If `fixed_parameters` is specified in an `ExpData` instance, [run_simulation](https://amici.readthedocs.io/en/latest/generated/amici.sim.sundials.html#amici.sim.sundials.run_simulation) will use those parameters instead of the ones specified in the `Model` instance." }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "edata = ExpData(rdata, 0.1, 0.0)\n", "edata.fixed_parameters = [0, 2]\n", "rdata = run_simulation(model, solver, edata)\n", "plot_observable_trajectories(rdata)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ "For many biological systems, it is reasonable to assume that they start in a\n", - " steady state. In this example we want to specify an experiment where a pretreatment with a drug is performed _before_ the kinase is added. We assume that the pretreatment is sufficiently long such that the system reaches steadystate before the kinase is added. To implement this in amici, we can specify `fixedParametersPreequilibration` in the `ExpData` object. This automatically adds a preequilibration phase where the model is run to steadystate, before regular simulation starts. Here we set `DRUG_0=3` and `KIN_0=0` for the preequilibration. This means that there is no kinase available in the preequilibration phase." + " steady state. In this example we want to specify an experiment where a pretreatment with a drug is performed _before_ the kinase is added. We assume that the pretreatment is sufficiently long such that the system reaches steady state before the kinase is added. To implement this in amici, we can specify `fixed_parameters_pre_equilibration` in the `ExpData` object. This automatically adds a preequilibration phase where the model is run to steady state, before regular simulation starts. Here we set `DRUG_0=3` and `KIN_0=0` for the preequilibration. This means that there is no kinase available in the preequilibration phase." ] }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "edata.fixed_parameters_pre_equilibration = [3, 0]\n", "rdata = run_simulation(model, solver, edata)\n", "plot_observable_trajectories(rdata)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": [ - "The resulting trajectory is definitely not what one may expect. The problem is that the `DRUG_0` and `KIN_0` set initial conditions for species in the model. By default, these initial conditions are only applied at the very beginning of the simulation, i.e., before the preequilibration. Accordingly, the `fixedParameters` that we specified do not have any effect. To fix this, we need to set the `reinitializeFixedParameterInitialStates` attribute to `True`, to specify that AMICI reinitializes all states that have `fixedParameter`-dependent initial states." - ] + "source": "The resulting trajectory is definitely not what one may expect. The problem is that the `DRUG_0` and `KIN_0` set initial conditions for species in the model. By default, these initial conditions are only applied at the very beginning of the simulation, i.e., before the preequilibration. Accordingly, the `fixed_parameters` that we specified do not have any effect. To fix this, we need to set the `reinitialize_fixed_parameter_initial_states` attribute to `True`, to specify that AMICI reinitializes all states that have `fixed_parameters`-dependent initial states." }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "edata.reinitialize_fixed_parameter_initial_states = True" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -340,24 +266,22 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "rdata = run_simulation(model, solver, edata)\n", "plot_observable_trajectories(rdata)" - ] + ], + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, - "source": "On top of preequilibration, we can also specify presimulation. This option can be used to specify pretreatments where the system is not assumed to reach steadystate. Presimulation can be activated by specifying `t_presim` and `edata.fixed_parameters_presimulation`. If both `fixed_parameters_presimulation` and `fixed_parameters_pre_equilibration` are specified, pre-equilibration will be performed first, followed by presimulation, followed by regular simulation. For this example we specify `DRUG_0=10` and `KIN_0=0` for the presimulation and `DRUG_0=10` and `KIN_0=2` for the regular simulation. We do not overwrite the `DRUG_0=3` and `KIN_0=0` that was previously specified for pre-equilibration." + "source": "On top of preequilibration, we can also specify presimulation. This option can be used to specify pretreatments where the system is not assumed to reach steady state. Presimulation can be activated by specifying `t_presim` and `edata.fixed_parameters_presimulation`. If both `fixed_parameters_presimulation` and `fixed_parameters_pre_equilibration` are specified, pre-equilibration will be performed first, followed by presimulation, followed by regular simulation. For this example we specify `DRUG_0=10` and `KIN_0=0` for the presimulation and `DRUG_0=10` and `KIN_0=2` for the regular simulation. We do not overwrite the `DRUG_0=3` and `KIN_0=0` that was previously specified for pre-equilibration." }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "edata.t_presim = 10\n", "edata.fixed_parameters_presimulation = [10.0, 0.0]\n", @@ -367,14 +291,16 @@ "print(edata.fixed_parameters)\n", "rdata = run_simulation(model, solver, edata)\n", "plot_observable_trajectories(rdata)" - ] + ], + "outputs": [], + "execution_count": null } ], "metadata": { "kernelspec": { - "display_name": "Python3", + "display_name": "Python 3 (ipykernel)", "language": "python", - "name": "python" + "name": "python3" }, "language_info": { "codemirror_mode": { diff --git a/python/sdist/amici/importers/petab/v1/_import_helpers.py b/python/sdist/amici/importers/petab/v1/_import_helpers.py index e32c91299b..0d5ba88aa1 100644 --- a/python/sdist/amici/importers/petab/v1/_import_helpers.py +++ b/python/sdist/amici/importers/petab/v1/_import_helpers.py @@ -248,7 +248,7 @@ def get_fixed_parameters( def check_model( - amici_model: amici.Model, + amici_model: amici.sim.sundials.Model, petab_problem: petab.Problem, ) -> None: """Check that the model is consistent with the PEtab problem.""" diff --git a/python/sdist/amici/sim/sundials/_swig_wrappers.py b/python/sdist/amici/sim/sundials/_swig_wrappers.py index 9473064c9b..addc4dde04 100644 --- a/python/sdist/amici/sim/sundials/_swig_wrappers.py +++ b/python/sdist/amici/sim/sundials/_swig_wrappers.py @@ -56,7 +56,7 @@ def run_simulation( :param solver: Solver instance, must be generated from - :py:meth:`amici.amici.Model.create_solver` + :py:meth:`amici.sim.sundials.Model.create_solver` :param edata: ExpData instance (optional) @@ -92,10 +92,13 @@ def run_simulations( num_threads: int = 1, ) -> list[ReturnDataView]: """ - Convenience wrapper for loops of amici.runAmiciSimulation + Run simulations for multiple experimental conditions. + + Convenience wrapper for loops of :func:`amici.sim.sundials.run_simulation`. :param model: Model instance - :param solver: Solver instance, must be generated from Model.getSolver() + :param solver: Solver instance, must be generated from + :py:meth:`amici.sim.sundials.Model.create_solver` :param edata_list: list of ExpData instances :param failfast: returns as soon as an integration failure is encountered :param num_threads: number of threads to use (only used if compiled