Skip to content

Commit e579e7d

Browse files
AntoniaBergerAntoniaBerger
committed
New docu for reactions
adjust docu
1 parent 9db4bfa commit e579e7d

File tree

7 files changed

+411
-158
lines changed

7 files changed

+411
-158
lines changed

‎doc/interface/reaction/index.rst‎

Lines changed: 80 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,92 @@
33
Reaction models
44
===============
55

6+
This section describes the configuration of reaction models for different phases in CADET unit operations.
7+
8+
Reactions can take place on different phases in the model. Depending on the unit operation, reactions can be defined for the bulk phase, solid phase, particle phase, or as cross-phase reactions between liquid and solid phases.
9+
In general the following phases are supported with reactions
10+
11+
- Bulk - main fluid phase in GRM and LRMP units
12+
- Solid - solid phase of particles
13+
- Pore - liquid within particles
14+
- Liquid - main fluid phase in LRM and CSTR
15+
16+
The following table provides an overview of reaction phase support across different unit operations:
17+
18+
19+
.. list-table:: Unit Operation Reaction Phase Support
20+
:header-rows: 1
21+
:widths: 40 20 20 20
22+
23+
* - Unit Operation
24+
- Bulk/Liquid
25+
- Pore/Particle Liquid
26+
- Solid/Particle Solid
27+
* - GeneralRateModel (1D/2D/DG)
28+
- bulk
29+
- pore (particle liquid)
30+
- solid (particle solid)
31+
* - LumpedRateModelWithPores
32+
- bulk
33+
- liquid (particle liquid)
34+
- solid (particle solid)
35+
* - LumpedRateModelWithoutPores
36+
- liquid (particle liquid / bulk)
37+
- --
38+
- solid (particle solid)
39+
* - CSTR
40+
- liquid (particle liquid / bulk)
41+
- --
42+
- solid (particle solid)
43+
* - MCTM
44+
- liquid (bulk)
45+
- --
46+
- --
47+
48+
49+
**Single-Phase Reaction Models** (for bulk, solid, and particle phases):
50+
651
.. toctree::
752
:maxdepth: 2
853

954
mass_action_law
1055
michaelis_menten_kinetics
1156

57+
58+
Cross Phase Reactions
59+
---------------------
60+
61+
Cross-phase reactions enable chemical processes that occur at the interface between different phases,
62+
such as dissolution, precipitation, or catalytic reactions on solid surfaces. These reactions
63+
are different from single-phase reactions as they involve mass transfer between phases.
64+
They are defined between a solid phase and a liquid phase i.e bulk/particle liquid and solid/particle solid phase.
65+
66+
**Cross-Phase Reaction Models**:
67+
68+
.. toctree::
69+
:maxdepth: 2
70+
71+
mass_action_law_cross_phase
72+
73+
.. note::
74+
Cross-phase reaction models can **only** be used in the cross-phase formulation
75+
For reactions within a single phase, use the standard reaction models listed above.
76+
77+
78+
Particle Reactions
79+
------------------
80+
81+
Consider which phases in your unit operation should have reactions.
82+
If the reaction takes place in a phase associated with a particle, the reaction group is defined under the corresponding particle phase i.e. ``particle_type_XXX``.
83+
Each particle can have its own reaction model configuration.
84+
85+
.. note::
86+
- For reactions within a single phase, use the standard reaction models listed above.
87+
- For reactions between a liquid and solid phase, use cross-phase reaction models.
88+
89+
90+
91+
1292
Externally dependent reaction models
1393
------------------------------------
1494

@@ -30,17 +110,3 @@ However, if only one index is passed in ``EXTFUN``, this external source is used
30110

