From 559f13d4503c33792a261ff58df5eaced723c878 Mon Sep 17 00:00:00 2001
From: Kutalmis Bercin <kutalmis.bercin@esi-group.com>
Date: Thu, 25 Jul 2024 10:05:31 +0100
Subject: [PATCH] DOC: scalarTransport/energyTransport: improve header file
 documentation

---
 .../solvers/energyTransport/energyTransport.H | 292 ++++++++++--------
 .../solvers/scalarTransport/scalarTransport.H | 210 +++++++------
 2 files changed, 276 insertions(+), 226 deletions(-)

diff --git a/src/functionObjects/solvers/energyTransport/energyTransport.H b/src/functionObjects/solvers/energyTransport/energyTransport.H
index 1487259896..eea60e707d 100644
--- a/src/functionObjects/solvers/energyTransport/energyTransport.H
+++ b/src/functionObjects/solvers/energyTransport/energyTransport.H
@@ -30,152 +30,180 @@ Group
     grpSolversFunctionObjects
 
 Description
-    Evolves a simplified energy transport equation for incompressible flows.
-    It takes into account the inertia, conduction and convection terms plus
-    a source.
+    Computes the simplified energy transport equation in single-phase or
+    two-phase flow, considering incompressible cases:
 
-    - The field name must be temperature and its BC's specified in the time
-      directory.
-    - The turbulence model should be incompressible
-    - In order to use in a incompressible multi phase a list of thermal
-      properties are needed. See below
+    \f[
+        \frac{\partial \rho \, C_p \, T}{\partial t}
+      + \nabla \cdot \left(\rho \, C_p \, \phi \, T \right)
+      - \nabla \cdot \left(\rho \, C_p \, \phi \right) \, T
+      - \nabla \cdot \left(\kappa_{eff} \, \nabla T \right)
+      = S_T
+    \f]
 
+    where:
+    \vartable
+      T       | Scalar field
+      \rho    | (Generic) Fluid density which is unity when not specified
+      C_p     | Specific heat capacity at constant pressure
+      \phi    | (Generic) Flux field
+      \kappa_{eff}  | Effective thermal conductivity
+      S_T     | Scalar field source term
+    \endvartable
 
 Usage
-    Example of function object specification to solve a energy transport
-    equation for a single phase flow plus a source term
+    Minimal example in \c system/controlDict.functions:
     \verbatim
-    functions
+    energyTransport1
     {
-        energy
-        {
-            type            energyTransport;
-            libs            (energyTransportFunctionObjects);
+        // Mandatory entries
+        type            energyTransport;
+        libs            (solverFunctionObjects);
 
-            enabled         true;
-            writeControl    writeTime;
-            writeInterval   1;
+        // Optional entries
+        field           <word>;
+        phi             <word>;
+        rho             <word>;
+        Cp              <scalar>;
+        kappa           <scalar>;
+        rhoInf          <scalar>;
+        Prt             <scalar>;
+        schemesField    <word>;
+        tolerance       <scalar>;
+        nCorr           <label>;
+        fvOptions       <dict>;
+        phaseThermos    <dict>;
 
-            field           T;
-
-            // volumetric Flux
-            phi             phi;
-
-            // Thermal properties
-            Cp              Cp    [J/kg/K]  1e3;
-            kappa           kappa [W/m/K]   0.0257;
-            rhoInf          rho   [kg/m^3]  1.2;
-
-            write           true;
-
-            fvOptions
-            {
-                viscousDissipation
-                {
-                    type            viscousDissipation;
-                    enabled         true;
-
-                    viscousDissipationCoeffs
-                    {
-                        fields          (T);
-                        rhoInf          $....rhoInf;
-                    }
-                }
-            }
-        }
+        // Inherited entries
+        ...
     }
     \endverbatim
 
