[doc] Improve doc of effective diffusion coeffs

doc/doxygen/groups/material.md

@@ -54,6 +54,27 @@ chemical species or a _fixed_ mixture of species. Fluid systems use components t
 @defgroup EffectiveDiffusivity Effective diffusivity in porous media
 @brief Laws for calculating effective diffusion coefficients.
 @details When averaging over a given volume of a porous medium, diffusion appears effectively restricted since not all volume is accessible to particles and diffusion is hindered by the solid matrix acting as obstacles. Effective diffusivity laws provide constitutive relations for the effective diffusion coefficients based on the solid matrix material parameters and the fluid configuration in the pore space.
+
+The effective diffusion coefficient of component $ \kappa $
+in phase $ \alpha $ can be modeled as
+\begin{equation}
+D^\kappa_{\text{eff},\alpha} = \phi S_\alpha \tau D^\kappa_\alpha,
+\end{equation}
+where
+$ \phi $ is the porosity (volume fraction of the pore space),
+$ S_\alpha $ is the saturation of phase $ \alpha $ (the volume
+fraction of phase $ \alpha $ being $ n_\alpha = \phi S_\alpha $),
+$ D^\kappa_\alpha $ denotes the binary diffusion coefficient of
+component $ \kappa $ in phase $ \alpha $, and $ \tau $
+is the tortuosity coefficient.
+
+Bear \cite bear1972 reports values of $\tau$ in the range of 0.4 to 0.8.
+Note that in some literature the tortuosity $ \lambda $ is used instead
+of the tortuosity coefficient $\tau$. The two
+quantities are related by $ \lambda = \sqrt{1/\tau} $.
+
+The following laws are implemented:
+
 @ingroup Fluidmatrixinteractions
 
 @defgroup EffectiveHeatConductivity Effective heat conductivity in porous media

dumux/material/fluidmatrixinteractions/diffusivityconstanttortuosity.hh

