{
  "name": "HexahedralFEMForceFieldAndMass",
  "main": {
    "name": "HexahedralFEMForceFieldAndMass",
    "namespace": "sofa::component::solidmechanics::fem::elastic",
    "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
    "include": "sofa/component/solidmechanics/fem/elastic/HexahedralFEMForceFieldAndMass.h",
    "doc": "Hexahedral finite elements with mass\n\nCompute Finite Element forces based on hexahedral elements including continuum mass matrices",
    "inherits": [
      "HexahedralFEMForceField",
      "Mass"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_density",
        "type": "Real",
        "xmlname": "density",
        "help": "density == volumetric mass in english (kg.m-3)"
      },
      {
        "name": "d_useLumpedMass",
        "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": "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": "addMBKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "matrix",
            "type": "const sofa::core::behavior::MultiMatrixAccessor *"
          }
        ],
        "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": "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": "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": "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": "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": "getElementMass",
        "return_type": "SReal",
        "params": [
          {
            "name": "index",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "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"
      },
      {
        "name": "computeElementMasses",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "integrateVolume",
        "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": "protected"
      },
      {
        "name": "computeElementMass",
        "return_type": "void",
        "params": [
          {
            "name": "Mass",
            "type": "ElementMass &"
          },
          {
            "name": "totalMass",
            "type": "Real &"
          },
          {
            "name": "nodes",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeParticleMasses",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeLumpedMasses",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "HexahedralFEMForceFieldAndMass is a component in the SOFA (Simulation Open-Framework Architecture) framework designed for simulating solid mechanics with finite element methods based on hexahedral elements. This component extends the functionality of HexahedralFEMForceField by incorporating continuum mass matrices, which allows for more accurate simulation of dynamic behaviors in solid materials.",
    "attributes": [
      {
        "name": "d_density",
        "type": "Real",
        "description": "Density (or volumetric mass) of the material represented in kg/m³. This parameter is used to calculate the mass distribution within each hexahedral element."
      },
      {
        "name": "d_useLumpedMass",
        "type": "bool",
        "description": "A flag that determines whether lumped masses should be used instead of full mass matrices. Lumped masses can simplify calculations but may reduce accuracy in dynamic simulations."
      }
    ],
    "methods": [
      {
        "name": "init()",
        "description": "Initializes the component, setting up internal data structures and dependencies required for simulation."
      },
      {
        "name": "reinit()",
        "description": "Reinitializes the component after any changes to topology or geometry. This method is called when the system needs to be reset due to changes in the model."
      },
      {
        "name": "addMDx(const core::MechanicalParams* mparams, DataVecDeriv& f, const DataVecDeriv& dx, SReal factor)",
        "description": "Calculates and adds the product of mass matrix (M) and velocity derivative (dx) to force vector (f)."
      },
      {
        "name": "addMToMatrix(sofa::linearalgebra::BaseMatrix * mat, SReal mFact, unsigned int &offset)",
        "description": "Adds diagonal elements from the mass matrices of hexahedral elements into a provided matrix. This method is marked with a warning that it only adds diagonal elements."
      },
      {
        "name": "addKToMatrix(sofa::linearalgebra::BaseMatrix * matrix, SReal kFact, unsigned int &offset)",
        "description": "Adds diagonal elements from the stiffness matrices of hexahedral elements into a provided matrix. This method is marked with a warning that it only adds diagonal elements."
      },
      {
        "name": "addMBKToMatrix(const core::MechanicalParams* mparams, const sofa::core::behavior::MultiMatrixAccessor* matrix)",
        "description": "Adds diagonal elements from both mass and stiffness matrices into a provided matrix for use in dynamic simulations. This method is marked with a warning that it only adds diagonal elements."
      },
      {
        "name": "addForce(const core::MechanicalParams* mparams, DataVecDeriv& f, const DataVecCoord& x, const DataVecDeriv& v)",
        "description": "Adds the computed forces to force vector (f) based on current position (x) and velocity (v). This method also adds gravitational forces if required."
      },
      {
        "name": "addDForce(const core::MechanicalParams* mparams, DataVecDeriv& df, const DataVecDeriv& dx)",
        "description": "Adds the computed derivative of forces to a force vector (df) based on the change in velocity (dx)."
      },
      {
        "name": "getPotentialEnergy(const core::MechanicalParams* mparams, const DataVecCoord& x) const",
        "description": "Returns potential energy of the system. This method is marked as not yet implemented."
      },
      {
        "name": "getElementMass(sofa::Index index) const",
        "description": "Returns the mass of a specified hexahedral element. This method is marked as not yet implemented."
      }
    ],
    "dependencies": [
      "HexahedralFEMForceField<DataTypes>",
      "sofa::core::behavior::Mass<DataTypes>"
    ],
    "related_components": [
      "Sofa.Component.Mass",
      "Sofa.Component.SolidMechanics.FEM.Elastic"
    ]
  },
  "maths": {
    "maths": "<p>The <code>HexahedralFEMForceFieldAndMass</code> component in the SOFA framework simulates solid mechanics with finite element methods based on hexahedral elements. It extends the functionality of the <code>HexahedralFEMForceField</code> by incorporating continuum mass matrices, enabling more accurate dynamic simulations.</p>\n\n<h3 id=\"governing-equations-and-operators\">Governing Equations and Operators</h3>\n\n<p>The component computes the forces and masses based on hexahedral elements. The primary operators it contributes to are:</p>\n\n<ul>\n<li><strong>Mass Matrix <span class=\"math inline\">\\(M\\)</span></strong>: Computes the mass contributions for each element, leading to global continuum mass matrices.</li>\n<li><strong>Stiffness Matrix <span class=\"math inline\">\\(K\\)</span></strong>: Inherited from <code>HexahedralFEMForceField</code>, computes the stiffness contributions based on material and geometric properties of hexahedral elements.</li>\n<li><strong>Internal Force Vector <span class=\"math inline\">\\(f_{int}\\)</span></strong>: Computes internal forces arising from displacements within the hexahedral elements, inherited from <code>HexahedralFEMForceField</code>.</li>\n<li><strong>Residual Vector <span class=\"math inline\">\\(R(x)\\)</span></strong>: Combines contributions from mass and stiffness matrices with external forces to form the residual for solving nonlinear equations.</li>\n</ul>\n\n<h3 id=\"constitutive-laws-and-strainmeasures\">Constitutive Laws and Strain Measures</h3>\n\n<p>The component inherits constitutive laws from <code>HexahedralFEMForceField</code>. It computes the strain measures based on displacements within hexahedral elements. The stress tensors are derived from these strains according to the selected material model, typically linear or nonlinear elasticity.</p>\n\n<h3 id=\"role-in-the-fem-pipeline\">Role in the FEM Pipeline</h3>\n\n<p>Within the broader Finite Element Method (FEM) pipeline:</p>\n\n<ul>\n<li><strong>Assembly Phase</strong>: Computes element-wise mass matrices and stiffness matrices, assembling them into global continuum mass matrix <span class=\"math inline\">\\(M\\)</span> and stiffness matrix <span class=\"math inline\">\\(K\\)</span>.</li>\n<li><strong>Time Integration</strong>: Contributes to the semi-discrete dynamical system equation:</p>\n\n<p><span class=\"math display\">\\[ M \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t) \\]</span></p>\n\n<li><strong>Nonlinear Resolution</strong>: Solves the nonlinear residual <span class=\"math inline\">\\(R(x)\\)</span>, incorporating contributions from mass, stiffness, and internal forces.</li>\n<li><strong>Linear Solve</strong>: Incorporates lumped or continuum mass matrices into the linear system of equations for efficient solution using Krylov subspace methods or direct solvers.</li>\n</ul>\n\n<h3 id=\"numerical-methods-and-discretization\">Numerical Methods and Discretization Choices</h3>\n\n<ul>\n<li><strong>Mass Computation</strong>: Computes element-wise masses and total mass per element, distributing it to particles for lumped or full continuum mass matrices.</li>\n<li><strong>Lumped Masses</strong>: If enabled via the <code>d_useLumpedMass</code> parameter, the component computes lumped masses at particle locations instead of the full continuum matrix. This can significantly simplify the linear system solution process but may reduce accuracy.</li>\n<li><strong>Numerical Integration</strong>: Computes mass matrices using numerical integration over hexahedral elements to ensure consistency with variational principles and accurate representation of material properties.</li>\n</ul>\n\n<h3 id=\"fit-into-the-broader-framework\">Fit into the Broader Variational / Lagrangian Mechanics Framework</h3>\n\n<p>The <code>HexahedralFEMForceFieldAndMass</code> component fits seamlessly within the variational mechanics framework:</p>\n\n<ul>\n<li><strong>Lagrangian Formulation</strong>: Adheres to the principle of minimizing potential energy, which underpins the variational formulation used for finite element discretization.</li>\n<li><strong>Weakening Principle</strong>: The weak (variational) form is employed for spatial discretization, leading to a consistent numerical representation that preserves mechanical invariants.</li>\n<li><strong>Implicit Time Integration</strong>: Ensures stability and accuracy of dynamic simulations by solving implicit equations at each time step, considering both inertial forces via the mass matrix <span class=\"math inline\">\\(M\\)</span> and internal stiffness contributions from <span class=\"math inline\">\\(K\\)</span>.</li>\n</ul>"
  },
  "summary": {
    "abstract": "Computes finite element forces and continuum mass matrices for hexahedral elements in solid mechanics simulations, supporting dynamic behavior.",
    "sheet": "# HexahedralFEMForceFieldAndMass\n\n## Overview\nHexahedralFEMForceFieldAndMass extends the functionality of `HexahedralFEMForceField` by incorporating continuum mass matrices. This component handles both internal forces and stiffness contributions based on hexahedral elements, enabling more accurate dynamic simulations in solid mechanics.\n\n## Mathematical Model\nThe primary operators and equations involved are:\n- **Mass Matrix** \\(M\\): Computes the mass contributions for each element, leading to global continuum mass matrices.\n- **Stiffness Matrix** \\(K\\): Inherited from `HexahedralFEMForceField`, computes stiffness based on material and geometric properties of hexahedral elements.\n- **Internal Force Vector** \\(f_{int}\\): Computes internal forces arising from displacements within the hexahedral elements, inherited from `HexahedralFEMForceField`.\n\nThe governing equation for dynamic behavior is:\n\\[ M \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t) \\]\nwhere \\(M\\) is the mass matrix, \\(K\\) is the stiffness matrix, and \\(f_{int}\\) represents internal forces.\n\n## Parameters and Data\n- **density**: Controls the volumetric mass (kg/m³). Default value not specified.\n- **lumpedMass**: Boolean flag indicating whether to use lumped masses. Default value not specified.\n\n## Dependencies and Connections\nThis component typically requires connections with other components that handle mechanical states, such as `MechanicalState` or `TopologyContainer`, to exchange data on displacements, velocities, and forces."
  }
}