Harmonize Fixed parameter Names (#3027)

* refactor model components

* fix argument names

* Update de_model_components.py

* refactor de_model

* refactor cpp code

* fixups cpp

* fixup id confusion

* fixup

* doc

* get_parameter_names

* free parameter ids

* more renaming

* update templates, regenerate test models

* Rename py

* some more

* ..

* ..

* Update test_pregenerated_models.py

* fix pysb tests

* clang-format

* changelog

* numpy

* Apply suggestions from code review

---------

Co-authored-by: Daniel Weindl <[email protected]>
Co-authored-by: Daniel Weindl <[email protected]>

Author: FFroehlich

CHANGELOG.md

@@ -8,6 +8,20 @@ See also our [versioning policy](https://amici.readthedocs.io/en/latest/versioni
 
 **BREAKING CHANGES**
 
+* The package has been reorganized. All importers have been moved to
+  `amici.importers` subpackages. For example, all functionality from
+  `amici.sbml_import` is now available in `amici.importers.sbml`.
+* The naming of free and fixed parameters has been harmonized across the API:
+  AMICI differentiates between parameters with respect to which a model
+  can compute sensitivities ("free parameters") and parameters with respect to
+  which no sensitivities can be computed ("fixed parameters").
+  "Free" and "fixed" are to be understood in the context of parameter
+  estimation, where free parameters are optimized,
+  while fixed parameters remain constant.
+  Free parameters were previously referred to as just "parameters", and
+  fixed parameters as "fixed parameters", "constant parameters",
+  or "constants". This has now been harmonized to "free" and "fixed" across the
+  API. E.g., `Model.setParameters()` is now `Model.set_free_parameters()`.
 * `ReturnDataView.posteq_numsteps` and `ReturnDataView.posteq_numsteps` now
   return a one-dimensional array of shape `(num_timepoints,)` instead of a
   two-dimensional array of shape `(1, num_timepoints)`.

doc/examples/example_errors.ipynb

@@ -626,8 +626,10 @@
     "\n",
     "unscaled_parameter = dict(\n",
     "    zip(\n",
-    "        amici_model.get_parameter_ids(),\n",
-    "        starmap(amici.unscale_parameter, zip(edata.parameters, edata.pscale)),\n",
+    "        amici_model.get_free_parameter_ids(),\n",
+    "        starmap(\n",
+    "            amici.unscale_parameter, zip(edata.free_parameters, edata.pscale)\n",
+    "        ),\n",
     "    )\n",
     ")\n",
     "print(dict((p, unscaled_parameter[p]) for p in (\"Kd\", \"Kp\", \"n_par\")))"

doc/examples/example_large_models/example_performance_optimization.ipynb

@@ -219,9 +219,7 @@
   {
    "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 `fixedParameters` as arguments to `constant_parameters`, which ensures that amici is aware that we want to have them as `fixedParameters`:"
-   ]
+   "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:"
   },
   {
    "cell_type": "code",
@@ -234,7 +232,7 @@
     "    model_output_dir,\n",
     "    verbose=False,\n",
     "    observation_model=observables,\n",
-    "    constant_parameters=fixed_parameters,\n",
+    "    fixed_parameters=fixed_parameters,\n",
     ")\n",
     "# load the generated module\n",
     "model_module = amici.import_model_module(model_name, model_output_dir)"

doc/examples/example_presimulation/ExampleExperimentalConditions.ipynb

@@ -90,7 +90,7 @@
     "    # Setup simulation timepoints and parameters\n",
     "    model = model_module.get_model()\n",
     "    for name, value in parameters.items():\n",
-    "        model.set_parameter_by_name(name, value)\n",
+    "        model.set_free_parameter_by_name(name, value)\n",
     "    if isinstance(T, int | float):\n",
     "        T = np.linspace(0, T, 100)\n",
     "    model.set_timepoints([float(t) for t in T])\n",
@@ -589,9 +589,9 @@
    "source": [
     "# Sensitivities with respect to the spline values can be computed\n",
     "fig, ax = plt.subplots()\n",
-    "ax.plot(rdata[\"t\"], rdata.sx[:, 0], label=model.get_parameter_names()[0])\n",
-    "ax.plot(rdata[\"t\"], rdata.sx[:, 1], label=model.get_parameter_names()[1])\n",
-    "ax.plot(rdata[\"t\"], rdata.sx[:, 2], label=model.get_parameter_names()[2])\n",
+    "ax.plot(rdata[\"t\"], rdata.sx[:, 0], label=model.get_free_parameter_names()[0])\n",
+    "ax.plot(rdata[\"t\"], rdata.sx[:, 1], label=model.get_free_parameter_names()[1])\n",
+    "ax.plot(rdata[\"t\"], rdata.sx[:, 2], label=model.get_free_parameter_names()[2])\n",
     "ax.set_xlabel(\"time\")\n",
     "ax.set_ylabel(\"sensitivity\")\n",
     "ax.legend();"

doc/examples/example_splines/ExampleSplines.ipynb

@@ -79,10 +79,10 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "# Import necessary libraries and define the model\n",
     "import os\n",
@@ -165,16 +165,16 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
    "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": null,
    "source": [
     "# Import the model\n",
     "sbml_importer = amici.SbmlImporter(antimony2sbml(ant_model), from_file=False)\n",
     "\n",
     "# specify observables and constant parameters\n",
-    "constant_parameters = [\"synthesis_substrate\", \"init_enzyme\"]\n",
+    "fixed_parameters = [\"synthesis_substrate\", \"init_enzyme\"]\n",
     "observation_model = [\n",
     "    MC(id_=\"observable_product\", name=\"\", formula=\"product\"),\n",
     "    MC(id_=\"observable_substrate\", name=\"\", formula=\"substrate\"),\n",
@@ -188,7 +188,7 @@
     "    model_name,\n",
     "    model_output_dir,\n",
     "    observation_model=observation_model,\n",
-    "    constant_parameters=constant_parameters,\n",
+    "    fixed_parameters=fixed_parameters,\n",
     "    compute_conservation_laws=False,\n",
     ")\n",
     "\n",
@@ -198,7 +198,7 @@
     "    model_reduced_name,\n",
     "    model_reduced_output_dir,\n",
     "    observation_model=observation_model,\n",
-    "    constant_parameters=constant_parameters,\n",
+    "    fixed_parameters=fixed_parameters,\n",
     ")"
    ]
   },

doc/examples/example_steady_states/ExampleEquilibrationLogic.ipynb

@@ -73,12 +73,12 @@
   {
    "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_parameter_by_name](https://amici.readthedocs.io/en/latest/generated/amici.amici.Model.html#amici.amici.Model.set_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 [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`."
   },
   {
    "cell_type": "code",
    "metadata": {},
-   "source": "model.set_parameter_by_name(\"p1\", 1e-3)",
+   "source": "model.set_free_parameter_by_name(\"p1\", 1e-3)",
    "outputs": [],
    "execution_count": null
   },

doc/examples/getting_started/GettingStarted.ipynb

@@ -134,19 +134,17 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Constant parameters\n",
+    "### Fixed parameters\n",
     "\n",
-    "Constant parameters, i.e. parameters with respect to which no sensitivities are to be computed (these are often parameters specifying a certain experimental condition) are provided as a list of parameter names."
+    "Fixed parameters, i.e. parameters with respect to which no sensitivities are to be computed (these are often parameters specifying a certain experimental condition) are provided as a list of parameter names."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 4,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "constant_parameters = [\"k0\"]"
-   ]
+   "source": "fixed_parameters = [\"k0\"]"
   },
   {
    "cell_type": "markdown",
@@ -335,7 +333,7 @@
     "    model_output_dir,\n",
     "    verbose=logging.INFO,\n",
     "    observation_model=observation_model,\n",
-    "    constant_parameters=constant_parameters,\n",
+    "    fixed_parameters=fixed_parameters,\n",
     ")"
    ]
   },
