Add multiple reactions in particles

doc/interface/reaction/index.rst

@@ -3,12 +3,66 @@
 Reaction models
 ===============
 
+Reactions can take place on different phases in the model. The interface specification depends on the phase where and between the reaction takes place.
+
+A reaction can be located in:
+
+- **Column**: The reaction group is defined under the corresponding column phase i.e. ``unit_XXX/phase_reaction_YYY``.
+- **Particle**: The reaction group is defined under the corresponding particle phase i.e. ``particle_type_XXX/phase_reaction_YYY``.
+
+Furthermore, we differ between reactions which take place in either a single phase or between two phases.
+
+Single Phase Reactions
+----------------
+Single phase reactions take place either in the liquid phase, the solid phase.
+
+The number of reaction is specified at the **column/particle level** using the following parameters:
+
+  - ``NREAC_LIQUID`` for liquid phase reactions,
+  - ``NREAC_SOLID`` for solid phase reactions.
+
+The input group for single reactions is given by ``phase_reaction_YYY`` where ``phase`` is one of ``liquid`` or ``solid`` and ``YYY`` is a 0-based index for the reaction group.
+
+**Single-Phase Reaction Models**:
+
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     mass_action_law
     michaelis_menten_kinetics
 
+
+Cross Phase Reactions
+---------------------
+Cross phase reactions take place between a liquid phase and a solid phase.
+
+To specify the number of reactions, use the parameter at the **column/particle level**:
+  - ``NREAC_CROSS_PHASE`` for cross-phase reactions.
+
+The input group for cross-phase reactions is given by ``cross_phase_reaction_YYY`` where ``YYY`` is a 0-based index for the reaction group.
+
+**Cross-Phase Reaction Models**:
+
+.. toctree::
+    :maxdepth: 1
+
+    mass_action_law_cross_phase
+
+.. note::
+  - Cross-phase reaction models can **only** be used in the cross-phase formulation
+  - For the LRM model, cross-phase reactions are not supported in the particle phase.
+
+
+Step by Step Guide to Define Reactions
+--------------------------------------
+
+1. Choose the appropriate reaction model based on the kinetics of your system (e.g., Mass Action Law, Michaelis-Menten).
+2. Choose a phase for your reaction (liquid, solid or cross phase) and define the input group accordingly (i.e., ``liquid_reaction_000``).
+3. Choose how many reaction types you want to define for the selected phase and set up the corresponding parameter in the configuration file (e.g., ``NREAC_LIQUID``, ``NREAC_SOLID``, ``NREAC_CROSS_PHASE``).
+  **Note** here that the input group depends on whether the reaction is defined in a particle phase or not.
+4. Define the reaction parameters according to the chosen model's specifications. Refer to the specific reaction model documentation for details on required parameters.
+
+
 Externally dependent reaction models
 ------------------------------------
 
@@ -30,17 +84,3 @@ However, if only one index is passed in ``EXTFUN``, this external source is used
 
 Note that parameter sensitivities with respect to column radius, column length, particle core radius, and particle radius may be wrong when using externally dependent reaction models.
 This is caused by not taking into account the derivative of the external profile with respect to column position.
-
-
-.. _multiple-particle-types_reactions:
-
-Multiple particle types
------------------------
-
-The group that contains the parameters of a reaction model in unit operation with index ``XXX`` reads ``/input/model/unit_XXX/reaction_particle``.
-This is valid for models with a single particle type.
-If a model has multiple particle types, it may have a different reaction model in each type.
-The parameters are then placed in the group ``/input/model/unit_XXX/reaction_particle_YYY`` instead, where ``YYY`` denotes the index of the particle type.
-
-Note that, in any case, ``/input/model/unit_XXX/reaction_particle_000`` contains the parameters of the first (and possibly sole) particle type.
-This group also takes precedence over a possibly existing ``/input/model/unit_XXX/adsorption_particle`` group.

doc/interface/reaction/mass_action_law.rst

@@ -3,158 +3,81 @@
 Mass Action Law
 ~~~~~~~~~~~~~~~
 
-**Group /input/model/unit_XXX/reaction - REACTION_MODEL = MASS_ACTION_LAW**
+**Group /input/model/unit_XXX(/particle_type_YYY)/phase_reaction_ZZZ/ - REACTION_MODEL = MASS_ACTION_LAW**
 
 For information on model equations, refer to :ref:`mass_action_law_model`.
 
-``MAL_KFWD_BULK``
+Notes
+-----
 
-   Forward rate constants for bulk volume reactions (available for external functions)
-
-   ================  =========================  ===================================
-   **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
-   ================  =========================  ===================================
-
-``MAL_KBWD_BULK``
+- ``reaction_phase`` refers to one of the phase-specific groups listed in :ref:`FFReaction`, e.g., ``reaction_bulk``, ``reaction_solid``, or ``reaction_particle_YYY`` (for particle type ``YYY``).
+- Each ``reaction_model_YYY`` is one instance of a reaction model and can contain multiple reactions (lengths denoted by ``NREACT`` below).
+- Dimensions of matrices depend on the hosting phase of this model instance:
 
-   Backward rate constants for bulk volume reactions (available for external functions)
-
-   ================  =========================  ===================================
-   **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
-   ================  =========================  ===================================
-
-``MAL_KFWD_LIQUID``
+  - Bulk phase or particle liquid phase: ``NVAR = NCOMP``
+   - Particle solid phase: ``NVAR = NTOTALBOUND`` (total number of bound states across all components)
 