-    Example of function object specification to solve a energy transport
-    equation for a multiphase phase flow plus a source term
-
-    equation:
-    \verbatim
-    functions
-    {
-        energy
-        {
-            type            energyTransport;
-            libs            (energyTransportFunctionObjects);
-
-            enabled         true;
-            writeControl    writeTime;
-            writeInterval   1;
-
-            field           T;
-
-            // rho field name
-            rho             rho;
-            // mass flux for multiphase
-            phi             rhoPhi;
-
-            write           true;
-
-            // Thermal properties of the phases
-            phaseThermos
-            {
-                alpha.air
-                {
-                    Cp          1e3;
-                    kappa       0.0243;
-                }
-                alpha.mercury
-                {
-                    Cp          140;
-                    kappa       8.2;
-                }
-                alpha.oil
-                {
-                    Cp          2e3;
-                    kappa       0.2;
-                }
-                alpha.water
-                {
-                    Cp          4e3;
-                    kappa       0.6;
-                }
-            }
-
-
-            fvOptions
-            {
-                viscousDissipation
-                {
-                    type            viscousDissipation;
-                    enabled         true;
-
-                    viscousDissipationCoeffs
-                    {
-                        fields          (T);
-                        rho             rho; //rho Field
-                    }
-                }
-            }
-        }
-    }
-    \endverbatim
-
-    Where the entries comprise:
+    where:
     \table
-        Property     | Description             | Required    | Default value
-        type         | Type name: energyTransport | yes      |
-        field        | Name of the scalar field | no         | T
-        phi          | Name of flux field      | no          | phi
-        rho          | Name of density field   | no          | rho
-        nCorr        | Number of correctors    | no          | 0
-        tolerance    | Outer-loop initial-residual tolerance | no | 1
-        schemesField | Name of field to specify schemes | no | field name
-        fvOptions    | List of scalar sources  | no          |
-        Cp           | Heat capacity for single phase | no   | 0
-        rhoInf       | Density for single phase | no         | 0
-        kappa        | Thermal conductivity for single phase | no   | 0
-        Prt          | Turbulent Prandlt number | no         | 1.0
-        phaseThermos | Dictionary for multi-phase thermo |no | null
-        fvOptions    | Opotional extra sources | no          | null
+      Property  | Description                         | Type | Reqd | Deflt
+      type      | Type name: energyTransport          | word | yes  | -
+      libs      | Library name: solverFunctionObjects | word | yes  | -
+      field     | Name of the passive-scalar field    | word | no   | s
+      phi       | Name of flux field                  | word | no   | phi
+      rho       | Name of density field               | word | no   | rho
+      Cp        | Specific heat capacity at constant pressure | scalar | no | 0
+      kappa     | Thermal conductivity                | scalar | no | 0
+      rhoInf    | Fluid density                       | scalar | no | 0
+      Prt       | Turbulent Prandtl number            | scalar | no | 1
+      schemesField | Name of field to specify schemes | word   | no | field
+      tolerance | Outer-loop initial-residual tolerance | scalar | no | 1
+      nCorr     | Number of outer-loop correctors     | label  | no | 0
+      fvOptions | List of finite-volume options       | dict   | no | -
+      phaseThermos | Dictionary for multi-phase thermo | dict  | no | null
     \endtable
 
-See also
-    Foam::functionObjects::fvMeshFunctionObject
+    The inherited entries are elaborated in:
+      - \link fvMeshFunctionObject.H \endlink
+      - \link fvOption.H \endlink
+
+    An example of function object specification to solve a energy transport
+    equation for a single phase flow plus a source term:
+    \verbatim
+    energyTransport1
+    {
+        // Mandatory entries
+        type            energyTransport;
+        libs            (solverFunctionObjects);
+
+        // Optional entries
+        field           T;
+        phi             phi;
+        Cp              Cp    [J/kg/K]  1e3;
+        kappa           kappa [W/m/K]   0.0257;
+        rhoInf          rho   [kg/m^3]  1.2;
+        fvOptions
+        {
+            viscousDissipation
+            {
+                type            viscousDissipation;
+                enabled         true;
+
+                viscousDissipationCoeffs
+                {
+                    fields          (T);
+                    rhoInf          $....rhoInf;
+                }
+            }
+        }
+
+        // Inherited entries
+        enabled         true;
+        writeControl    writeTime;
+        writeInterval   1;
+    }
+    \endverbatim
+
+    An example of function object specification to solve a energy transport
+    equation for a multiphase phase flow plus a source term:
+    \verbatim
+    energyTransport1
+    {
+        // Mandatory entries
+        type            energyTransport;
+        libs            (solverFunctionObjects);
+
+        // Optional entries
+        field           T;
+        rho             rho;
+        phi             rhoPhi;
+
+        // Thermal properties of the phases
+        phaseThermos
+        {
+            alpha.air
+            {
+                Cp          1e3;
+                kappa       0.0243;
+            }
+            alpha.mercury
+            {
+                Cp          140;
+                kappa       8.2;
+            }
+            alpha.oil
+            {
+                Cp          2e3;
+                kappa       0.2;
+            }
+            alpha.water
+            {
+                Cp          4e3;
+                kappa       0.6;
+            }
+        }
+
+        fvOptions
+        {
+            viscousDissipation
+            {
+                type            viscousDissipation;
+                enabled         true;
+
+                viscousDissipationCoeffs
+                {
+                    fields          (T);
+                    rho             rho;
+                }
+            }
+        }
+
+        // Inherited entries
+        enabled         true;
+        writeControl    writeTime;
+        writeInterval   1;
+    }
+    \endverbatim
+
+Note
+  - The field name must be temperature and its boundary conditions
+    specified in the time directory.
+  - The turbulence model should be incompressible.
 
 SourceFiles
     energyTransport.C
