Merge pull request #29646 from aprilnovak/heat-transfer-docs

Document heat transfer kernels.

framework/doc/content/source/kernels/BodyForce.md

@@ -2,15 +2,17 @@
 
 ## Description
 
-`BodyForce` implements a force term in momentum transport or structural
-mechanics or a source term in species/mass transport. The strong form, given a
-domain $\Omega$ is defined as
+`BodyForce` implements a force term, such as a heat generation/sink term for heat
+conduction, a momentum source/sink for momentum transport or structural mechanics, or
+a source/sink term in species/mass transport. The context of this kernel depends
+on the differential equation of interest, but shares the strong form on a domain
+$\Omega$ as
 
 \begin{equation}
-\underbrace{-f}_{\textrm{BodyForce}} + \sum_{i=1}^n \beta_i = 0 \in \Omega
+\underbrace{-f}_{\textrm{BodyForce}} + \text{other kernels} = 0 \in \Omega
 \end{equation}
-where $f$ is the source term (negative if a sink) and the second term on the
-left hand side represents the strong forms of other kernels. The `BodyForce`
+where $f$ is the source term (negative if a sink) and "other kernels"
+represent the strong forms of other terms present in the equation. The `BodyForce`
 weak form, in inner-product notation, is defined as
 
 \begin{equation}
@@ -25,14 +27,13 @@ it is assumed that $f$ +is not+ a function of the unknown $u$.
 The force is constructed through a user supplied constant $c$,
 [function](/Functions/index.md) value evaluated at the current time and
 quadrature point $f$, and/or [postprocessor](/Postprocessors/index.md)
-value $p$. The constant $c$, supplied through the parameter `value`, may also be
+value $p$. The constant $c$ may also be
 controlled over the course of a transient simulation with a
-[`Controls`](/Controls/index.md) block.  $c$, $f$, $p$ are supplied
-through the input parameters `value`, `function`, and `postprocessor`
-respectively. Not supplying $c$, $f$, or $p$ through its corresponding
+[Controls](/Controls/index.md) block.
+Not supplying $c$, $f$, or $p$ through its corresponding
 parameter is equivalent to setting its value to unity.
 
-## Example Syntax
+## Example Input File Syntax
 
 The case below demonstrates the use of `BodyForce` where the force term is
 supplied based upon a function form:

framework/doc/content/source/materials/GenericConstantMaterial.md

@@ -1,4 +1,4 @@
-# GenericConstantMaterial
+# GenericConstantMaterial / ADGenericConstantMaterial
 
 !syntax description /Materials/GenericConstantMaterial
 

modules/heat_transfer/doc/content/source/bcs/ConvectiveHeatFluxBC.md

@@ -2,10 +2,21 @@
 
 !syntax description /BCs/ConvectiveHeatFluxBC
 
-This boundary condition computes convective heat flux $q'' = H \cdot (T - T_{inf})$, where $H$ is convective heat transfer coefficient,
-$T$ is the temperature, and $T_{inf}$ is far field temperature.  Both $H$ and $T_{inf}$ are coupled as material properties.
+## Description
+
+The `ConvectiveHeatFluxBC` boundary condition imposes a heat flux equal to
+
+\begin{equation}
+\vec{q}\cdot\hat{n}=h\left(T-T_\infty\right)
+\end{equation}
+
+where $\vec{q}\cdot\hat{n}$ is the heat flux normal to the boundary, $h$ is
+the convective heat transfer coefficient, and $T_\infty$ is the far-field temperature.
+Both $h$ and $T_\infty$ are taken as material properties.
 See [CoupledConvectiveHeatFluxBC](CoupledConvectiveHeatFluxBC.md) for a similar boundary condition coupled to variables.
 
+## Example Input File Syntax
+
 !listing /convective_heat_flux/equilibrium.i block=BCs/right
 
 !syntax parameters /BCs/ConvectiveHeatFluxBC

modules/heat_transfer/doc/content/source/kernels/ADHeatConduction.md

@@ -2,14 +2,17 @@
 
 ## Description
 
-`ADHeatConduction` is the implementation of the heat diffusion equation in [HeatConduction](/HeatConduction.md) within the framework of automatic differentiation.
-The `ADHeatConduction` kernel implements the heat equation given by Fourier's Law where The heat flux is given as
-\begin{equation}
-\mathbf{q} = - k\nabla T,
-\end{equation}
-where $k$ denotes the thermal conductivity of the material. $k$ can either be an `ADMaterial` or traditional `Material`.
-
-This class inherits from the [ADDiffusion](/ADDiffusion.md) class.
+`ADHeatConduction` is the implementation of [HeatConduction](/HeatConduction.md) within the framework of [!ac](AD). Please see the [HeatConduction](/HeatConduction.md) documentation for more information.
+
+## Example Input File Syntax
+
+The case demonstrates the use of `ADHeatConduction` where the
+diffusion coefficient (thermal conductivity) is defined by an [ADGenericConstantMaterial](GenericConstantMaterial.md).
+
+!listing modules/heat_transfer/test/tests/radiative_bcs/ad_radiative_bc_cyl.i
+  start=Kernels
+  end=Preconditioning
+  remove=BCs
 
 !syntax description /Kernels/ADHeatConduction
 

