BiLinearFormsIntegrators.hpp

Go to the documentation of this file.

/** \file BiLinearFormsIntegrators.hpp
  * \brief Bilinear forms integrators for finite element assembly
  * \ingroup mofem_form
  *
  * This file provides template aliases for bilinear form integrators used in finite
  * element assembly. Bilinear forms represent the system matrices (left-hand side) in
  * finite element formulations through the mathematical expression \f$(u, v)_\Omega\f$,
  * where \f$u\f$ and \f$v\f$ are trial and test functions respectively.
  *
  * The integrators encompass fundamental finite element operations:
  * - **Gradient operators**: \f$(v_{,i}, u_{,j})_\Omega\f$ for diffusion and elasticity
  * - **Mass matrices**: \f$(v, u)_\Omega\f$ for dynamic and parabolic problems
  * - **Mixed formulations**: Coupling different field types for constrained problems
  * - **Tensor operations**: Anisotropic material behavior with full tensor coupling
  * - **Hybridization**: Interface constraints for discontinuous Galerkin methods
  *
  * All template aliases reference concrete implementations in BiLinearFormsIntegratorsImpl.hpp,
  * providing a clean interface while maintaining computational efficiency. The operators
  * support various coordinate systems, field dimensions, and specializations for different
  * problem types in computational mechanics and multi-physics simulations.
 
  \todo Some operators could be optimized. To do that, we need to write tests
  and use Valgrind to profile code, checking cache misses. For example, some
  operators should have iteration first over columns, then rows for optimal
  memory access patterns. Since these operators are used in many problems,
  implementation efficiency is critical for overall performance.
 
*/
 
#ifndef __BILINEAR_FORMS_INTEGRATORS_HPP__
#define __BILINEAR_FORMS_INTEGRATORS_HPP__
 
namespace MoFEM {
 
/**
 * @brief Bilinear integrator form
 * @ingroup mofem_forms
 *
 * @tparam EleOp
 * @tparam A
 * @tparam I
 */
template <typename EleOp>
template <AssemblyType A>
template <IntegrationType I>
struct FormsIntegrators<EleOp>::Assembly<A>::BiLinearForm {
 
  /**
   * @brief Gradient-gradient bilinear form: \f$(v_{,i},\beta(\mathbf{x}) u_{,j})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates the product of test function gradients with trial 
   * function gradients, scaled by a coefficient \f$\beta(\mathbf{x})\f$. This is 
   * fundamental for diffusion, heat conduction, and elasticity problems. Applications include:
   * - Laplacian operators in diffusion equations
   * - Stiffness matrices in structural mechanics
   * - Gradient-based regularization terms
   *
   * @note \f$\beta(\mathbf{x})\f$ is a spatially varying coefficient
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   * @tparam SPACE_DIM Spatial dimension of the problem
   */
  template <int BASE_DIM, int FIELD_DIM, int SPACE_DIM>
  using OpGradGrad = OpGradGradImpl<BASE_DIM, FIELD_DIM, SPACE_DIM, I, OpBase>;
 
  /**
   * @brief Mass matrix bilinear form: \f$(v_i,\beta(\mathbf{x}) u_j)_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates the product of test and trial functions, scaled by 
   * a coefficient \f$\beta(\mathbf{x})\f$. This forms the mass matrix in dynamic 
   * problems and identity-type operators in various formulations. Applications include:
   * - Mass matrices in dynamic finite element analysis
   * - Identity operators in parabolic equations
   * - Penalty terms and stabilization methods
   * - Time-dependent term discretization
   *
   * @note FIELD_DIM = 4 or 9 assumes OpMass is for tensorial field 2x2 or 3x3
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @todo Consider another template parameter RANK to distinguish between 
   *       scalar, vectorial and tensorial fields
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   */
  template <int BASE_DIM, int FIELD_DIM>
  using OpMass = OpMassImpl<BASE_DIM, FIELD_DIM, I, OpBase>;
 
  /**
   * @brief Cached mass matrix bilinear form (same as OpMass with caching)
   * @ingroup mofem_forms
   *
   * This is a cached version of OpMass that stores intermediate computations
   * to improve performance in repeated evaluations. Useful when the same
   * mass matrix structure is evaluated multiple times.
   *
   * @copydetails OpMass
   */
  template <int BASE_DIM, int FIELD_DIM>
  using OpMassCache = OpMassCacheImpl<BASE_DIM, FIELD_DIM, I, OpBase>;
 