diff --git a/src/functionObjects/solvers/scalarTransport/scalarTransport.H b/src/functionObjects/solvers/scalarTransport/scalarTransport.H
index 5097ba5f93..61cea62fa5 100644
--- a/src/functionObjects/solvers/scalarTransport/scalarTransport.H
+++ b/src/functionObjects/solvers/scalarTransport/scalarTransport.H
@@ -31,112 +31,134 @@ Group
     grpSolversFunctionObjects
 
 Description
-    Evolves a passive scalar transport equation.
+    Computes the transport equation for a passive scalar in single-phase or
+    two-phase flow, considering both incompressible and compressible cases:
 
-    - To specify the field name set the \c field entry
-    - To employ the same numerical schemes as another field set
-      the \c schemesField entry,
-    - The diffusivity can be set manually using the 'D' entry, retrieved
-      from the turbulence model or specified nut
-    - Alternatively if a turbulence model is available a turbulent diffusivity
-      may be constructed from the laminar and turbulent viscosities using the
-      optional diffusivity coefficients \c alphaD and \c alphaDt (which default
-      to 1):
-      \verbatim
-          D = alphaD*nu + alphaDt*nut
-      \endverbatim
-    - To specify a transport quantity within a phase enter phase.
-    - bounded01 bounds the transported scalar within 0 and 1.
+    \f[
+        \frac{\partial \rho \, T}{\partial t}
+      + \nabla \cdot \left( \phi_\alpha \, T \right)
+      - \nabla \cdot (D_T \, \nabla T)
+      = \alpha \, S_T
+    \f]
+
+    where:
+    \vartable
+      T       | Passive scalar field
+      \rho    | (Generic) Fluid density which is unity when not specified
+      \phi_\alpha | (Generic) Flux field
+      \alpha  | Phase fraction which is unity for single-phase flows
+      D_T     | Diffusivity representing the diffusive transport of T
+      S_T     | Passive-scalar field source term
+    \endvartable
 
 Usage
-    Example of function object specification to solve a scalar transport
-    equation:
+    Minimal example in \c system/controlDict.functions:
     \verbatim
-    functions
+    scalarTransport1
     {
-        scalar1
-        {
-            type            scalarTransport;
-            libs            (solverFunctionObjects);
+        // Mandatory entries
+        type            scalarTransport;
+        libs            (solverFunctionObjects);
 
-            resetOnStartUp  no;
-            region          cabin;
-            field           H2O;
+        // Optional entries
+        field           <word>;
+        phi             <word>;
+        rho             <word>;
+        nut             <word>;
+        phase           <word>;
+        phasePhiCompressed  <word>;
+        schemesField    <word>;
+        bounded01       <bool>;
+        D               <scalar>;
+        alphaD          <scalar>;
+        alphaDt         <scalar>;
+        tolerance       <scalar>;
+        nCorr           <label>;
+        resetOnStartUp  <bool>;
+        fvOptions       <dict>;
 
-
-            fvOptions
-            {
-                ...
-            }
-        }
+        // Inherited entries
+        ...
     }
-    \endverbatim
 