31111
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.
32112
This is caused by not taking into account the derivative of the external profile with respect to column position.
33-
34-
35-
.. _multiple-particle-types_reactions:
36-
37-
Multiple particle types
38-
-----------------------
39-
40-
The group that contains the parameters of a reaction model in unit operation with index ``XXX`` reads ``/input/model/unit_XXX/reaction_particle``.
41-
This is valid for models with a single particle type.
42-
If a model has multiple particle types, it may have a different reaction model in each type.
43-
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.
44-
45-
Note that, in any case, ``/input/model/unit_XXX/reaction_particle_000`` contains the parameters of the first (and possibly sole) particle type.
46-
This group also takes precedence over a possibly existing ``/input/model/unit_XXX/adsorption_particle`` group.

‎doc/interface/reaction/mass_action_law.rst‎

Lines changed: 39 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -3,158 +3,81 @@
33
Mass Action Law
44
~~~~~~~~~~~~~~~
55

6-
**Group /input/model/unit_XXX/reaction - REACTION_MODEL = MASS_ACTION_LAW**
6+
**Group /input/model/unit_XXX/reaction_phase/reaction_model_YYY - REACTION_MODEL = MASS_ACTION_LAW**
77

88
For information on model equations, refer to :ref:`mass_action_law_model`.
99

10-
``MAL_KFWD_BULK``
10+
Notes
11+
-----
1112

12-
Forward rate constants for bulk volume reactions (available for external functions)
13-
14-
================ ========================= ===================================
15-
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
16-
================ ========================= ===================================
17-
18-
``MAL_KBWD_BULK``
13+
- ``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``).
14+
- Each ``reaction_model_YYY`` is one instance of a reaction model and can contain multiple reactions (lengths denoted by ``NREACT`` below).
15+
- Dimensions of matrices depend on the hosting phase of this model instance:
1916

20-
Backward rate constants for bulk volume reactions (available for external functions)
21-
22-
================ ========================= ===================================
23-
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
24-
================ ========================= ===================================
25-
26-
``MAL_KFWD_LIQUID``
17+
- Bulk phase or particle liquid phase: ``NVAR = NCOMP``
18+
- Particle solid phase: ``NVAR = NTOTALBOUND`` (total number of bound states across all components)
2719

28-
Forward rate constants for particle liquid phase reactions (available for external functions)
29-
30-
================ ========================= ===================================
31-
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
32-
================ ========================= ===================================
33-
34-
``MAL_KBWD_LIQUID``
20+
``MAL_KFWD``
3521

36-
Backward rate constants for particle liquid phase reactions (available for external functions)
22+
Forward rate constants for reactions in this phase (available for external functions)
3723

3824
================ ========================= ===================================
3925
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
4026
================ ========================= ===================================
4127

42-
``MAL_KFWD_SOLID``
28+
``MAL_KBWD``
4329

44-
Forward rate constants for particle solid phase reactions (available for external functions)
30+
Backward rate constants for reactions in this phase (available for external functions)
4531

4632
================ ========================= ===================================
4733
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
4834
================ ========================= ===================================
49-
50-
``MAL_KBWD_SOLID``
5135

52-
Backward rate constants for particle solid phase reactions (available for external functions)
53-
54-
================ ========================= ===================================
55-
**Type:** double **Range:** :math:`\geq 0` **Length:** :math:`\texttt{NREACT}`
56-
================ ========================= ===================================
57-
58-
``MAL_STOICHIOMETRY_BULK``
36+
``MAL_STOICHIOMETRY``
5937

60-
Stoichiometric matrix of bulk volume reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage
38+
Stoichiometric matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (phase-dependent ``NVAR``, see Notes)
6139

6240
================ ========================================================
63-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
41+
**Type:** double **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
6442
================ ========================================================
65-
66-
``MAL_EXPONENTS_BULK_FWD``
67-
68-
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)
69-
70-
================ ========================================================
71-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
72-
================ ========================================================
73-
74-
``MAL_EXPONENTS_BULK_BWD``
7543

76-
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)
77-
78-
================ ========================================================
79-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
80-
================ ========================================================
81-
82-
``MAL_STOICHIOMETRY_LIQUID``
44+
``MAL_EXPONENTS_FWD``
8345

