Document heat transfer kernels. Refs idaholab#29645

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`
+left hand side represents the strong forms of other kernels which may be present in the equation. The `BodyForce`
 weak form, in inner-product notation, is defined as
 
 \begin{equation}
@@ -32,7 +34,7 @@ through the input parameters `value`, `function`, and `postprocessor`
 respectively. 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:

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

@@ -2,9 +2,20 @@
 
 !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.
-See [CoupledConvectiveHeatFluxBC](CoupledConvectiveHeatFluxBC.md) for a similar boundary condition coupled to variables.
+## 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_{inf}$ are taken as material properties.
+See [CoupledConvectiveHeatFluxBC](CoupledConvectiveHeatFluxBC.md) for a similar boundary condition coupled to variables and [ConvectionHeatTransferBC](ConvectionHeatTransferBC.md) for a similar condition for functions.
+
+## Example Input File Syntax
 
 !listing /convective_heat_flux/equilibrium.i block=BCs/right
 

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

@@ -2,14 +2,19 @@
 
 ## 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.
+
+For this object, the diffusion coefficient can either be an `ADMaterial` or traditional `Material`, though the Jacobian will be perfect if using an `ADMaterial`.
+
+## Example Input File Syntax
+
+The case demonstrates the use of `ADHeatConduction` where the
+diffusion coefficient (thermal conductivity) is defined by an [ADGenericConstantMaterial](ADGenericConstantMaterial.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,19 @@
 
 ## 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.
+
+For this object, the diffusion coefficient can either be an `ADMaterial` or traditional `Material`, though the Jacobian will be perfect if using an `ADMaterial`.
+
+## Example Input File Syntax
+
+The case demonstrates the use of `ADHeatConductionTimeDerivative` where the
+diffusion coefficient (thermal conductivity) is defined by an [ADGenericConstantMaterial](ADGenericConstantMaterial.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,40 @@
-!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, `thermal_conductivity`.
+The Jacobian does not account for partial derivatives of $\mathbf{k}$ with
+respect to the system unknowns (e.g., temperature).
+
+## Example Input File Syntax
+
+The case below demonstrates the use of `AnisoHeatConduction` where the diffusion
+coefficient (thermal conductivity) is defined by an `AnisoHeatConductionMaterial`.
+
+!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
+`diffusion_coefficient` parameter is used to define the material property name
+which contains the diffusion coefficient (which defaults to `thermal_conductivity`).
+The Jacobian will account for partial derivatives of the diffusion coefficient
+with respect to the unknown variable if the `diffusion_coefficient_dT` property
+name is provided. These particular names are the defaults because they
+are the names used by [HeatConductionMaterial](HeatConductionMaterial.md),
+though you can also define these materials using other [Material](Material.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,48 @@
 # 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. \eqref{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 `density_name` and `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 `density_name_dT` and `specific_heat_dT` property
+names are also provided.
 
 See also [/HeatCapacityConductionTimeDerivative.md] and [/SpecificHeatConductionTimeDerivative.md].
 
+## Example Input File Syntax
+
+The case below instead 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 and its temperature derivative.
+
+!listing modules/heat_transfer/test/tests/transient_heat/transient_heat_derivatives.i
+  start=Kernels
+  end=Executioner
+  remove=BCs;Functions
+
 !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

@@ -16,8 +16,7 @@ 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)$.");
+      "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,14 @@ InputParameters
 HeatConductionKernel::validParams()
 {
   InputParameters params = Diffusion::validParams();
-  params.addClassDescription(
-      "Computes residual/Jacobian contribution for $(k \\nabla T, \\nabla \\psi)$ term.");
+  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 diffusivity");
+      "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

@@ -17,14 +17,14 @@ 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$.");
+      "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 "