-   Forward rate constants for particle liquid phase reactions (available for external functions)
-
-   ================  =========================  ===================================
-   **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
-   ================  =========================  ===================================
-
-``MAL_KBWD_LIQUID``
+``MAL_KFWD``
 
-   Backward rate constants for particle liquid phase reactions (available for external functions)
+   Forward rate constants for reactions in this phase (available for external functions)
 
    ================  =========================  ===================================
    **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
    ================  =========================  ===================================
 
-``MAL_KFWD_SOLID``
+``MAL_KBWD``
 
-   Forward rate constants for particle solid phase reactions (available for external functions)
+   Backward rate constants for reactions in this phase (available for external functions)
 
    ================  =========================  ===================================
    **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
    ================  =========================  ===================================
-
-``MAL_KBWD_SOLID``
 
-   Backward rate constants for particle solid phase reactions (available for external functions)
-
-   ================  =========================  ===================================
-   **Type:** double  **Range:** :math:`\geq 0`  **Length:** :math:`\texttt{NREACT}`
-   ================  =========================  ===================================
-
-``MAL_STOICHIOMETRY_BULK``
+``MAL_STOICHIOMETRY``
 
-   Stoichiometric matrix of bulk volume reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage
+   Stoichiometric matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (phase-dependent ``NVAR``, see Notes)
 
    ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
+   **Type:** double  **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
    ================  ========================================================
-
-``MAL_EXPONENTS_BULK_FWD``
-
-   Forward exponent matrix of bulk volume reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_BULK}` by default)
-
-   ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
-   ================  ========================================================
-
-``MAL_EXPONENTS_BULK_BWD``
 
-   Backward exponent matrix of bulk volume reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_BULK}` by default)
-
-   ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
-   ================  ========================================================
-
-``MAL_STOICHIOMETRY_LIQUID``
+``MAL_EXPONENTS_FWD``
 
-   Stoichiometric matrix of particle liquid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage
+   Forward exponent matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY}` by default)
 
    ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
+   **Type:** double  **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
    ================  ========================================================
-
-``MAL_EXPONENTS_LIQUID_FWD``
 
-   Forward exponent matrix of particle liquid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_LIQUID}` by default)
-
-   ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
-   ================  ========================================================
-
-``MAL_EXPONENTS_LIQUID_BWD``
+``MAL_EXPONENTS_BWD``
 
-   Backward exponent matrix of particle liquid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_LIQUID}` by default)
+   Backward exponent matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY}` by default)
 
    ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
+   **Type:** double  **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
    ================  ========================================================
-
-``MAL_EXPONENTS_LIQUID_FWD_MODSOLID``
 
-   Forward solid phase modifier exponent matrix of particle liquid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage (optional, defaults to all 0)
-
-   ================  ============================================================
-   **Type:** double  **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
-   ================  ============================================================
-
-``MAL_EXPONENTS_LIQUID_BWD_MODSOLID``
+Examples
+--------
+.. code-block::
 
-   Backward solid phase modifier exponent matrix of particle liquid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage (optional, defaults to all 0)
-
-   ================  ============================================================
-   **Type:** double  **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
-   ================  ============================================================
-
-``MAL_STOICHIOMETRY_SOLID``
+Cross-phase reaction that consumes one bulk and one liquid component and produces a solid state (one reaction)::
 
-   Stoichiometric matrix of particle solid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage
-
-   ================  ============================================================
-   **Type:** double  **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
-   ================  ============================================================
-
-``MAL_EXPONENTS_SOLID_FWD``
+   input.model.unit_000.reaction_liquid_000.NREAC_LIQUID = 1
+   input.model.unit_000.reaction_liquid_000.type = MASS_ACTION_LAW
+   input.model.unit_000.reaction_liquid_000.reaction_model_000.MAL_KFWD = [1.0]
+   input.model.unit_000.reaction_liquid_000.reaction_model_000.MAL_KBWD = [1.0]
+   input.model.unit_000.reaction_liquid_000.reaction_model_000.MAL_STOICHIOMETRY = [... length NCOMP*1 ...]
 
-   Forward exponent matrix of particle solid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_SOLID}` by default)
-
-   ================  ============================================================
-   **Type:** double  **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
-   ================  ============================================================
-
-``MAL_EXPONENTS_SOLID_BWD``
+Cross-Phase reaction in a pore::
 
-   Backward exponent matrix of particle solid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY_SOLID}` by default)
-
-   ================  ============================================================
-   **Type:** double  **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
-   ================  ============================================================
-
-``MAL_EXPONENTS_SOLID_FWD_MODLIQUID``
+   input.model.unit_000.particle_type_000.NREAC_PORE = 1
+   input.model.unit_000.particle_type_000.reaction_pore_000.type = MASS_ACTION_LAW
+   input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_KFWD = [1.0]
+   input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_KBWD = [1.0]
+   input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_STOICHIOMETRY = [... length NCOMP*1 ...]
 
-   Forward liquid phase modifier exponent matrix of particle solid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, defaults to all 0)
-
-   ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
-   ================  ========================================================
-
-``MAL_EXPONENTS_SOLID_BWD_MODLIQUID``
+See also
+--------
 
-   Backward liquid phase modifier exponent matrix of particle solid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage (optional, defaults to all 0)
-
-   ================  ========================================================
-   **Type:** double  **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
-   ================  ========================================================
+- Cross-phase variant: :ref:`mass_action_law_cross_phase_config` (supports liquid/solid modifiers and bulk coupling)