-    Example of function object specification to solve a residence time
-    in a two phase flow:
-    equation:
-    \verbatim
-    functions
-    {
-        sTransport
-        {
-            type            scalarTransport;
-            libs            (solverFunctionObjects);
-
-            enabled         true;
-            writeControl    writeTime;
-            writeInterval   1;
-
-            field           s;
-            bounded01       false;
-            phase           alpha.water;
-            tolerance       1e-5;
-
-            write           true;
-
-            fvOptions
-            {
-                unitySource
-                {
-                    type            scalarSemiImplicitSource;
-                    enabled         true;
-
-                    selectionMode   all;
-                    volumeMode      specific;
-
-                    sources
-                    {
-                        s           (1 0);
-                    }
-                }
-            }
-
-            resetOnStartUp  false;
-        }
-    }
-    \endverbatim
-
-    Where the entries comprise:
+    where:
     \table
-        Property     | Description             | Required    | Default value
-        type         | Type name: scalarTransport | yes      |
-        field        | Name of the scalar field | no         | s
-        phi          | Name of flux field      | no          | phi
-        rho          | Name of density field   | no          | rho
-        phase        | Name of the phase       | no          | none
-        tolerance    | Outer-loop initial-residual tolerance | no | 1
-        nut          | Name of the turbulence viscosity | no | none
-        D            | Diffusion coefficient   | no          | auto generated
-        nCorr        | Number of correctors    | no          | 0
-        resetOnStartUp | Reset scalar to zero on start-up | no | no
-        schemesField | Name of field to specify schemes | no | field name
-        fvOptions    | List of scalar sources  | no          |
-        bounded01    | Bounds scalar between 0-1 for multiphase | no | true
-        phasePhiCompressed | Compressed flux for VOF | no | alphaPhiUn
+      Property  | Description                         | Type | Reqd | Deflt
+      type      | Type name: scalarTransport          | word | yes  | -
+      libs      | Library name: solverFunctionObjects | word | yes  | -
+      field     | Name of the passive-scalar field    | word | no   | s
+      phi       | Name of flux field                  | word | no   | phi
+      rho       | Name of density field               | word | no   | rho
+      nut       | Name of the turbulence viscosity    | word | no   | none
+      phase     | Name of the phase                   | word | no   | none
+      phasePhiCompressed | Name of compressed VOF flux | word | no | alphaPhiUn
+      schemesField | Name of field to specify schemes | word  | no | field
+      bounded01 | Bounds scalar between 0-1 for multiphase  | bool | no | true
+      D         | Diffusion coefficient               | scalar | no | -
+      alphaD    | Laminar diffusivity coefficient     | scalar | no | 1
+      alphaDt   | Turbulent diffusivity coefficient   | scalar | no | 1
+      tolerance | Outer-loop initial-residual tolerance | scalar | no | 1
+      nCorr     | Number of outer-loop correctors     | label  | no | 0
+      resetOnStartUp | Flag to reset field to zero on start-up | bool | no | no
+      fvOptions | List of finite-volume options       | dict   | no | -
     \endtable
 
-See also
-    Foam::functionObjects::fvMeshFunctionObject
+    The inherited entries are elaborated in:
+      - \link fvMeshFunctionObject.H \endlink
+      - \link fvOption.H \endlink
+
+    An example of function object specification to solve a residence time
+    in a two-phase flow:
+    \verbatim
+    scalarTransport1
+    {
+        // Mandatory entries
+        type            scalarTransport;
+        libs            (solverFunctionObjects);
+
+        // Optional entries
+        field           s;
+        bounded01       false;
+        phase           alpha.water;
+        tolerance       1e-5;
+        resetOnStartUp  false;
+        fvOptions
+        {
+            unitySource
+            {
+                type            scalarSemiImplicitSource;
+                enabled         true;
+
+                selectionMode   all;
+                volumeMode      specific;
+
+                sources
+                {
+                    s           (1 0);
+                }
+            }
+        }
+
+        // Inherited entries
+        enabled         true;
+        writeControl    writeTime;
+        writeInterval   1;
+    }
+    \endverbatim
+
+Note
+  - To use the same numerical schemes as another field,
+  set the \c schemesField entry.
+  - The diffusivity can be set manually using the \c D entry, obtained
+  from the turbulence model or specified as `nut`.
+  - Alternatively, if a turbulence model is available, turbulent diffusivity
+  can be constructed from the laminar and turbulent viscosities using the
+  optional diffusivity coefficients \c alphaD and \c alphaDt
+  (which default to 1):
+
+    \f[
+        D = \alpha_D \, \nu + \alpha_{Dt} \, \nu_t
+    \f]
 
 SourceFiles
     scalarTransport.C