update thermal diffusion doc

Docs/source/diffusion.rst

@@ -4,7 +4,7 @@
 Thermal Diffusion
 *****************
 
-Castro incorporates explicit thermal diffusion into the energy equation.
+Castro incorporates explicit thermal diffusion into the energy equations.
 In terms of the specific internal energy, :math:`e`, this appears as:
 
 .. math:: \rho \frac{De}{Dt} + p \nabla \cdot \ub = \nabla \cdot \kth \nabla T
@@ -20,15 +20,82 @@ where :math:`\kth` is the thermal conductivity, with units
 
      USE_DIFFUSION=TRUE
 
-It is treated explicitly, by constructing the contribution to the evolution as a
-source term. This is time-centered to achieve second-order accuracy
+Thermal Diffusion related source codes are contained in the ``diffusion`` direction.
+Thermal Diffusion is treated explicitly, by constructing the contribution to the
+evolution as a source term. This is time-centered to achieve second-order accuracy
 in time.
 
+Overall Procedure
+=================
+
+Computing Thermal Conductivity
+------------------------------
+The main function that computes the diffusion term is ``getTempDiffusionTerm()``.
+Within ``getTempDiffusionTerm()``, it first calculates the cell centered
+thermal conductivity, :math:`\kth` contained in the variable ``coeff_cc``
+using the function ``fill_temp_cond()`` located in ``diffusion_util.cpp``.
+``fill_temp_cond()`` fills an ``eos_state()`` using the
+input conserved variables, which is used to calculate :math:`\kth` via
+``conductivity(eos_state)``. ``conductivity()`` routine is supplied via
+the ``Microphysics`` package. See :ref:`sec:conductivities` to see the
+specific choices of conductivity routines available.
+
+.. note::
+   The diffusion approximation breaks down at the surface of stars,
+   where the density rapidly drops and the mean free path becomes
+   large. In those instances, you should use the flux limited diffusion
+   module in Castro to evolve a radiation field.
+
+Now :math:`\kth` is reset to 0 unless
+:math:`\rho \gt \mathrm{castro::diffuse\_cutoff\_density}`.
+And if :math:`\rho \lt \mathrm{castro::diffuse\_cutoff\_density\_hi}`,
+a linear scaling of :math:`\kth` is done as:
+
+.. math::
+
+   \kth = \kth \cdot \frac{\rho - \mathtt{castro.diffuse\_cutoff\_density}}{\mathtt{castro.diffuse\_cutoff\_density\_hi} - \mathtt{castro.diffuse\_cutoff\_density}}
+
+Lastly, :math:`\kth` is scaled with ``castro::diffuse_cond_scale_fac``,
+a runtime parameter controlled by the user.
+
+After obtaining cell-centered :math:`\kth`, we do an average along
+i, j, and k depending on the direction to obtain face-centered MultiFabs.
+This is stored in ``coeffs``, a vector of MultiFabs, and the number of
+MultiFabs depends to ``AMREX_SPACEDIM``, since a :math:`\nabla` operator
+will be applied to it later.
+It has 1 ghost cells due to the nature of MLMG solvers.
+
+.. _sec:thermal_diffusion:
+
+Computing Thermal Diffusion
+---------------------------
+We are now ready to compute :math:`\nabla \cdot \kth \nabla T`
+after obtaining :math:`\kth`. This is done in the ``applyop_mlmg()`` function
+in ``Diffusion.cpp``. It defines ``mlabec`` an instance of class
+``MLABecLaplacian`` which is in the form of
+
+.. math::
+   (A\alpha - B\nabla \cdot \beta \nabla) \phi = f
+
+where A and B are constant scalars, and :math:`\alpha` and :math:`\beta`
+are scalar fields. In order to make it correctly represents our diffusion term,
+we set A = 0 and B = -1, which is done via ``mlabec.setScalars(0.0, -1.0)``.
+Now we recognize :math:`\beta = \kth`, which needs to be an array of MultiFab,
+corresponding to dimension. This is done via ``mlabec.setBCoeffs()``.
+
+One of the important flag that we need to pass in is to set ``setMetricTerm(true)``.
+This enables modifications due to curvilinear coordinates.
+
+Finally we create an instance of ``MLMG`` using ``mlabec``, and call
+``mlmg.apply()``, which simply evaluates the LHS but do not solve it.
+See more information in the amrex documentation:
+https://amrex-codes.github.io/amrex/docs_html/LinearSolvers.html
+
 
 Timestep Limiter
 ================
 
-Castro integrates diffusion explicitly in time—this means that
+Castro integrates diffusion explicitly in time;this means that
 there is a diffusion timestep limiter.
 
 To see the similarity to the thermal diffusion equation, consider the
@@ -59,27 +126,16 @@ The following parameter affects diffusion:
 
       castro.diffuse_temp = 1
       castro.do_hydro = 0
+* ``castro.diffuse_cond_scale_fac``: a linear scaling to :math:`\kth`. (default 0).
 
-.. index:: castro.diffusion_cutoff_density, castro.diffusion_cutoff_density_hi
-
-The diffusion approximation breaks down at the surface of stars,
-where the density rapidly drops and the mean free path becomes
-large. In those instances, you should use the flux limited diffusion
-module in Castro to evolve a radiation field. However, if your
-interest is only on the diffusion in the interior, you can use
-the parameters:
+* ``castro.diffuse_cutoff_density``: density under which :math:`\kth` is set to 0.
+  (Default: -1e200)
 
- * ``castro.diffuse_cutoff_density``
+* ``castro.diffuse_cutoff_density_hi``: density under which a linear scaling is
+  applied to :math:`\kth`, see section :ref:`sec:thermal_diffusion` for details.
+  (Default: -1e200)
 
- * ``castro.diffuse_cutoff_density_hi``
-
-to specify a density,
-below which, diffusion is not modeled. This is implemented in the
-code by linearly scaling the conductivity to zero between these limits, e.g.,
-
-.. math::
-
-   \kth = \kth \cdot \frac{\rho - \mathtt{castro.diffuse\_cutoff\_density}}{\mathtt{castro.diffuse\_cutoff\_density\_hi} - \mathtt{castro.diffuse\_cutoff\_density}}
+.. _sec:conductivities:
 
 Conductivities
 ==============