Kernels System

Optimized Kernel Objects

Depending on the residual calculation being performed it is sometimes possible to optimize the calculation of the residual by precomputing values during the finite element assembly of the residual vector. The following table details the various Kernel base classes that can be used for as base classes to improve performance.

Custom Kernel Creation

To create a custom kernel, you can follow the pattern of the Diffusion or ADDiffusion objects implemented and included in the MOOSE framework. Additionally, Example 2 in MOOSE provides a step-by-step overview of creating your own custom kernel. The following describes that calculation of the diffusion term of a PDE.

The strong-form of the diffusion equation is defined on a 3-D domain as: find such that

where is defined as the boundary on which the value of is fixed to a known constant , is defined as the boundary on which the flux across the boundary is fixed to a known constant , and is the boundary outward normal.

The weak form is generated by multiplying by a test function () and integrating over the domain (using inner-product notation):

and then integrating by parts which gives the weak form:

where is known as the trial function that defines the finite element discretization, , with being the basis functions.

The Jacobian, which is the derivative of Eq. (2) with respect to , is defined as:

As mentioned, the computeQpResidual method must be overridden for both flavors of kernels non-AD and AD. The computeQpResidual method for the non-AD version, Diffusion, is provided in Listing 1.

Real
Diffusion::computeQpResidual()
{
  return _grad_u[_qp] * _grad_test[_i][_qp];
}

This object also overrides the computeQpJacobian method to define Jacobian term of (moose/test/tests/test_harness/duplicate_outputs_analyzejacobian) as shown in Listing 2.

Real
Diffusion::computeQpJacobian()
{
  return _grad_phi[_j][_qp] * _grad_test[_i][_qp];
}

The AD version of this object, ADDiffusion, relies on an optimized kernel object (see Optimized Kernel Objects), as such it overrides precomputeQpResidual as follows.

ADDiffusion::precomputeQpResidual()
{
  return _grad_u[_qp];
}

Time Derivative Kernels

You can create a time-derivative term/kernel by subclassing TimeKernel instead of Kernel. For example, the residual contribution for a time derivative term is:

where is the finite element solution, and

because you can interchange the order of differentiation and summation.

In the equation above, is the time derivative of the th finite element coefficient of . While the exact form of this derivative depends on the time stepping scheme, without much loss of generality, we can assume the following form for the time derivative:

for some constants , which depend on and the timestepping method.

The derivative of equation Eq. (4) with respect to is then:

So that the Jacobian term for equation Eq. (4) is

where is what we call du_dot_du in MOOSE.

Therefore the computeQpResidual() function for our time-derivative term kernel looks like:

return _test[_i][_qp] * _u_dot[_qp];

And the corresponding computeQpJacobian() is:

return _test[_i][_qp] * _phi[_j][_qp] * _du_dot_du[_qp];

Coupling with Scalar Variables

If the weak form has contributions from scalar variables, then this contribution can be treated similarly as coupling from other spatial variables. See the Coupleable interface for how to obtain the variable values. Residual contributions are simply added to the computeQpResidual() function. Jacobian terms from the test spatial variable and incremental scalar variable are added by overriding the function computeQpOffDiagJacobianScalar().

Contributions to the scalar variable weak equation (test scalar variable terms) are not natively treated by the Kernel class. Inclusion of these residual and Jacobian contributions are discussed within ScalarKernels and specifically KernelScalarBase.

Further Kernel Documentation

Several specialized kernel types exist in MOOSE each with useful functionality. Details for each are in the sections below.

Available Objects