modules/heat_transfer/doc/content/source/kernels/ADHeatConductionTimeDerivative.md

@@ -2,22 +2,17 @@
 
 ## Description
 
-The `ADHeatConductionTimeDerivative` kernel implements a time derivative for the domain $\Omega$ given by
-
-\begin{equation}
-\underbrace{\rho c_p \frac{\partial u}{\partial t}}_{\textrm{ADHeatConductionTimeDerivative}} +
-\sum_{i=1}^n \beta_i = 0 \in \Omega.
-\end{equation}
-where $\rho$ is the material density, $c_p$ is the specific heat, and the second term on the left hand side corresponds to the strong forms of
-other kernels. The corresponding `ADHeatConductionTimeDerivative` weak form using inner-product notation is
-
-\begin{equation}
-R_i(u_h) = (\psi_i, \rho c_p\frac{\partial u_h}{\partial t}) \quad \forall \psi_i,
-\end{equation}
-where $u_h$ is the approximate solution and $\psi_i$ is a finite element test function.
-
-The Jacobian is given by automatic differentiation, and should be perfect as long as $c_p$ and $\rho$
-are provided using `ADMaterial` derived objects.
+`ADHeatConductionTimeDerivative` is the implementation of [HeatConductionTimeDerivative](/HeatConductionTimeDerivative.md) within the framework of [!ac](AD). Please see the [HeatConductionTimeDerivative](/HeatConductionTimeDerivative.md) documentation for more information.
+
+## Example Input File Syntax
+
+The case demonstrates the use of `ADHeatConductionTimeDerivative` where the
+properties are defined by an [ADGenericConstantMaterial](GenericConstantMaterial.md)
+
+!listing modules/heat_transfer/test/tests/verify_against_analytical/ad_1D_transient.i
+  start=Kernels
+  end=Materials
+  remove=BCs
 
 !syntax parameters /Kernels/ADHeatConductionTimeDerivative
 

modules/heat_transfer/doc/content/source/kernels/AnisoHeatConduction.md

@@ -1 +1,38 @@
-!template load file=stubs/moose_object.md.template name=AnisoHeatConduction syntax=/Kernels/AnisoHeatConduction
+# AnisoHeatConduction
+
+## Description
+
+`AnisoHeatConduction` implements the diffusion kernel in the thermal energy conservation equation, with an anisotropic material property for the thermal conductivity.
+The strong form is
+
+\begin{equation}
+\underbrace{-\nabla\cdot(\mathbf{k}\nabla T)}_{\textrm{AnisoHeatConduction}} + \text{other kernels} = 0 \in \Omega
+\end{equation}
+
+where $\mathbf{k}$ is a tensor thermal conductivity (nine components) and $T$ is
+temperature. The corresponding weak form,
+in inner-product notation, is
+
+\begin{equation}
+R_i(u_h)=(\nabla\psi_i, \mathbf{k}\nabla u_h)\quad\forall \psi_i,
+\end{equation}
+
+where $u_h$ is the approximate solution and $\psi_i$ is a finite element test function.
+
+The thermal conductivity is specified with a material property, [!param](/Kernels/AnisoHeatConduction/thermal_conductivity).
+
+## Example Input File Syntax
+
+The case below demonstrates the use of `AnisoHeatConduction` where the diffusion
+coefficient (thermal conductivity) is defined by an [AnisoHeatConductionMaterial](AnisoHeatConductionMaterial.md).
+
+!listing modules/heat_transfer/test/tests/heat_conduction_ortho/heat_conduction_ortho.i
+  start=Kernels
+  end=Executioner
+  remove=BCs
+
+!syntax parameters /Kernels/AnisoHeatConduction
+
+!syntax inputs /Kernels/AnisoHeatConduction
+
+!syntax children /Kernels/AnisoHeatConduction

modules/heat_transfer/doc/content/source/kernels/HeatConduction.md

