{
  "name": "HexahedronFEMForceFieldAndMass",
  "main": {
    "name": "HexahedronFEMForceFieldAndMass",
    "namespace": "sofa::component::solidmechanics::fem::elastic",
    "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
    "include": "sofa/component/solidmechanics/fem/elastic/HexahedronFEMForceFieldAndMass.h",
    "doc": "Hexahedral finite elements with mass.\n\nCompute Finite Element forces based on hexahedral elements including continuum mass matrices",
    "inherits": [
      "HexahedronFEMForceField",
      "Mass"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_elementMasses",
        "type": "VecElementMass",
        "xmlname": "massMatrices",
        "help": "Mass matrices per element (M_i)"
      },
      {
        "name": "d_density",
        "type": "Real",
        "xmlname": "density",
        "help": "density == volumetric mass in english (kg.m-3)"
      },
      {
        "name": "d_lumpedMass",
        "type": "bool",
        "xmlname": "lumpedMass",
        "help": "Does it use lumped masses?"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reinit",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeElementMasses",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeElementMass",
        "return_type": "void",
        "params": [
          {
            "name": "Mass",
            "type": "ElementMass &"
          },
          {
            "name": "nodes",
            "type": "const int &"
          },
          {
            "name": "elementIndice",
            "type": "const int"
          },
          {
            "name": "stiffnessFactor",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "integrateMass",
        "return_type": "Real",
        "params": [
          {
            "name": "signx",
            "type": "int"
          },
          {
            "name": "signy",
            "type": "int"
          },
          {
            "name": "signz",
            "type": "int"
          },
          {
            "name": "l0",
            "type": "Real"
          },
          {
            "name": "l1",
            "type": "Real"
          },
          {
            "name": "l2",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addMDx",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "f",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dx",
            "type": "const DataVecDeriv &"
          },
          {
            "name": "factor",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addMToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mat",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "mFact",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isDiagonal",
        "return_type": "bool",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "kFact",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::behavior::StiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildMassMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrices",
            "type": "sofa::core::behavior::MassMatrixAccumulator *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "accFromF",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "a",
            "type": "DataVecDeriv &"
          },
          {
            "name": "f",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "f",
            "type": "DataVecDeriv &"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          },
          {
            "name": "v",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getKineticEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addDForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dx",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addGravityToV",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "d_v",
            "type": "DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getElementMass",
        "return_type": "SReal",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "initTextures",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "update",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDensity",
        "return_type": "void",
        "params": [
          {
            "name": "d",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getDensity",
        "return_type": "Real",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "HexahedronFEMForceFieldAndMass",
    "description": "This component computes finite element forces based on hexahedral elements and includes continuum mass matrices for more accurate physical simulations.",
    "type": "Component",
    "category": "Solid Mechanics",
    "parameters": [
      {
        "name": "density",
        "type": "Real",
        "description": "Density (volumetric mass) in kg/m³, used to calculate the element masses."
      },
      {
        "name": "lumpedMass",
        "type": "bool",
        "description": "Whether to use lumped masses for simplified calculations. Default is false, indicating continuum mass matrices are used."
      }
    ],
    "methods": [
      {
        "name": "init",
        "description": "Initializes the component, setting up required data structures and computing element properties."
      },
      {
        "name": "reinit",
        "description": "Reinitializes the component after changes in topology or other parameters affecting the calculations."
      },
      {
        "name": "computeElementMasses",
        "description": "Computes mass matrices for all elements based on their geometry and material properties."
      },
      {
        "name": "addMDx",
        "description": "Adds the product of mass matrix M and velocity change dx to force vector f, scaled by a factor. Implements part of the Mass interface."
      }
    ],
    "notes": [
      "This component extends the standard HexahedronFEMForceField with continuum mass matrices for more realistic dynamic simulations.",
      "It supports lumped masses as an option for simplified calculations when needed.",
      "The density parameter defines the volumetric mass used in calculating element masses.",
      "Mass and stiffness matrices are computed per element based on geometry, material properties, and global scaling factors."
    ]
  },
  "maths": {
    "maths": "The **HexahedronFEMForceFieldAndMass** component in the SOFA framework implements hexahedral finite elements for deformable solid mechanics simulations, incorporating both continuum mass matrices and stiffness matrices. This component contributes to several key aspects of the FEM pipeline: spatial discretization, element operators derivation, and time integration.\n\n### Governing Equations and Operators\n- **Mass Matrix (M)**\nThe mass matrix $M$ is computed per hexahedral element based on the density $\\rho$ and volume $V_e$. For each element with nodes $i = 0,1,...,7$, the mass of a particle is given by:\n\begin{equation}\n    m_i = \\frac{\\rho V_e}{8}.\n\tag{1}\\end{equation}\nThe lumped or consistent mass matrices are computed and stored in $M_e$ for each element, where $e$ indexes the elements. The global mass matrix is assembled from these local contributions:\n\begin{equation}\n    M = \\sum_e M_e.\n\tag{2}\\end{equation}\nThe lumped mass option allows simplifying this to a diagonal matrix with entries given by Eq. (1).\n\n- **Stiffness Matrix (K)** and Internal Force ($f_{int}$)\nThe stiffness matrix $K$ and internal force vector $f_{int}$ are inherited from the `HexahedronFEMForceField` base class, which implements standard hexahedral finite elements for deformable solids. The internal forces account for material stresses and nonlinear behavior of the solid.\n\n### Constitutive and Kinematic Laws\n- **Strain Measures and Stress Tensors**\nThe component relies on a constitutive law to relate strains $\\varepsilon$ to stresses $\\sigma$. This law is specified by the user through material parameters (e.g., Young's modulus, Poisson ratio for linear elasticity) or more complex hyperelastic potentials. The strain measures are derived from the displacement field using standard finite element shape functions.\n\n### Role in FEM Pipeline\n- **Assembly Phase**\nThe `HexahedronFEMForceFieldAndMass` computes and stores mass matrices per element during initialization (`init`) and reinitialization (`reinit`). These matrices are critical for assembling the global mass matrix $M$ used in time integration.\n\n- **Time Integration**\nThe component provides methods to compute the product of the mass matrix with a vector (addMDx) and to integrate gravity forces. It supports implicit time-stepping schemes, where the mass matrix plays a central role in updating nodal accelerations and velocities.\n\n### Numerical Methods\nThe component implements standard numerical methods for hexahedral finite elements:\n- **Element Operators**\nThe local stiffness matrix $K_e$ and internal force vector $f_{int}^e$ are computed per element using shape functions and their derivatives. The mass matrices $M_e$ are similarly computed, often via numerical integration over the element volume.\n\n### Variational Mechanics Framework\nThe `HexahedronFEMForceFieldAndMass` fits into a broader variational mechanics framework by:\n- Deriving weak forms of equilibrium equations for deformable solids,\n- Discretizing these equations using hexahedral finite elements, and\n- Assembling global matrices ($M$, $K$) and vectors from element contributions.\nThe inclusion of mass matrices ensures that the component can handle both static and dynamic simulations accurately."
  },
  "summary": {
    "abstract": "The `HexahedronFEMForceFieldAndMass` component computes finite element forces based on hexahedral elements and includes continuum mass matrices to account for physical properties in deformable solid mechanics simulations.",
    "sheet": "\\# HexahedronFEMForceFieldAndMass\n\n## Overview\n\nThis component handles the computation of finite element forces based on hexahedral elements, including both stiffness and mass contributions. It inherits from `HexahedronFEMForceField` for stiffness calculations and `Mass` for mass matrix computations.\n\n## Mathematical Model\n\nThe **HexahedronFEMForceFieldAndMass** component computes the mass matrices per element based on density \\(\\rho\\) and volume \\(V_e\\). For each hexahedral element with nodes indexed from 0 to 7, the mass of a particle is given by:\n\n\\[ m_i = \\frac{\\rho V_e}{8} \\]\n\nThe lumped or consistent mass matrices are computed for each element and stored in \\(M_e\\). The global mass matrix \\(M\\) is assembled from these local contributions as follows:\n\n\\[ M = \\sum_e M_e \\]\n\nIf the `lumpedMass` flag is set to true, the mass matrix simplifies to a diagonal form with entries given by Eq. (1).\n\n## Parameters and Data\n\n- **density**: The volumetric density of the material in kg/m\\(^3\\). This parameter controls the mass distribution within each element.\n- **lumpedMass**: A boolean flag indicating whether lumped masses are used. If true, the mass matrix is diagonalized."
  }
}