Back

MeshMatrixMass

sofa::component::mass::MeshMatrixMass
Mass
Doc (from source)

Compute a mass matrix resulting from the space integration of a density over a domain. template <class DataTypes, class TMassType> @class MeshMatrixMass @brief This component computes the integral of this mass density over the volume of the object geometry. @remark Similar to DiagonalMass which simplifies the Mass Matrix as diagonal. @remark https://www.sofa-framework.org/community/doc/components/masses/meshmatrixmass/ @tparam DataTypes type of the state associated to this mass @tparam GeometricalTypes type of the geometry, i.e type of the state associated with the topology (if the topology and the mass relates to the same state, this will be the same as DataTypes)

Abstract (AI generated)

The `MeshMatrixMass` component computes a mass matrix by integrating density over mesh elements, supporting lumped mass matrices and visualization of the center of gravity.

Metadata
module
Sofa.Component.Mass
namespace
sofa::component::mass
include
sofa/component/mass/MeshMatrixMass.h
inherits
  • Mass
templates
  • sofa::defaulttype::Vec2Types, sofa::defaulttype::Vec3Types
description

Mathematical and Physical Description of the MeshMatrixMass Component

Overview

The MeshMatrixMass component in the Simulation Open-Framework Architecture (SOFA) computes a mass matrix resulting from the spatial integration of a density over a domain. This mass distribution is associated with mesh elements, making it suitable for finite element-based simulations.

Mathematical Representation

Mass Distribution and Density Integration

The core functionality of MeshMatrixMass involves integrating the mass distribution over the geometry defined by the mesh topology. Given a density function $\rho(x)$ at each point in space, the mass matrix is computed through integration:

$$ m_i = \int_{V_i} \rho(\mathbf{x}) dV, $$

where $m_i$ is the mass associated with element $i$, and $V_i$ denotes the volume (or area for 2D cases) of the element.

Vertex and Edge Masses

The component also allows specifying masses directly at vertices (vertexMass) or along edges (edgeMass). These masses can be used to define a lumped mass matrix or a more detailed sparse mass distribution:

$$ m = m_{\text{vertex}} + m_{\text{edge}}, $$

where $m_{\text{vertex}}$ and $m_{\text{edge}}$ are the masses assigned to vertices and edges, respectively.

Vertex Mass Calculation for Lumped Mass Matrices

When a lumped mass matrix is used (controlled by d_lumping flag), each vertex is given a corresponding mass. This simplification can be represented as:

$$ m_{\text{lumped}} = m_{\text{vertex}} \cdot k, $$

where $k$ is the lumping coefficient (m_massLumpingCoeff).

Edge Mass Contribution for Sparse Matrices

For a sparse mass matrix, contributions from edges are also considered. The edge masses are distributed between connected vertices:

$$ m_{\text{total}} = m_{\text{vertex}} + 2 \cdot m_{\text{edge}}, $$

where the factor of 2 accounts for the contribution to both adjacent vertices.

Kinetic Energy Calculation

The kinetic energy associated with a given configuration is calculated using:

$$ E_k = \frac{1}{2} \sum_{i=0}^{N-1} m_i (\mathbf{v}_i)^T \mathbf{v}_i + 2 \cdot \sum_{j=0}^{M-1} m_j^e (\mathbf{v}_{e_0})^T \mathbf{v}_{e_1}, $$

where $N$ is the number of vertices, $M$ is the number of edges, and $(\mathbf{v}_i)$ denotes the velocity at vertex $i$. The term involving edges captures interactions between adjacent vertices.

Potential Energy Calculation with Gravity

Potential energy due to gravity can be calculated by integrating over the mass distribution:

$$ E_p = - \sum_{i=0}^{N-1} m_i (\mathbf{x}_i)^T \mathbf{g}, $$

where $\mathbf{g}$ is the gravity vector and $(\mathbf{x}_i)$ denotes the position of vertex $i$.