  /**
   * @brief Symmetric tensor gradient bilinear form: \f$(v_k,D_{ijkl} u_{,l})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates test functions with trial function gradients through
   * a symmetric fourth-order tensor \f$D_{ijkl}\f$ with minor and major symmetry.
   * Essential for anisotropic diffusion and linear elasticity. Applications include:
   * - Elasticity stiffness matrices with material symmetry
   * - Anisotropic diffusion operators
   * - Constitutive relations in continuum mechanics
   * - Stress-strain coupling in solid mechanics
   *
   * @note \f$D_{ijkl}\f$ is a tensor with minor & major symmetry
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   * @tparam SPACE_DIM Spatial dimension of the problem
   * @tparam S Additional parameter for specialization (default: 0)
   */
  template <int BASE_DIM, int FIELD_DIM, int SPACE_DIM, int S = 0>
  using OpGradSymTensorGrad =
      OpGradSymTensorGradImpl<BASE_DIM, FIELD_DIM, SPACE_DIM, S, I, OpBase>;
 
  /**
   * @brief Second-order gradient symmetric tensor bilinear form: \f$(v_{,ij},D_{ijkl} u_{,kl})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates second-order gradients (Hessians) of test and trial
   * functions through a symmetric fourth-order tensor \f$D_{ijkl}\f$. Used in
   * higher-order partial differential equations and plate/shell theories. Applications include:
   * - Biharmonic operators in plate bending problems
   * - Fourth-order diffusion equations
   * - Higher-order regularization in optimization
   * - Gradient damage models in mechanics
   *
   * @note \f$D_{ijkl}\f$ is a tensor with no symmetries
   * @note Requires C1 continuous finite elements
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   * @tparam SPACE_DIM Spatial dimension of the problem
   * @tparam S Additional parameter for specialization (default: 0)
   */
  template <int BASE_DIM, int FIELD_DIM, int SPACE_DIM, int S = 0>
  using OpGradGradSymTensorGradGrad =
      OpGradGradSymTensorGradGradImpl<BASE_DIM, FIELD_DIM, SPACE_DIM, S, I,
                                      OpBase>;
 
  /**
   * @brief General tensor gradient bilinear form: \f$(v_{,j},D_{ijkl} u_{,l})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates test function gradients with trial function gradients
   * through a general fourth-order tensor \f$D_{ijkl}\f$ with no symmetry assumptions.
   * This is the most general form for anisotropic material behavior. Applications include:
   * - General anisotropic elasticity without symmetry
   * - Non-symmetric material tensors in advanced materials
   * - Coupled multi-physics problems with complex constitutive relations
   * - Plasticity with kinematic hardening
   *
   * @note \f$D_{ijkl}\f$ is a tensor with no symmetries
   * @note More computationally expensive than symmetric versions
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   * @tparam SPACE_DIM Spatial dimension of the problem
   * @tparam S Additional parameter for specialization (default: 0)
   */
  template <int BASE_DIM, int FIELD_DIM, int SPACE_DIM, int S = 0>
  using OpGradTensorGrad =
      OpGradTensorGradImpl<BASE_DIM, FIELD_DIM, SPACE_DIM, S, I, OpBase>;
 
  /**
   * @brief Mixed divergence-scalar bilinear form: \f$(\lambda_{i,i},u)_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates the divergence of vector test functions with scalar
   * trial functions. Essential for mixed formulations enforcing divergence constraints
   * such as incompressibility. Applications include:
   * - Pressure-velocity coupling in incompressible flow
   * - Mixed formulations for Darcy flow
   * - Constraint enforcement in optimization problems
   * - Divergence-free condition implementation
   *
   * @note \f$\lambda_{i,i}\f$ is the divergence of vector test function
   * @note \f$u\f$ is a scalar trial function
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam SPACE_DIM Spatial dimension of the problem
   */
  template <int SPACE_DIM>
  using OpMixDivTimesScalar = OpMixDivTimesScalarImpl<SPACE_DIM, I, OpBase>;
 
  /**
   * @brief Mixed tensor divergence-vector bilinear form: \f$(\lambda_{ij,j},u_{i})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates the divergence of tensor test functions with vector
   * trial functions. Used in mixed formulations with stress-displacement coupling
   * and equilibrium enforcement. Applications include:
   * - Stress-displacement mixed formulations in elasticity
   * - Mixed finite element methods for mechanics
   * - Equilibrium constraint enforcement
   * - Multi-physics coupling with tensor fields
   *
   * @note \f$\lambda_{ij,j}\f$ is the divergence of tensor test function
   * @note \f$u_i\f$ is a vector trial function
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam SPACE_DIM Spatial dimension of the problem
   * @tparam CoordSys Coordinate system type (default: CARTESIAN)
   */
  template <int SPACE_DIM, CoordinateTypes CoordSys = CARTESIAN>
  using OpMixDivTimesVec = OpMixDivTimesVecImpl<SPACE_DIM, I, OpBase, CoordSys>;
 