@@ -373,7 +371,7 @@
     "model = model_module.get_model()\n",
     "\n",
     "print(\"Model name:            \", model.get_name())\n",
-    "print(\"Model parameters:      \", model.get_parameter_ids())\n",
+    "print(\"Model parameters:      \", model.get_free_parameter_ids())\n",
     "print(\"Model outputs:         \", model.get_observable_ids())\n",
     "print(\"Model state variables: \", model.get_state_ids())"
    ]
@@ -417,7 +415,7 @@
     "print(\n",
     "    \"Simulation was run using model default parameters as specified in the SBML model:\"\n",
     ")\n",
-    "print(dict(zip(model.get_parameter_ids(), model.get_parameters())))"
+    "print(dict(zip(model.get_free_parameter_ids(), model.get_free_parameters())))"
    ]
   },
   {
@@ -1113,11 +1111,11 @@
    "source": [
     "# Set model options\n",
     "model = model_module.get_model()\n",
-    "p_orig = np.array(model.get_parameters())\n",
+    "p_orig = np.array(model.get_free_parameters())\n",
     "p_orig[\n",
-    "    list(model.get_parameter_ids()).index(\"observable_x1withsigma_sigma\")\n",
+    "    list(model.get_free_parameter_ids()).index(\"observable_x1withsigma_sigma\")\n",
     "] = 0.1  # Change default parameter\n",
-    "model.set_parameters(p_orig)\n",
+    "model.set_free_parameters(p_orig)\n",
     "model.set_parameter_scale(amici.ParameterScaling.none)\n",
     "model.set_timepoints(np.linspace(0, 10, 21))\n",
     "\n",
@@ -1174,12 +1172,12 @@
     "        p[plist] = x0\n",
     "    verbose and print(f\"f: p={p}\")\n",
     "\n",
-    "    old_parameters = model.get_parameters()\n",
+    "    old_parameters = model.get_free_parameters()\n",
     "    solver.set_sensitivity_order(amici.SensitivityOrder.none)\n",
-    "    model.set_parameters(p)\n",
+    "    model.set_free_parameters(p)\n",
     "    rdata = amici.run_simulation(model, solver, edata)\n",
     "\n",
-    "    model.set_parameters(old_parameters)\n",
+    "    model.set_free_parameters(old_parameters)\n",
     "\n",
     "    res = np.sum(rdata[symbol])\n",
     "    verbose and print(res)\n",
@@ -1196,13 +1194,13 @@
     "        model.require_sensitivities_for_all_parameters()\n",
     "    verbose and print(f\"g: p={p}\")\n",
     "\n",
-    "    old_parameters = model.get_parameters()\n",
+    "    old_parameters = model.get_free_parameters()\n",
     "    solver.set_sensitivity_method(amici.SensitivityMethod.forward)\n",
     "    solver.set_sensitivity_order(amici.SensitivityOrder.first)\n",
-    "    model.set_parameters(p)\n",
+    "    model.set_free_parameters(p)\n",
     "    rdata = amici.run_simulation(model, solver, edata)\n",
     "\n",
-    "    model.set_parameters(old_parameters)\n",
+    "    model.set_free_parameters(old_parameters)\n",
     "\n",
     "    res = rdata[f\"s{symbol}\"]\n",
     "    if not isinstance(res, float):\n",
@@ -1257,7 +1255,7 @@
    "outputs": [],
    "source": [
     "eps = 1e-4\n",
-    "op = model.get_parameters()\n",
+    "op = model.get_free_parameters()\n",
     "\n",
     "\n",
     "solver.set_sensitivity_method(\n",
@@ -1273,23 +1271,23 @@
     "\n",
     "def fd(x0, ip, eps, symbol=\"llh\"):\n",
     "    p = list(x0[:])\n",
-    "    old_parameters = model.get_parameters()\n",
+    "    old_parameters = model.get_free_parameters()\n",
     "    solver.set_sensitivity_order(amici.SensitivityOrder.none)\n",
     "    p[ip] += eps\n",
-    "    model.set_parameters(p)\n",
+    "    model.set_free_parameters(p)\n",
     "    rdata_f = amici.run_simulation(model, solver, edata)\n",
     "    p[ip] -= 2 * eps\n",
-    "    model.set_parameters(p)\n",
+    "    model.set_free_parameters(p)\n",
     "    rdata_b = amici.run_simulation(model, solver, edata)\n",
     "\n",
-    "    model.set_parameters(old_parameters)\n",
+    "    model.set_free_parameters(old_parameters)\n",
     "    return (rdata_f[symbol] - rdata_b[symbol]) / (2 * eps)\n",
     "\n",
     "\n",
     "def plot_sensitivities(symbol, eps):\n",
     "    fig, axes = plt.subplots(4, 2, figsize=(15, 10))\n",
     "    for ip in range(4):\n",
-    "        fd_approx = fd(model.get_parameters(), ip, eps, symbol=symbol)\n",
+    "        fd_approx = fd(model.get_free_parameters(), ip, eps, symbol=symbol)\n",
     "\n",
     "        axes[ip, 0].plot(\n",
     "            edata.get_timepoints(), rdata[f\"s{symbol}\"][:, ip, :], \"r-\"\n",

doc/examples/getting_started_extended/GettingStartedExtended.ipynb

@@ -27,10 +27,20 @@ Glossary
 
     fixed parameters
         In AMICI, *fixed parameters* are parameters with respect to which no
-        sensitivities are computed. They usually correspond to experimental
-        conditions. For fixed parameters, different values can be set for
+        sensitivities are computed. The values of fixed parameters can changed.
+        "fixed" here refers to the fact that these parameters are fixed
+        in context of parameter estimation.
+        Fixed parameters encode, for example, experimental conditions.
+        For fixed parameters, different values can be set for
         :term:`pre-equilibration`, :term:`pre-simulation` and the main
         simulation. See also :term:`simulation periods`.
+        See also :term:`free parameters`.
+
+    free parameters
+        In AMICI, *free parameters* are parameters with respect to which
+        sensitivities are computed. These are typically the parameters that
+        are estimated in a parameter estimation problem.
+        See also :term:`fixed parameters`.
 
     IDAS
         `IDAS <https://computing.llnl.gov/projects/sundials/idas>`_ is a

doc/glossary.rst

@@ -58,7 +58,8 @@ class ExpData : public SimulationParameters {
      * @param nztrue Number of event outputs
      * @param nmaxevent Maximal number of events to track
      * @param ts Timepoints (dimension: nt)
-     * @param fixed_parameters Model constants (dimension: nk)
+     * @param fixed_parameters Model variables excluded from sensitivity
+     * analysis (dimension: nk)
      */
     ExpData(
         int nytrue, int nztrue, int nmaxevent, std::vector<realtype> ts,