Momentum Calculation

Momentum is calculated as a combination of linear momentum (related to translation) and angular momentum (related to rotation):

  • Linear Momentum:
    $$ \mathbf{p} = \sum_{i=0}^{N-1} m_i \mathbf{v}_i + \sum_{j=0}^{M-1} m_j^e \left(\frac{\mathbf{v}_{e_0} + \mathbf{v}_{e_1}}{2}\right). $$

  • Angular Momentum:
    $$ \mathbf{L} = \sum_{i=0}^{N-1} m_i (\mathbf{x}_i)^T \times \mathbf{v}_i + \sum_{j=0}^{M-1} m_j^e ((\mathbf{x}_{e_0})^T \times \mathbf{v}_{e_0} + (\mathbf{x}_{e_1})^T \times \mathbf{v}_{e_1}). $$

Visualization and Physical Properties

The component provides visualization of the center of gravity by computing the weighted average position:

$$ \mathbf{C} = \frac{1}{m_{\text{total}}} \sum_{i=0}^{N-1} m_i \mathbf{x}_i, $$

where $m_{\text{total}}$ is the total mass. The showAxisSize parameter controls the size of axes used to visualize this center.

Integration into SOFA Simulation Pipeline

The MeshMatrixMass integrates into the SOFA simulation pipeline, contributing to accurate physical behaviors by providing detailed mass information that influences forces, motion, and interactions within the simulated environment.