@@ -1 +1,52 @@
-!template load file=stubs/moose_object.md.template name=HeatConduction syntax=/Kernels/HeatConduction
+# HeatConduction
+
+## Description
+
+`HeatConduction` implements the diffusion kernel in the thermal energy conservation equation, with a material property for the diffusion coefficient. The strong form is
+
+\begin{equation}
+\underbrace{-\nabla\cdot(k\nabla T)}_{\textrm{HeatConduction}} + \text{other kernels} = 0 \in \Omega
+\end{equation}
+
+where $k$ is the diffusion coefficient (thermal conductivity) and $T$ is
+the variable (temperature). The corresponding weak form,
+in inner-product notation, is
+
+\begin{equation}
+R_i(u_h)=(\nabla\psi_i, k\nabla u_h)\quad\forall \psi_i,
+\end{equation}
+
+where $u_h$ is the approximate solution and $\psi_i$ is a finite element test function.
+
+The diffusion coefficient is specified with a material property; the
+[!param](/Kernels/HeatConduction/diffusion_coefficient)
+parameter is used to define the material property name
+which contains the diffusion coefficient.
+The Jacobian will account for partial derivatives of the diffusion coefficient
+with respect to the unknown variable if the [!param](/Kernels/HeatConduction/diffusion_coefficient_dT) property
+name is provided. These particular defaults for these parameters
+are the names used by [HeatConductionMaterial](HeatConductionMaterial.md),
+though you can also define these materials using other [Material](Materials/index.md) objects.
+
+## Example Input File Syntax
+
+The case below demonstrates the use of `HeatConduction` where the diffusion
+coefficient (thermal conductivity) is defined by a `HeatConductionMaterial`.
+
+!listing modules/heat_transfer/tutorials/introduction/therm_step02.i
+  start=Kernels
+  end=BCs
+
+The case below instead demonstrates the use of `HeatConduction` where the
+diffusion coefficient (thermal conductivity) is defined by a [ParsedMaterial](ParsedMaterial.md)
+
+!listing modules/heat_transfer/test/tests/code_verification/spherical_test_no2.i
+  start=Kernels
+  end=Executioner
+  remove=BCs
+
+!syntax parameters /Kernels/HeatConduction
+
+!syntax inputs /Kernels/HeatConduction
+
+!syntax children /Kernels/HeatConduction

modules/heat_transfer/doc/content/source/kernels/HeatConductionTimeDerivative.md

@@ -1,13 +1,49 @@
 # HeatConductionTimeDerivative
 
-!syntax description /Kernels/HeatConductionTimeDerivative
+## Description
 
-!alert warning
-This Kernel will not generate the correct on-diagonal Jacobians for temperature dependent specific
-heat $c_p$ or density $\rho$, and this kernel does not contribute an off-diagonal Jacobian at all.
+`HeatConductionTimeDerivative` implements the time derivative term in the
+thermal energy conservation equation. The strong form is
+
+\begin{equation}
+\label{eq:hctd}
+\underbrace{\rho C_p\frac{\partial T}{\partial t}}_{\textrm{HeatConductionTimeDerivative}} + \text{other kernels} = 0 \in \Omega
+\end{equation}
+
+where $\rho$ is density, $C_p$ is the volumetric isobaric specific heat, and $T$ is
+temperature.
+
+!alert note
+This strong form does *not* assume that $\rho$ or $C_p$ are constant. Eq. [eq:hctd] is the rigorously-derived form which can be used for $\rho$ and $C_p$ which are not constant.
+
+The corresponding weak form using inner-product notation is
+
+\begin{equation}
+R_i(u_h) = (\psi_i, \rho c_p\frac{\partial u_h}{\partial t}) \quad \forall \psi_i,
+\end{equation}
+
+where $u_h$ is the approximate solution and $\psi_i$ is a finite element test function.
+
+The density and specific heat are specified with material properties,
+and the [!param](/Kernels/HeatConductionTimeDerivative/density_name) and
+[!param](/Kernels/HeatConductionTimeDerivative/specific_heat) parameters are used to define the material property
+name providing those properties.
+The Jacobian will account for partial derivatives of $\rho$ and $C_p$
+with respect to the unknown variable if the [!param](/Kernels/HeatConductionTimeDerivative/density_name_dT) and [!param](/Kernels/HeatConductionTimeDerivative/specific_heat_dT) property
+names are also provided.
 
 See also [/HeatCapacityConductionTimeDerivative.md] and [/SpecificHeatConductionTimeDerivative.md].
 
+## Example Input File Syntax
+
+The case below demonstrates the use of `HeatConductionTimeDerivative` where the
+density and specific heat are defined by a [HeatConductionMaterial](/HeatConductionMaterial.md) (for specific heat) and a [ParsedMaterial](ParsedMaterial.md) for density.
+
+!listing modules/heat_transfer/test/tests/transient_heat/transient_heat_derivatives.i
+  start=Kernels
+  end=Executioner
+  remove=BCs
+
 !syntax parameters /Kernels/HeatConductionTimeDerivative
 
 !syntax inputs /Kernels/HeatConductionTimeDerivative