  /**
   * @brief Mixed scalar-divergence bilinear form: \f$(\lambda,u_{i,i})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates scalar test functions with the divergence of vector
   * trial functions. This is the transpose of OpMixDivTimesScalar and enforces
   * the same constraints but with different test/trial function roles. Applications include:
   * - Symmetric mixed formulations
   * - Lagrange multiplier methods for divergence constraints
   * - Saddle point problems in fluid mechanics
   * - Mixed Poisson formulations
   *
   * @note \f$\lambda\f$ is a scalar test function
   * @note \f$u_{i,i}\f$ is the divergence of vector trial function
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam SPACE_DIM Spatial dimension of the problem
   * @tparam COORDINATE_SYSTEM Coordinate system type (default: CARTESIAN)
   */
  template <int SPACE_DIM, CoordinateTypes COORDINATE_SYSTEM = CARTESIAN>
  using OpMixScalarTimesDiv =
      OpMixScalarTimesDivImpl<SPACE_DIM, I, OpBase, COORDINATE_SYSTEM>;
 
  /**
   * @brief Mixed vector-gradient bilinear form: \f$(\lambda_{i},u_{,j})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates vector test functions with the gradient of trial
   * functions. Used in mixed formulations where vector fields couple with
   * gradient terms. Applications include:
   * - Mixed formulations with vector Lagrange multipliers
   * - Gradient constraint enforcement
   * - Vector-scalar coupling in multi-physics problems
   * - Stabilization terms in finite element methods
   *
   * @note \f$\lambda_i\f$ is a vector test function
   * @note \f$u_{,j}\f$ is the gradient of trial function
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam BASE_DIM Dimension of the basis functions (1D, 2D, 3D)
   * @tparam FIELD_DIM Dimension of the field
   * @tparam SPACE_DIM Spatial dimension of the problem
   */
  template <int BASE_DIM, int FIELD_DIM, int SPACE_DIM>
  using OpMixVectorTimesGrad =
      OpMixVectorTimesGradImpl<BASE_DIM, FIELD_DIM, SPACE_DIM, I, OpBase>;
 
  /**
   * @brief Mixed tensor-gradient bilinear form: \f$(\lambda_{ij},u_{i,j})_\Omega\f$
   * @ingroup mofem_forms
   *
   * This operator integrates tensor test functions with the gradient of vector
   * trial functions. Essential for mixed formulations in solid mechanics where
   * stress tensors couple with displacement gradients. Applications include:
   * - Stress-strain mixed formulations
   * - Mixed finite element methods in elasticity
   * - Constitutive relation enforcement
   * - Coupled stress-displacement problems
   *
   * @note \f$\lambda_{ij}\f$ is a tensor test function
   * @note \f$u_{i,j}\f$ is the gradient of vector trial function
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam SPACE_DIM Spatial dimension of the problem
   */
  template <int SPACE_DIM>
  using OpMixTensorTimesGrad = OpMixTensorTimesGradImpl<SPACE_DIM, I, OpBase>;
 
  /**
   * @brief Hybridization constraint bilinear form for broken spaces
   * @ingroup mofem_forms
   *
   * This operator assembles constraint matrices during hybridization of broken
   * finite element spaces. Hybridization introduces Lagrange multipliers on
   * element interfaces to enforce continuity in discontinuous Galerkin methods.
   * The operator handles the coupling between interior element solutions and
   * interface unknowns. Applications include:
   * - Discontinuous Galerkin (DG) methods
   * - Hybridizable discontinuous Galerkin (HDG) methods
   * - Mixed finite element methods with broken spaces
   * - Static condensation procedures
   *
   * @note Used specifically for broken space hybridization procedures
   * @note Handles interface coupling in DG methods
   * @note Implementation details are in BiLinearFormsIntegratorsImpl.hpp
   *
   * @tparam FIELD_DIM Dimension of the field
   */
  template <int FIELD_DIM>
  using OpBrokenSpaceConstrain =
      OpBrokenSpaceConstrainImpl<FIELD_DIM, I, OpBrokenBase>;
};
 
} // namespace MoFEM
 
#endif //__BILINEAR_FORMS_INTEGRATORS_HPP__