84-
Stoichiometric matrix of particle liquid phase reactions as :math:`\texttt{NCOMP} \times \texttt{NREACT}` matrix in row-major storage
46+
Forward exponent matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY}` by default)
8547

8648
================ ========================================================
87-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
49+
**Type:** double **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
8850
================ ========================================================
89-
90-
``MAL_EXPONENTS_LIQUID_FWD``
9151

92-
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)
93-
94-
================ ========================================================
95-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
96-
================ ========================================================
97-
98-
``MAL_EXPONENTS_LIQUID_BWD``
52+
``MAL_EXPONENTS_BWD``
9953

100-
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)
54+
Backward exponent matrix as :math:`\texttt{NVAR} \times \texttt{NREACT}` matrix in row-major storage (optional, calculated from :math:`\texttt{MAL_STOICHIOMETRY}` by default)
10155

10256
================ ========================================================
103-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
57+
**Type:** double **Length:** :math:`\texttt{NVAR} \cdot \texttt{NREACT}`
10458
================ ========================================================
105-
106-
``MAL_EXPONENTS_LIQUID_FWD_MODSOLID``
10759

108-
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)
109-
110-
================ ============================================================
111-
**Type:** double **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
112-
================ ============================================================
113-
114-
``MAL_EXPONENTS_LIQUID_BWD_MODSOLID``
60+
Examples
61+
--------
62+
.. code-block::
11563
116-
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)
117-
118-
================ ============================================================
119-
**Type:** double **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
120-
================ ============================================================
121-
122-
``MAL_STOICHIOMETRY_SOLID``
64+
Cross-phase reaction that consumes one bulk and one liquid component and produces a solid state (one reaction)::
12365

124-
Stoichiometric matrix of particle solid phase reactions as :math:`\texttt{NTOTALBND} \times \texttt{NREACT}` matrix in row-major storage
125-
126-
================ ============================================================
127-
**Type:** double **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
128-
================ ============================================================
129-
130-
``MAL_EXPONENTS_SOLID_FWD``
66+
input.model.unit_000.reaction_bulk_000.NREAC_bulk = 1
67+
input.model.unit_000.reaction_bulk_000.type = MASS_ACTION_LAW
68+
input.model.unit_000.reaction_bulk_000.reaction_model_000.MAL_KFWD = [1.0]
69+
input.model.unit_000.reaction_bulk_000.reaction_model_000.MAL_KBWD = [1.0]
70+
input.model.unit_000.reaction_bulk_000.reaction_model_000.MAL_STOICHIOMETRY = [... length NCOMP*1 ...]
13171

132-
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)
133-
134-
================ ============================================================
135-
**Type:** double **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
136-
================ ============================================================
137-
138-
``MAL_EXPONENTS_SOLID_BWD``
72+
Cross-Phase reaction in a pore::
13973

140-
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)
141-
142-
================ ============================================================
143-
**Type:** double **Length:** :math:`\texttt{NTOTALBND} \cdot \texttt{NREACT}`
144-
================ ============================================================
145-
146-
``MAL_EXPONENTS_SOLID_FWD_MODLIQUID``
74+
input.model.unit_000.particle_type_000.NREAC_PORE = 1
75+
input.model.unit_000.particle_type_000.reaction_pore_000.type = MASS_ACTION_LAW
76+
input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_KFWD = [1.0]
77+
input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_KBWD = [1.0]
78+
input.model.unit_000.particle_type_000.reaction_pore_000.reaction_model_000.MAL_STOICHIOMETRY = [... length NCOMP*1 ...]
14779

148-
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)
149-
150-
================ ========================================================
151-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
152-
================ ========================================================
153-
154-
``MAL_EXPONENTS_SOLID_BWD_MODLIQUID``
80+
See also
81+
--------
15582

156-
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)
157-
158-
================ ========================================================
159-
**Type:** double **Length:** :math:`\texttt{NCOMP} \cdot \texttt{NREACT}`
160-
================ ========================================================
83+
- Cross-phase variant: :ref:`mass_action_law_cross_phase_config` (supports liquid/solid modifiers and bulk coupling)

0 commit comments

Comments
 (0)