• Moose App
• ADBodyForceDemonstrates the multiple ways that scalar values can be introduced into kernels, e.g. (controllable) constants, functions, and postprocessors. Implements the weak form .
• ADCoefReactionImplements the residual term (p*u, test)
• ADConservativeAdvectionConservative form of which in its weak form is given by: .
• ADCoupledForceImplements a source term proportional to the value of a coupled variable. Weak form: .
• ADCoupledTimeDerivativeTime derivative Kernel that acts on a coupled variable. Weak form: .
• ADDiffusionSame as Diffusion in terms of physics/residual, but the Jacobian is computed using forward automatic differentiation
• ADMatCoupledForceKernel representing the contribution of the PDE term , where is a material property coefficient, is a coupled scalar field variable, and Jacobian derivatives are calculated using automatic differentiation.
• ADMatDiffusionDiffusion equation kernel that takes an isotropic diffusivity from a material property
• ADMatReactionKernel representing the contribution of the PDE term , where is a reaction rate material property, is a scalar variable (nonlinear or coupled), and whose Jacobian contribution is calculated using automatic differentiation.
• ADMaterialPropertyValueResidual term (u - prop) to set variable u equal to a given material property prop
• ADReactionImplements a simple consuming reaction term with weak form .
• ADScalarLMKernelThis class is used to enforce integral of phi = V_0 with a Lagrange multiplier approach.
• ADTimeDerivativeThe time derivative operator with the weak form of .
• ADVectorDiffusionThe Laplacian operator (), with the weak form of . The Jacobian is computed using automatic differentiation
• ADVectorTimeDerivativeThe time derivative operator with the weak form of .
• AnisotropicDiffusionAnisotropic diffusion kernel with weak form given by .
• ArrayBodyForceApplies body forces specified with functions to an array variable.
• ArrayDiffusionThe array Laplacian operator (), with the weak form of .
• ArrayReactionThe array reaction operator with the weak form of .
• ArrayTimeDerivativeArray time derivative operator with the weak form of .
• BodyForceDemonstrates the multiple ways that scalar values can be introduced into kernels, e.g. (controllable) constants, functions, and postprocessors. Implements the weak form .
• CoefReactionImplements the residual term (p*u, test)
• CoefTimeDerivativeThe time derivative operator with the weak form of .
• ConservativeAdvectionConservative form of which in its weak form is given by: .
• CoupledForceImplements a source term proportional to the value of a coupled variable. Weak form: .
• CoupledTimeDerivativeTime derivative Kernel that acts on a coupled variable. Weak form: .
• DiffusionThe Laplacian operator (), with the weak form of .
• FunctionDiffusionThe Laplacian operator with a function coefficient.
• MassEigenKernelAn eigenkernel with weak form where is the eigenvalue.
• MassLumpedTimeDerivativeLumped formulation of the time derivative . Its corresponding weak form is where denotes the time derivative of the solution coefficient associated with node .
• MatCoupledForceImplements a forcing term RHS of the form PDE = RHS, where RHS = Sum_j c_j * m_j * v_j. c_j, m_j, and v_j are provided as real coefficients, material properties, and coupled variables, respectively.
• MatDiffusionDiffusion equation Kernel that takes an isotropic Diffusivity from a material property
• MatReactionKernel to add -L*v, where L=reaction rate, v=variable
• MaterialDerivativeRankFourTestKernelClass used for testing derivatives of a rank four tensor material property.
• MaterialDerivativeRankTwoTestKernelClass used for testing derivatives of a rank two tensor material property.
• MaterialDerivativeTestKernelClass used for testing derivatives of a scalar material property.
• MaterialPropertyValueResidual term (u - prop) to set variable u equal to a given material property prop
• NullKernelKernel that sets a zero residual.
• ReactionImplements a simple consuming reaction term with weak form .
• ScalarLMKernelThis class is used to enforce integral of phi = V_0 with a Lagrange multiplier approach.
• ScalarLagrangeMultiplierThis class is used to enforce integral of phi = V_0 with a Lagrange multiplier approach.
• TimeDerivativeThe time derivative operator with the weak form of .
• UserForcingFunctionDemonstrates the multiple ways that scalar values can be introduced into kernels, e.g. (controllable) constants, functions, and postprocessors. Implements the weak form .
• VectorBodyForceDemonstrates the multiple ways that scalar values can be introduced into kernels, e.g. (controllable) constants, functions, and postprocessors. Implements the weak form .
• VectorCoupledTimeDerivativeTime derivative Kernel that acts on a coupled vector variable. Weak form: .
• VectorDiffusionThe Laplacian operator (), with the weak form of .
• VectorTimeDerivativeThe time derivative operator with the weak form of .
• Tensor Mechanics App
• ADDynamicStressDivergenceTensorsResidual due to stress related Rayleigh damping and HHT time integration terms
• ADGravityApply gravity. Value is in units of acceleration.
• ADInertialForceCalculates the residual for the inertial force () and the contribution of mass dependent Rayleigh damping and HHT time integration scheme ($\eta \cdot M \cdot ((1+\alpha)velq2-\alpha \cdot vel-old) $)
• ADInertialForceShellCalculates the residual for the inertial force/moment and the contribution of mass dependent Rayleigh damping and HHT time integration scheme.
• ADStressDivergenceRSphericalTensorsCalculate stress divergence for a spherically symmetric 1D problem in polar coordinates.
• ADStressDivergenceRZTensorsCalculate stress divergence for an axisymmetric problem in cylindrical coordinates.
• ADStressDivergenceShellQuasi-static stress divergence kernel for Shell element
• ADStressDivergenceTensorsStress divergence kernel with automatic differentiation for the Cartesian coordinate system
• ADSymmetricStressDivergenceTensorsStress divergence kernel with automatic differentiation for the Cartesian coordinate system
• ADWeakPlaneStressPlane stress kernel to provide out-of-plane strain contribution.
• AsymptoticExpansionHomogenizationKernelKernel for asymptotic expansion homogenization for elasticity
• CosseratStressDivergenceTensorsStress divergence kernel for the Cartesian coordinate system
• DynamicStressDivergenceTensorsResidual due to stress related Rayleigh damping and HHT time integration terms
• GeneralizedPlaneStrainOffDiagGeneralized Plane Strain kernel to provide contribution of the out-of-plane strain to other kernels
• GravityApply gravity. Value is in units of acceleration.
• HomogenizedTotalLagrangianStressDivergenceTotal Lagrangian stress equilibrium kernel with homogenization constraint Jacobian terms
• InertialForceCalculates the residual for the inertial force () and the contribution of mass dependent Rayleigh damping and HHT time integration scheme ($\eta \cdot M \cdot ((1+\alpha)velq2-\alpha \cdot vel-old) $)
• InertialForceBeamCalculates the residual for the inertial force/moment and the contribution of mass dependent Rayleigh damping and HHT time integration scheme.
• InertialTorqueKernel for inertial torque: density * displacement x acceleration
• MaterialVectorBodyForceApply a body force vector to the coupled displacement component.
• MomentBalancing
• OutOfPlanePressureApply pressure in the out-of-plane direction in 2D plane stress or generalized plane strain models
• PhaseFieldFractureMechanicsOffDiagStress divergence kernel for phase-field fracture: Computes off diagonal damage dependent Jacobian components. To be used with StressDivergenceTensors or DynamicStressDivergenceTensors.
• PlasticHeatEnergyPlastic heat energy density = coeff * stress * plastic_strain_rate
• PoroMechanicsCouplingAdds , where the subscript is the component.
• StressDivergenceBeamQuasi-static and dynamic stress divergence kernel for Beam element
• StressDivergenceRSphericalTensorsCalculate stress divergence for a spherically symmetric 1D problem in polar coordinates.
• StressDivergenceRZTensorsCalculate stress divergence for an axisymmetric problem in cylindrical coordinates.
• StressDivergenceTensorsStress divergence kernel for the Cartesian coordinate system
• StressDivergenceTensorsTrussKernel for truss element
• TotalLagrangianStressDivergenceEnforce equilibrium with a total Lagrangian formulation in Cartesian coordinates.
• TotalLagrangianStressDivergenceAxisymmetricCylindricalEnforce equilibrium with a total Lagrangian formulation in axisymmetric cylindrical coordinates.
• TotalLagrangianStressDivergenceCentrosymmetricSphericalEnforce equilibrium with a total Lagrangian formulation in centrosymmetric spherical coordinates.
• TotalLagrangianWeakPlaneStressPlane stress kernel to provide out-of-plane strain contribution.
• UpdatedLagrangianStressDivergenceEnforce equilibrium with an updated Lagrangian formulation in Cartesian coordinates.
• WeakPlaneStressPlane stress kernel to provide out-of-plane strain contribution.
• Chamois App
• GradientEnhancedMicropolarDamage2. order Helmholtz like PDE for describing nonlocal damage
• GradientEnhancedMicropolarKirchhoffMomentMoment of a gradient-enhanced rank two tensor Kirchhoff
• GradientEnhancedMicropolarPKIDivergenceDivergence of a gradient-enhanced rank two tensor PKI (stress, couple stress)
• GradientEnhancedStressDivergenceTensorsEnhanced StressDivergenceTensors kernel considering off diagonal jacobian terms due to gradient-enhanced stress effects.
• ImplicitGradientEnhancedDamageClassical 'Helmholtz'-like equation used for implicit gradient-enhanced damage or plasticity models