Data Fields
NameTypeDefaultHelp
d_totalMass MassType If unspecified or wrongly set, the default value is used: totalMass = 1.0
d_computeMassOnRest bool If true, the mass of every element is computed based on the rest position rather than the position
d_showCenterOfGravity bool display the center of gravity of the system
d_showAxisSize Real factor length of the axis displayed (only used for rigids)
d_lumping bool If true, the mass matrix is lumped, meaning the mass matrix becomes diagonal (summing all mass values of a line on the diagonal)
d_printMass bool boolean if you want to check the mass conservation
data DataTypes, MassType, GeometricalTypes
Links
NameTypeHelp
l_topology link to the topology container
l_geometryState link to the MechanicalObject associated with the geometry
Methods
sofa::geometry::ElementType checkTopology ()
void initTopologyHandlers (sofa::geometry::ElementType topologyType)
void massInitialization ()
void clear () virtual
void reinit ()
void init ()
void handleEvent (sofa::core::objectmodel::Event * event)
void doUpdateInternal ()
sofa::geometry::ElementType getMassTopologyType ()
void setMassTopologyType (sofa::geometry::ElementType t)
int getMassCount ()
void printMass ()
void computeMass ()
const int & getVertexMass ()
const int & getMassDensity ()
const Real & getTotalMass () virtual
void setVertexMass (int vertexMass) virtual
void setMassDensity (int massDensity) virtual
void setMassDensity (MassType massDensityValue) virtual
void setTotalMass (MassType totalMass) virtual
void addMassDensity (const int & indices, const int & ancestors, const int & coefs) virtual
bool checkVertexMass () virtual
void initFromVertexMass () virtual
bool checkMassDensity () virtual
void initFromMassDensity () virtual
bool checkTotalMass () virtual
void checkTotalMassInit () virtual
void initFromTotalMass () virtual
bool checkEdgeMass ()
void initFromVertexAndEdgeMass ()
void copyVertexMass ()
void addMDx (const core::MechanicalParams * , DataVecDeriv & f, const DataVecDeriv & dx, SReal factor)
void accFromF (const core::MechanicalParams * , DataVecDeriv & a, const DataVecDeriv & f)
void addForce (const core::MechanicalParams * , DataVecDeriv & f, const DataVecCoord & x, const DataVecDeriv & v)
SReal getKineticEnergy (const core::MechanicalParams * , const DataVecDeriv & v)
SReal getPotentialEnergy (const core::MechanicalParams * , const DataVecCoord & x)
type::Vec6 getMomentum (const core::MechanicalParams * mparams, const DataVecCoord & x, const DataVecDeriv & v)
void addGravityToV (const core::MechanicalParams * mparams, DataVecDeriv & d_v)
bool isDiagonal ()
void addMToMatrix (sofa::linearalgebra::BaseMatrix * mat, SReal mFact, unsigned int & offset)
void buildMassMatrix (sofa::core::behavior::MassMatrixAccumulator * matrices)
void buildStiffnessMatrix (core::behavior::StiffnessMatrix * )
void buildDampingMatrix (core::behavior::DampingMatrix * )
SReal getElementMass (int index)
void getElementMass (int index, linearalgebra::BaseMatrix * m)
void draw (const core::visual::VisualParams * vparams)
bool isLumped ()
void parse (sofa::core::objectmodel::BaseObjectDescription * arg)
void applyVertexMassCreation (int pointIndex, MassType & VertexMass, const core::topology::BaseMeshTopology::Point & point, const int & , const int & )
void applyVertexMassDestruction (int , MassType & )
void applyEdgeMassCreation (int edgeIndex, MassType & EdgeMass, const core::topology::BaseMeshTopology::Edge & , const int & , const int & )
void applyEdgeMassDestruction (int , MassType & ) 
{
  "name": "MeshMatrixMass",
  "namespace": "sofa::component::mass",
  "module": "Sofa.Component.Mass",
  "include": "sofa/component/mass/MeshMatrixMass.h",
  "doc": "Compute a mass matrix resulting from the space integration of a density over a domain.\n\ntemplate <class DataTypes, class TMassType>\n@class    MeshMatrixMass\n@brief    This component computes the integral of this mass density over the volume of the object geometry.\n@remark   Similar to DiagonalMass which simplifies the Mass Matrix as diagonal.\n@remark   https://www.sofa-framework.org/community/doc/components/masses/meshmatrixmass/\n@tparam   DataTypes type of the state associated to this mass\n@tparam   GeometricalTypes type of the geometry, i.e type of the state associated with the topology (if the topology and the mass relates to the same state, this will be the same as DataTypes)",
  "inherits": [
    "Mass"
  ],
  "templates": [
    "sofa::defaulttype::Vec2Types, sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_totalMass",
      "type": "MassType",
      "xmlname": "totalMass",
      "help": "If unspecified or wrongly set, the default value is used: totalMass = 1.0"
    },
    {
      "name": "d_computeMassOnRest",
      "type": "bool",
      "xmlname": "computeMassOnRest",
      "help": "If true, the mass of every element is computed based on the rest position rather than the position"
    },
    {
      "name": "d_showCenterOfGravity",
      "type": "bool",
      "xmlname": "showGravityCenter",
      "help": "display the center of gravity of the system"
    },
    {
      "name": "d_showAxisSize",
      "type": "Real",
      "xmlname": "showAxisSizeFactor",
      "help": "factor length of the axis displayed (only used for rigids)"
    },
    {
      "name": "d_lumping",
      "type": "bool",
      "xmlname": "lumping",
      "help": "If true, the mass matrix is lumped, meaning the mass matrix becomes diagonal (summing all mass values of a line on the diagonal)"
    },
    {
      "name": "d_printMass",
      "type": "bool",
      "xmlname": "printMass",
      "help": "boolean if you want to check the mass conservation"
    },
    {
      "name": "data",
      "type": "DataTypes, MassType, GeometricalTypes"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    },
    {
      "name": "l_geometryState",
      "target": "MechanicalState<GeometricalTypes>",
      "kind": "single",
      "xmlname": "geometryState",
      "help": "link to the MechanicalObject associated with the geometry"
    }
  ],
  "methods": [
    {
      "name": "checkTopology",
      "return_type": "sofa::geometry::ElementType",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initTopologyHandlers",
      "return_type": "void",
      "params": [
        {
          "name": "topologyType",
          "type": "sofa::geometry::ElementType"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "massInitialization",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "clear",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "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": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "sofa::core::objectmodel::Event *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "doUpdateInternal",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMassTopologyType",
      "return_type": "sofa::geometry::ElementType",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMassTopologyType",
      "return_type": "void",
      "params": [
        {
          "name": "t",
          "type": "sofa::geometry::ElementType"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMassCount",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "printMass",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeMass",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVertexMass",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMassDensity",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTotalMass",
      "return_type": "const Real &",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setVertexMass",
      "return_type": "void",
      "params": [
        {
          "name": "vertexMass",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMassDensity",
      "return_type": "void",
      "params": [
        {
          "name": "massDensity",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMassDensity",
      "return_type": "void",
      "params": [
        {
          "name": "massDensityValue",
          "type": "MassType"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTotalMass",
      "return_type": "void",
      "params": [
        {
          "name": "totalMass",
          "type": "MassType"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMassDensity",
      "return_type": "void",
      "params": [
        {
          "name": "indices",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkVertexMass",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromVertexMass",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkMassDensity",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromMassDensity",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTotalMass",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTotalMassInit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromTotalMass",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkEdgeMass",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initFromVertexAndEdgeMass",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "copyVertexMass",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMDx",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "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": "accFromF",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "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": "",
          "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": "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": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMomentum",
      "return_type": "type::Vec6",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "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": "isDiagonal",
      "return_type": "bool",
      "params": [],
      "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": "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": "buildStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::StiffnessMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildDampingMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "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": "getElementMass",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        },
        {
          "name": "m",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "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": "isLumped",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "parse",
      "return_type": "void",
      "params": [
        {
          "name": "arg",
          "type": "sofa::core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyVertexMassCreation",
      "return_type": "void",
      "params": [
        {
          "name": "pointIndex",
          "type": "int"
        },
        {
          "name": "VertexMass",
          "type": "MassType &"
        },
        {
          "name": "point",
          "type": "const core::topology::BaseMeshTopology::Point &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyVertexMassDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int"
        },
        {
          "name": "",
          "type": "MassType &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyEdgeMassCreation",
      "return_type": "void",
      "params": [
        {
          "name": "edgeIndex",
          "type": "int"
        },
        {
          "name": "EdgeMass",
          "type": "MassType &"
        },
        {
          "name": "",
          "type": "const core::topology::BaseMeshTopology::Edge &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyEdgeMassDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int"
        },
        {
          "name": "",
          "type": "MassType &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "title": "MeshMatrixMass Component",
  "description": "The `MeshMatrixMass` component in SOFA computes a mass matrix resulting from the spatial integration of a density over a domain. This mass distribution is associated with mesh elements, making it suitable for finite element-based simulations.\n\n### Features:\n- **Supports Different Data Types:** The component can work with different vector types (`Vec1`, `Vec2`, and `Vec3`), allowing flexibility in representing 1D, 2D, or 3D data.\n- **Custom Geometrical Types:** It also supports custom geometrical types for more specialized use cases.\n- **Center of Gravity Visualization:** The component can visualize the center of gravity of the mass distribution using a configurable axis size.\n- **Momentum Calculation:** Calculates linear and angular momentum based on vertex positions, velocities, and masses, useful for dynamics simulations.\n\n### Usage:\n- The `MeshMatrixMass` component is typically added to nodes containing geometric data (positions) and topology information. It computes the mass distribution over these elements and can be used in conjunction with various physics engines or solvers within SOFA.\n- This component is particularly useful for simulations where accurate representation of mass distribution across a mesh is critical, such as in soft tissue modeling or complex structural analysis.\n\n### Configuration:\n- **Attributes:**\n  - `l_topology`: Links to the topology container that defines how geometric elements (vertices, edges) are connected.\n  - `gravityCenter` and `totalMass`: Automatically computed based on vertex positions and masses.\n  - `showAxisSize`: Size of axes for visualizing center of gravity.\n- **Methods:**\n  - `draw()`: Visualizes mass points and the center of gravity if enabled.\n  - `getElementMass()`: Retrieves the mass associated with a specific element.\n\n### Integration:\n- The component integrates seamlessly into SOFA's simulation pipeline, contributing to accurate physical behaviors by providing detailed mass information that can influence forces, motion, and interactions within the simulated environment.",
  "parameters": [
    {
      "name": "l_topology",
      "description": "The topology container defining mesh connectivity.",
      "type": "sofa::core::topology::BaseTopology::SPtr"
    },
    {
      "name": "showAxisSize",
      "description": "Size of axes for visualizing center of gravity.",
      "type": "Real",
      "default_value": ""
    },
    {
      "name": "showCenterOfGravity",
      "description": "Flag to enable visualization of the center of gravity.",
      "type": "bool",
      "default_value": "False"
    }
  ],
  "example": "To use `MeshMatrixMass` in a SOFA scene, you would typically define it as follows:\n```xml\n<Node>\n    <MechanicalObject name='geometry' position='...' />\n    <RegularGridTopology name='topology' nx='10' ny='10' nz='10'/>\n    <MeshMatrixMass l_topology='@topology' showAxisSize='2.0' showCenterOfGravity='true'/>\n</Node>\n```",
  "maths": "# Mathematical and Physical Description of the MeshMatrixMass Component\n\n## Overview\nThe `MeshMatrixMass` component in the Simulation Open-Framework Architecture (SOFA) computes a mass matrix resulting from the spatial integration of a density over a domain. This mass distribution is associated with mesh elements, making it suitable for finite element-based simulations.\n\n## Mathematical Representation\n### Mass Distribution and Density Integration\nThe core functionality of `MeshMatrixMass` involves integrating the mass distribution over the geometry defined by the mesh topology. Given a density function $\\rho(x)$ at each point in space, the mass matrix is computed through integration:\n\n$$\nm_i = \\int_{V_i} \\rho(\\mathbf{x}) dV,\n$$\nwhere $m_i$ is the mass associated with element $i$, and $V_i$ denotes the volume (or area for 2D cases) of the element.\n\n### Vertex and Edge Masses\nThe component also allows specifying masses directly at vertices (`vertexMass`) or along edges (`edgeMass`). These masses can be used to define a lumped mass matrix or a more detailed sparse mass distribution:\n\n$$\nm = m_{\\text{vertex}} + m_{\\text{edge}},\n$$\nwhere $m_{\\text{vertex}}$ and $m_{\\text{edge}}$ are the masses assigned to vertices and edges, respectively.\n\n### Vertex Mass Calculation for Lumped Mass Matrices\nWhen a lumped mass matrix is used (controlled by `d_lumping` flag), each vertex is given a corresponding mass. This simplification can be represented as:\n\n$$\nm_{\\text{lumped}} = m_{\\text{vertex}} \\cdot k,\n$$\nwhere $k$ is the lumping coefficient (`m_massLumpingCoeff`).\n\n### Edge Mass Contribution for Sparse Matrices\nFor a sparse mass matrix, contributions from edges are also considered. The edge masses are distributed between connected vertices:\n\n$$\nm_{\\text{total}} = m_{\\text{vertex}} + 2 \\cdot m_{\\text{edge}},\n$$\nwhere the factor of 2 accounts for the contribution to both adjacent vertices.\n\n### Kinetic Energy Calculation\nThe kinetic energy associated with a given configuration is calculated using:\n\n$$\nE_k = \\frac{1}{2} \\sum_{i=0}^{N-1} m_i (\\mathbf{v}_i)^T \\mathbf{v}_i + 2 \\cdot \\sum_{j=0}^{M-1} m_j^e (\\mathbf{v}_{e_0})^T \\mathbf{v}_{e_1},\n$$\nwhere $N$ is the number of vertices, $M$ is the number of edges, and $(\\mathbf{v}_i)$ denotes the velocity at vertex $i$. The term involving edges captures interactions between adjacent vertices.\n\n### Potential Energy Calculation with Gravity\nPotential energy due to gravity can be calculated by integrating over the mass distribution:\n\n$$\nE_p = - \\sum_{i=0}^{N-1} m_i (\\mathbf{x}_i)^T \\mathbf{g},\n$$\nwhere $\\mathbf{g}$ is the gravity vector and $(\\mathbf{x}_i)$ denotes the position of vertex $i$.\n\n### Momentum Calculation\nMomentum is calculated as a combination of linear momentum (related to translation) and angular momentum (related to rotation):\n\n- **Linear Momentum**:\n  $$\n  \\mathbf{p} = \\sum_{i=0}^{N-1} m_i \\mathbf{v}_i + \\sum_{j=0}^{M-1} m_j^e \\left(\\frac{\\mathbf{v}_{e_0} + \\mathbf{v}_{e_1}}{2}\\right).\n  $$\n\n- **Angular Momentum**:\n  $$\n  \\mathbf{L} = \\sum_{i=0}^{N-1} m_i (\\mathbf{x}_i)^T \\times \\mathbf{v}_i + \\sum_{j=0}^{M-1} m_j^e ((\\mathbf{x}_{e_0})^T \\times \\mathbf{v}_{e_0} + (\\mathbf{x}_{e_1})^T \\times \\mathbf{v}_{e_1}).\n  $$\n\n## Visualization and Physical Properties\nThe component provides visualization of the center of gravity by computing the weighted average position:\n\n$$\n\\mathbf{C} = \\frac{1}{m_{\\text{total}}} \\sum_{i=0}^{N-1} m_i \\mathbf{x}_i,\n$$\nwhere $m_{\\text{total}}$ is the total mass. The `showAxisSize` parameter controls the size of axes used to visualize this center.\n\n## Integration into SOFA Simulation Pipeline\nThe `MeshMatrixMass` integrates into the SOFA simulation pipeline, contributing to accurate physical behaviors by providing detailed mass information that influences forces, motion, and interactions within the simulated environment.",
  "abstract": "The `MeshMatrixMass` component computes a mass matrix by integrating density over mesh elements, supporting lumped mass matrices and visualization of the center of gravity.",
  "sheet": "# MeshMatrixMass\n\n## Overview\nThe `MeshMatrixMass` component in SOFA computes a mass matrix resulting from the spatial integration of a density function over the domain defined by mesh elements. It supports lumping the mass matrix to make it diagonal, which simplifies calculations. The component also provides visualization features for displaying the center of gravity.\n\n## Mathematical Model\nThe core functionality involves integrating the density function $\\rho(\\mathbf{x})$ over each element's volume (or area) to compute the mass associated with that element:\n$$\nm_i = \\int_{V_i} \\rho(\\mathbf{x}) dV,\n$$\nwhere $m_i$ is the mass of element $i$, and $V_i$ denotes its volume.\n\nFor lumped mass matrices, each vertex is assigned a corresponding mass:\n$$\nm_{\\text{lumped}} = m_{\\text{vertex}} \\cdot k,\n$$\nwhere $k$ is the lumping coefficient. The total mass can also include contributions from edges if specified.\n\n## Parameters and Data\n- **totalMass**: If unspecified, defaults to 1.0. Controls the total mass of the system.\n- **computeMassOnRest**: Boolean flag indicating whether masses are computed based on rest positions rather than current positions.\n- **showGravityCenter**: Boolean flag for displaying the center of gravity.\n- **showAxisSizeFactor**: Factor controlling the length of axes displayed (only used for rigid bodies).\n- **lumping**: Boolean flag to enable lumping the mass matrix, making it diagonal by summing all mass values on the diagonal.\n- **printMass**: Boolean flag to check and print mass conservation."
}