v2: Clarify model initialization (#645)

Clarify that the parameter table is applied before initial assignments are executed and change the way how concentration and  compartment changes are handled.

Author: dweindl

doc/v2/documentation_data_format.rst

@@ -142,10 +142,10 @@ PEtab 2.0.0 is a major update of the PEtab format. The main changes are:
    **Figure 3: A comparison of simulations in PEtab v1 and v2.**
 
 * Support for math expressions in the condition table
-  (:ref:`v2_condition_table`).
+  (:ref:`v2_condition_table`, :ref:`v2_math_expressions`).
 * Clarification and specification of various previously underspecified
   aspects, including overriding values via the condition table
-  (:ref:`v2_math_expressions`).
+  (:ref:`v2_initialization_semantics`, :ref:`v2_reinitialization_semantics`).
 * Support for format :ref:`extensions <petab_extensions>`.
 * Observable IDs can now be used in observable and noise formulas
   (:ref:`v2_observable_table`).
@@ -296,53 +296,50 @@ Detailed field description
 Detailed semantics
 ~~~~~~~~~~~~~~~~~~
 
-All changes defined in the condition table are applied in five consecutive
-phases, following the logic of the event assignments in a single SBML event.
+See :ref:`v2_initialization_semantics` for how the changes for the initial
+period of an experiment are applied and how the model is initialized.
+For any subsequent time period, the changes defined in the condition table
+are applied in five consecutive phases:
 
 1. **Evaluation of** ``targetValues``
 
    ``targetValues`` are first evaluated using the *current* values of all
    variables in the respective expressions.
-
-   * For the initial time period of an experiment, *current* values are
-     determined by the initial conditions defined in the model.
-
-     Constructs defining initial values of model entities (e.g., SBML's
-     *initialAssignments*) are applied only once at the start of the first
-     time period and are not re-evaluated in later time periods. The start
-     time of the first time period is defined by the respective experiment.
-
-   * For subsequent time periods, the *current* values are taken from the
-     simulation results at the end of the preceding time period.
-     A special case is simulation time (``time``),
-     which is set to the start time of the current time period.
+   The *current* values are taken from the simulation results at the end of the
+   preceding time period.
+   A special case is simulation time (``time``),
+   which is set to the start time of the current time period.
 
 2. **Assignment of the evaluated** ``targetValues`` **to their targets**
 
    All evaluated ``targetValues`` are simultaneously assigned to their
    respective targets. It is invalid to apply multiple assignments to the
    same target at the same time.
 
-   * These assignments respect language specific interpretations of which
-     variables are *atomic* or *derived*/*algebraic*. Most notably, SBML
-     considers species amounts and compartment sizes but not
-     concentrations to be *atomic*. This means that any entry that has a
-     ``targetId`` that refers to a species with
-     ``hasOnlySubstanceUnits=false`` will have its ``targetValue``
-     (interpreted as concentration) converted to amounts using the
-     **current** compartment size and then applied to the target's amount.
-     For further details, refer to SBML semantic test suite case `01779
-     <https://github.com/sbmlteam/sbml-test-suite/blob/7ab011efe471877987b5d6dcba8cc19a6ff71254/cases/semantic/01779/01779-model.m>`_.
+   The interpretation of the assigned value depends on the type of the
+   model and the target entity.
+   For example, for an SBML model and a ``targetId`` referring to a species,
+   the ``targetValue`` will override the current amount of the species
+   if ``hasOnlySubstanceUnits=true`` (*amount-based species*),
+   or the current concentration if ``hasOnlySubstanceUnits=false``
+   (*concentration-based species*).
+
+   If the target is a compartment, the compartment size is set to the
+   evaluated value of the ``targetValue`` expression.
+   The value of a species in such a compartment is not changed by this
+   assignment. I.e., for an amount-based species, the amount of the species
+   will be preserved (the concentration may change accordingly),
+   and for a concentration-based species, the concentration will be preserved
+   (the amount may change accordingly).
+   Mind that this differs from the behavior of an SBML event assignment where
+   compartment size changes always preserve the amounts of species in that
+   compartment.
 
 3. **Update of derived variables**
 
    After target values have been assigned, all derived variables (i.e.,
-   algebraic entities such as SBML assignment rules or PySB expressions) are updated.
-
-   * These updates follow language specific rules of which variables are
-     *atomic* or *derived*/*algebraic*. For example, SBML treats species
-     concentrations to be *derived*, meaning they are recomputed based on
-     (updated) species amounts and corresponding compartment sizes.
+   algebraic entities such as SBML assignment rules or PySB expressions)
+   are updated.
 
 4. **Events and finalization**
 
@@ -827,6 +824,8 @@ One row per parameter with arbitrary order of rows and columns:
 
 Additional columns may be added.
 
+See :ref:`v2_initialization_semantics` for details on how and when the values
+of parameter table parameters are applied.
 
 Detailed field description
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1117,6 +1116,56 @@ Conditions and observables that are not applied to a model do not need to be
 valid for that model.
 
 
+.. _v2_initialization_semantics:
+
+Initialization and parameter application
+----------------------------------------
+
+The following describes how the model is initialized and how other PEtab
+parameter values are applied before the simulation starts.
+This procedure is executed for each model and experiment combination
+defined in the PEtab problem.
+
+1. Pre-initialization
+
+   1. Parameters values for parameters that occur in the parameter table are
+      applied to the uninitialized model.
+      *Uninitialized* means that no model-internal initial values have been
+      computed yet (e.g., in SBML models, no initial assignments have been
+      evaluated and no derived initial quantities such as concentrations have
+      been computed yet).
+      For estimated parameters, the respective externally-provided values
+      are applied and for non-estimated parameters, the nominal values
+      from the parameter table are applied.
+
+   2. The time is set to the start time of the first period of the given
+      experiment (or 0 if there is no explicit experiment), and any
+      experiment-specific conditions provided for the first period are applied
+      (see :ref:`v2_reinitialization_semantics` for details).
+      Target value expressions for the first period must not refer to model
+      entities that are not also listed in the parameter table.
+
+   This pre-initialization replaces any model-internal initial values
+   (or initialization constructs such as SBML's *initialAssignments*)
+   that would alter the initial time, the values of the parameters contained
+   in the parameter table or any target values from the condition table.
+
+2. Model initialization
+
+   The model is initialized according to the model semantics, e.g., by
+   evaluating the initial assignments or applying the initial values of
+   state variables.
+
+3. Simulation
+
+   Model simulation starts with evaluating any event triggers at the initial
+   time, applying pending event assignments, and evaluating the observables
+   at the initial time (Steps 4 and 5 in :ref:`v2_reinitialization_semantics`).
+
+   For any subsequent experiment periods, the steps described in
+   :ref:`v2_reinitialization_semantics` are applied at their start times.
+
+
 .. _v2_objective_function:
 
 Frequentist vs. Bayesian inference