modules/heat_transfer/doc/content/source/kernels/HeatSource.md

@@ -1 +1,31 @@
-!template load file=stubs/moose_object.md.template name=HeatSource syntax=/Kernels/HeatSource
+# HeatSource
+
+## Description
+
+The `HeatSource` kernel implements a volumetric heat source/sink forcing term. The strong form is
+
+\begin{equation}
+\underbrace{-\dot{q}}_{\textrm{HeatSource}} + \text{other kernels} = 0 \in \Omega
+\end{equation}
+
+where $\dot{q}$ is the volumetric heat source. The corresponding weak form,
+in inner-product notation, is
+
+\begin{equation}
+R_i(u_h)=(\psi_i, -\dot{q})\quad\forall \psi_i,
+\end{equation}
+
+where $u_h$ is the approximate solution and $\psi_i$ is a finite element test function.
+
+A slightly more general version of this same kernel can be found in [BodyForce](BodyForce.md), which you can equivalently use instead of `HeatSource`.
+
+## Example Input File Syntax
+
+!listing modules/heat_transfer/tutorials/introduction/therm_step03a.i
+  block=Kernels
+
+!syntax parameters /Kernels/HeatSource
+
+!syntax inputs /Kernels/HeatSource
+
+!syntax children /Kernels/HeatSource

modules/heat_transfer/src/kernels/AnisoHeatConduction.C

@@ -15,9 +15,8 @@ InputParameters
 AnisoHeatConduction::validParams()
 {
   InputParameters params = DerivativeMaterialInterface<Kernel>::validParams();
-  params.addClassDescription(
-      "Anisotropic HeatConduction kernel $\\nabla \\cdot -\\widetilde{k} \\nabla u$ "
-      "with weak form given by $(\\nabla \\psi_i, \\widetilde{k} \\nabla u)$.");
+  params.addClassDescription("Anisotropic diffusive heat conduction term $\\nabla \\cdot "
+                             "-\\mathbf{k} \\nabla T$ of the thermal energy conservation equation");
   params.addParam<MaterialPropertyName>(
       "thermal_conductivity",
       "thermal_conductivity",

modules/heat_transfer/src/kernels/HeatConduction.C

@@ -16,15 +16,16 @@ InputParameters
 HeatConductionKernel::validParams()
 {
   InputParameters params = Diffusion::validParams();
-  params.addClassDescription(
-      "Computes residual/Jacobian contribution for $(k \\nabla T, \\nabla \\psi)$ term.");
-  params.addParam<MaterialPropertyName>(
-      "diffusion_coefficient", "thermal_conductivity", "Property name of the diffusivity");
+  params.addClassDescription("Diffusive heat conduction term $-\\nabla\\cdot(k\\nabla T)$ of the "
+                             "thermal energy conservation equation");
+  params.addParam<MaterialPropertyName>("diffusion_coefficient",
+                                        "thermal_conductivity",
+                                        "Property name of the diffusion coefficient");
   params.addParam<MaterialPropertyName>(
       "diffusion_coefficient_dT",
       "thermal_conductivity_dT",
-      "Property name of the derivative of the diffusivity with respect "
-      "to the variable (Default: thermal_conductivity_dT)");
+      "Property name of the derivative of the diffusion coefficient with respect "
+      "to the variable");
   params.set<bool>("use_displaced_mesh") = true;
   return params;
 }

modules/heat_transfer/src/kernels/HeatConductionTimeDerivative.C

@@ -15,16 +15,17 @@ InputParameters
 HeatConductionTimeDerivative::validParams()
 {
   InputParameters params = TimeDerivative::validParams();
-  params.addClassDescription(
-      "Time derivative term $\\rho c_p \\frac{\\partial T}{\\partial t}$ of "
-      "the heat equation for quasi-constant specific heat $c_p$ and the density $\\rho$.");
+  params.addClassDescription("Time derivative term $\\rho c_p \\frac{\\partial T}{\\partial t}$ of "
+                             "the thermal energy conservation equation.");
 
   // Density may be changing with deformation, so we must integrate
   // over current volume by setting the use_displaced_mesh flag.
   params.set<bool>("use_displaced_mesh") = true;
 
   params.addParam<MaterialPropertyName>(
-      "specific_heat", "specific_heat", "Name of the specific heat material property");
+      "specific_heat",
+      "specific_heat",
+      "Name of the volumetric isobaric specific heat material property");
   params.addParam<MaterialPropertyName>(
       "specific_heat_dT",
       "Name of the material property for the derivative of the specific heat with respect "