@@ -13,41 +13,37 @@ namespace Dumux {
 
 /*!
 * \addtogroup EffectiveDiffusivity
-* \copydoc Dumux::DiffusivityConstantTortuosity
+* \copydetails Dumux::DiffusivityConstantTortuosity
 */
 
 /*!
  * \ingroup EffectiveDiffusivity
- * \brief Relation for the saturation-dependent effective diffusion coefficient
+ * \brief Relation for the effective diffusion coefficient with constant tortuosity
  *
  * ### Constant Tortuosity
  *
- * The material law is:
- * \f[
- *  D_\text{eff,pm} = \phi * S_w * \tau * D
- * \f]
- *
- * with
- * \f[
- * \tau = \text{const}
- * \f]
- *
- * The default value is 0.5, empirically obtained in Carman 1937:
- * <i>Fluid flow through granular beds</i> \cite carman1937
- * Additionally, Bear 1972 \cite bear1972 mentions values 0.4 and in the
- * range of 0.56 to 0.8.
+ * For `DiffusivityConstantTortuosity`, \f$ \tau = \text{const.} \f$,
+ * with default value 0.5, empirically obtained by Carman \cite carman1937.
+ * The value can be changed at runtime by setting parameter
+ * `"SpatialParams.Tortuosity"`. This will change the value of \f$ \tau \f$,
+ * and therefore the effective diffusion coefficient wherever
+ * the function `effectiveDiffusionCoefficient` is used.
  */
 template<class Scalar>
 class DiffusivityConstantTortuosity
 {
 public:
     /*!
-     * \brief Returns the effective diffusion coefficient \f$\mathrm{[m^2/s]}\f$ based
-     *        on a constant tortuosity value
-     * \param volVars The Volume Variables
-     * \param phaseIdx the index of the phase
-     * \param compIdxI the component index i
-     * \param compIdxJ the component index j
+     * \brief Returns the effective diffusion coefficient (\f$\mathrm{m^2/s}\f$)
+     *
+     * Returns the effective diffusion coefficient (\f$\mathrm{m^2/s}\f$)
+     * of component \f$ \kappa \f$ (index `compIdxI`) in phase \f$ \alpha \f$ based
+     * on a constant tortuosity coefficient: \f$ D^\kappa_{\text{eff},\alpha} = \phi S_\alpha \tau D^\kappa_\alpha \f$.
+     *
+     * \param volVars The volume variables
+     * \param phaseIdx the index of phase \f$ \alpha \f$
+     * \param compIdxI the component index i (the component diffusing in phase \f$ \alpha \f$)
+     * \param compIdxJ the component index j (the main component of phase \f$ \alpha \f$)
      */
     template<class VolumeVariables>
     static Scalar effectiveDiffusionCoefficient(const VolumeVariables& volVars,

dumux/material/fluidmatrixinteractions/diffusivitymillingtonquirk.hh

@@ -14,34 +14,34 @@ namespace Dumux {
 
 /*!
 * \addtogroup EffectiveDiffusivity
-* \copydoc Dumux::DiffusivityMillingtonQuirk
+* \copydetails Dumux::DiffusivityMillingtonQuirk
 */
 
 /*!
  * \ingroup EffectiveDiffusivity
- * \brief Relation for the saturation-dependent effective diffusion coefficient
+ * \brief Relation for the effective diffusion coefficient after Millington and Quirk
  *
  * ### Millington Quirk
- * The material law is:
- * \f[
- *  D_\text{eff,pm} = \phi * S_w * \tau * D
- * \f]
  *
- * with
+ * For `DiffusivityMillingtonQuirk`,
+ * the tortuosity coefficient is estimated after Millington and Quirk (1961) \cite millington1961
+ * by
  * \f[
- *  \tau = \frac{1}{\phi^2} * \left(\phi S_w\right)^{7/3}
+ *  \tau = \frac{1}{\phi^2} \left(\phi S_\alpha\right)^{7/3}.
  * \f]
  *
- * after Millington and Quirk 1961: <i>Permeability of porous solids</i> \cite millington1961
- * and Helmig 1997: <i>Multiphase Flow and Transport Processes in the Subsurface: A Contribution
- * to the Modeling of Hydrosystems</i>, page 129 \cite helmig1997
+ * See also Helmig (1997) \cite helmig1997 [page 129].
  */
 template<class Scalar>
 class DiffusivityMillingtonQuirk
 {
 public:
     /*!
-     * \brief Returns the effective diffusion coefficient \f$\mathrm{[m^2/s]}\f$ after Millington Quirk.
+     * \brief Returns the effective diffusion coefficient (\f$\mathrm{m^2/s}\f$)
+     *
+     * Returns the effective diffusion coefficient (\f$\mathrm{m^2/s}\f$)
+     * of component \f$ \kappa \f$ (index `compIdxI`) in phase \f$ \alpha \f$ computed as
+     * \f$ D^\kappa_{\text{eff},\alpha} = \phi S_\alpha \tau D^\kappa_\alpha \f$.
      *
      * \param volVars The Volume Variables
      * \param phaseIdx the index of the phase
@@ -54,10 +54,8 @@ public:
                                                 const int compIdxI,
                                                 const int compIdxJ)
     {
-        // instead of D_eff,pm = phi * Sw * 1/phi^2 * (phi * Sw)^(7/3) * D
-        // we calculate the more efficient
-        // D_eff,pm = phi * Sw^3 * cubicroot(phi * Sw) * D
-
+        // instead of D_eff = phi S tau D = phi S 1/phi^2 (phi S)^(7/3) D
+        // we implement more efficiently D_eff = phi S^3 cubicroot(phi S) D
         using std::cbrt;
         using std::max;
         const Scalar diffCoeff = volVars.diffusionCoefficient(phaseIdx, compIdxI, compIdxJ);
@@ -65,7 +63,8 @@ public:
         const Scalar sat = max<Scalar>(volVars.saturation(phaseIdx), 0.0);
         return porosity * (sat*sat*sat) * cbrt(porosity * sat) * diffCoeff;
     }
-
 };
-}
+
+} // end namespace Dumux
+
 #endif