DiagonalMass
The `DiagonalMass` component in the SOFA framework is designed to compute a lumped (diagonalized) mass matrix by integrating a density over a domain's volume. This mass computation assumes that the mass matrix is diagonal, simplifying subsequent calculations and interactions within the simulation. The component can handle different types of geometries and state data through its template parameters, allowing for flexibility in representing rigid or vectorial objects. **Role and Purpose:** The `DiagonalMass` facilitates the efficient computation of mass properties by assuming a diagonal structure for the mass matrix. This simplification enables faster numerical operations while still providing an accurate representation of physical behavior within the simulation context. The component is essential for simulating interactions involving forces, momentum, and energy calculations that depend on mass distributions. **Interactions with Other Components:** The `DiagonalMass` interacts primarily through its API to receive geometry information from linked components such as `MechanicalObject`, which provides the state and position data. The component also links with a topology container (`BaseMeshTopology`) for topological information regarding vertices, edges, triangles, etc., enabling it to calculate mass distributions based on geometric shapes and their associated densities. **Usage Guidance:** The main data fields of `DiagonalMass` include: - **massDensity**: A real number representing the density used for calculating vertex masses; defaults or wrong values are overridden by totalMass settings. - **totalMass**: The overall mass, defaulting to 1.0 if unspecified. - **computeMassOnRest**: Indicates whether mass should be computed based on rest positions instead of current ones. - **showCenterOfGravity**: Enables the display of the system's center of gravity. - **showAxisSizeFactor**: Adjusts the scale factor for displayed axes, relevant for rigid object visualization. Additionally, it can link to a topology container and a MechanicalObject associated with geometry, ensuring correct behavior during initialization.
- abstract
- The `DiagonalMass` computes a lumped (diagonalized) mass matrix by integrating density over the domain's volume, simplifying subsequent calculations within the simulation.
- sheet
- <h1>DiagonalMass</h1> <h2>Overview</h2> <p>The <code>DiagonalMass</code> component computes a lumped (diagonalized) mass matrix by integrating density over the domain's volume. This simplification assumes that the mass distribution can be represented as a diagonal matrix, which significantly reduces computational complexity for dynamic simulations involving forces and inertia.</p> <h2>Mathematical Model</h2> <p>The primary role of <code>DiagonalMass</code> is to compute vertex masses based on specified density and geometric properties. The mass computation involves integrating the mass density over the volume or area elements corresponding to each vertex.</p> <ul> <li><strong>Triangular Elements:</strong> \[ m_i^{triangle} = \frac{\text{Area of Triangle}}{3} \times \rho \] Where $m_i^{triangle}$ is the mass contribution to vertex $i$ from a triangular element, and $\rho$ is the specified density.</li> <li><strong>Tetrahedral Elements:</strong> \[ m_i^{tetrahedron} = \frac{\text{Volume of Tetrahedron}}{4} \times \rho \] Where $m_i^{tetrahedron}$ is the mass contribution to vertex $i$ from a tetrahedral element, and $\rho$ is the specified density.</li> </ul> <p>The total lumped mass at each vertex ($m_i$) is calculated as follows: \[ m_i = \sum_{j=1}^{N_t}(m_i^{triangle}) + \sum_{k=1}^{N_v}(m_i^{tetrahedron}) \] Where $N_t$ and $N_v$ represent the number of triangles and tetrahedra, respectively, contributing to vertex $i$. The total mass of the system is then given by: \[ M_{total} = \sum_{i=1}^{N}(m_i) \] Where $N$ is the total number of vertices.</p> <h2>Parameters and Data</h2> <table> <thead> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>massDensity</code></td> <td><code>Real</code></td> <td>Density used for calculating vertex masses; defaults or wrong values are overridden by totalMass settings.</td> </tr> <tr> <td><code>totalMass</code></td> <td><code>Real</code></td> <td>The overall mass, defaulting to 1.0 if unspecified.</td> </tr> <tr> <td><code>computeMassOnRest</code></td> <td><code>bool</code></td> <td>Indicates whether mass should be computed based on rest positions instead of current ones.</td> </tr> <tr> <td><code>showCenterOfGravity</code></td> <td><code>bool</code></td> <td>Enables the display of the system's center of gravity.</td> </tr> <tr> <td><code>showAxisSizeFactor</code></td> <td><code>float</code></td> <td>Adjusts the scale factor for displayed axes, relevant for rigid object visualization.</td> </tr> </tbody> </table> <h2>Dependencies and Connections</h2> <p>The <code>DiagonalMass</code> component links to a topology container (<code>BaseMeshTopology</code>) for topological information regarding vertices, edges, triangles, etc., enabling it to calculate mass distributions based on geometric shapes and their associated densities. It also interacts with the <code>MechanicalObject</code> associated with geometry to receive state and position data.</p> <h2>Practical Notes</h2> <p>The component assumes a diagonal structure for the mass matrix, which simplifies numerical operations but may introduce approximations in certain scenarios. Ensure that the specified density or total mass is appropriate for the simulation context to maintain physical accuracy.</p>
- description
- The `DiagonalMass` component in the SOFA framework is designed to compute a lumped (diagonalized) mass matrix by integrating a density over a domain's volume. This mass computation assumes that the mass matrix is diagonal, simplifying subsequent calculations and interactions within the simulation. The component can handle different types of geometries and state data through its template parameters, allowing for flexibility in representing rigid or vectorial objects. **Role and Purpose:** The `DiagonalMass` facilitates the efficient computation of mass properties by assuming a diagonal structure for the mass matrix. This simplification enables faster numerical operations while still providing an accurate representation of physical behavior within the simulation context. The component is essential for simulating interactions involving forces, momentum, and energy calculations that depend on mass distributions. **Interactions with Other Components:** The `DiagonalMass` interacts primarily through its API to receive geometry information from linked components such as `MechanicalObject`, which provides the state and position data. The component also links with a topology container (`BaseMeshTopology`) for topological information regarding vertices, edges, triangles, etc., enabling it to calculate mass distributions based on geometric shapes and their associated densities. **Usage Guidance:** The main data fields of `DiagonalMass` include: - **massDensity**: A real number representing the density used for calculating vertex masses; defaults or wrong values are overridden by totalMass settings. - **totalMass**: The overall mass, defaulting to 1.0 if unspecified. - **computeMassOnRest**: Indicates whether mass should be computed based on rest positions instead of current ones. - **showCenterOfGravity**: Enables the display of the system's center of gravity. - **showAxisSizeFactor**: Adjusts the scale factor for displayed axes, relevant for rigid object visualization. Additionally, it can link to a topology container and a MechanicalObject associated with geometry, ensuring correct behavior during initialization.
- maths
- # Mathematical and Physical Description of DiagonalMass Component ## Overview The `DiagonalMass` component in the SOFA framework is designed to compute a lumped (diagonalized) mass matrix by integrating density over the volume or area of the domain. This simplification assumes that the mass distribution can be represented as a diagonal matrix, which significantly reduces the computational complexity for dynamic simulations involving forces and inertia. ## Mathematical Formulation The primary role of `DiagonalMass` is to compute vertex masses based on the specified density and geometric properties of the object being simulated. The mathematical formulation involves integrating the mass density over the volume or area elements corresponding to each vertex. ### Mass Computation Given a domain discretized into vertices, edges, faces (triangles), or tetrahedra, the `DiagonalMass` component calculates the lumped masses for each vertex. This is achieved by summing contributions from surrounding geometric entities such as triangles and tetrahedra. #### Triangular Elements: The mass contribution from a triangular element to its vertices can be computed using barycentric coordinates or area-based methods, often leading to equal distribution among the three vertices of the triangle. egin{align} m_i^{triangle} &= \frac{ ext{Area of Triangle}}{3}\times\rho \\ \end{align} Where $m_i^{triangle}$ is the mass contribution to vertex $i$ from a triangular element, and $ ho$ is the specified density. #### Tetrahedral Elements: The mass contribution for tetrahedra involves a similar approach but may also consider higher-order approximations or weighted contributions based on proximity. The total mass at each vertex is the sum of all contributing elements' masses. egin{align} m_i^{tetrahedron} &= \frac{ ext{Volume of Tetrahedron}}{4}\times\rho \\ \end{align} Where $m_i^{tetrahedron}$ is the mass contribution to vertex $i$ from a tetrahedral element, and $ ho$ is the specified density. ### Total Mass Calculation The total lumped mass at each vertex ($m_i$) is calculated as follows: egin{align} m_i &= \sum_{j=1}^{N_t}(m_i^{triangle}) + \sum_{k=1}^{N_v}(m_i^{tetrahedron}) \\ \end{align} Where $N_t$ and $N_v$ represent the number of triangles and tetrahedra, respectively, contributing to vertex $i$. The total mass of the system is then given by: egin{align} M_{total} &= \sum_{i=1}^{N}(m_i) \\ \end{align} Where $N$ is the total number of vertices. ## Physical Interpretation In physical terms, `DiagonalMass` simplifies mass distribution by assuming that each vertex carries its own lumped mass. This approach is particularly useful for simulations where the detailed spatial distribution of mass can be approximated as concentrated at discrete points (vertices). ### Gravity and Inertial Forces The component also handles gravitational forces and inertial forces in the simulation. The gravity force $ extbf{F}_g$ acting on each vertex $i$ is calculated as: egin{align} extbf{F}_{gi} &= m_i \cdot extbf{g} \\ \end{align} Where $ extbf{g}$ is the gravity vector. The `DiagonalMass` adds this gravitational force to each vertex's velocity during the simulation update step. ### Center of Gravity Calculation The center of gravity (COG) of the system can be computed as a weighted average of all vertices' positions: egin{align} extbf{COG} &= \frac{1}{M_{total}}\sum_{i=1}^{N}(m_i \cdot extbf{x}_i) \\ \end{align} Where $ extbf{x}_i$ is the position of vertex $i$. The COG can be visualized in the simulation to aid in understanding the object's balance and movement. ## Conclusion The `DiagonalMass` component provides a computationally efficient method for lumped mass calculations, making it suitable for real-time dynamic simulations. By assuming a diagonal mass matrix, complex interactions involving forces and inertia can be simplified while maintaining accurate physical behavior.
{
"name": "DiagonalMass",
"main": {
"name": "DiagonalMass",
"namespace": "sofa::component::mass",
"module": "Sofa.Component.Mass",
"include": "sofa/component/mass/DiagonalMass.h",
"doc": "Compute a lumped (diagonalized) mass matrix resulting from the space integration of a density over a domain.\n\n@class DiagonalMass\n@brief This component computes the integral of this mass density over the volume of the object geometry but it supposes that the Mass matrix is diagonal.\n@remark Similar to MeshMatrixMass but it does not simplify the Mass Matrix as diagonal.\n@remark https://www.sofa-framework.org/community/doc/components/masses/diagonalmass/\n@tparam DataTypes type of the state associated with 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::Rigid2Types, sofa::defaulttype::Rigid3Types",
"sofa::defaulttype::Vec2Types, sofa::defaulttype::Vec3Types"
],
"data_fields": [
{
"name": "d_massDensity",
"type": "Real",
"xmlname": "massDensity",
"help": "If unspecified or wrongly set, the totalMass information is used."
},
{
"name": "d_totalMass",
"type": "Real",
"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": "float",
"xmlname": "showAxisSizeFactor",
"help": "Factor length of the axis displayed (only used for rigids)"
}
],
"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": "load",
"return_type": "bool",
"params": [
{
"name": "filename",
"type": "const char *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clear",
"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": "init",
"return_type": "void",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "handleEvent",
"return_type": "void",
"params": [
{
"name": "",
"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": "getMassDensity",
"return_type": "Real",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "checkTopology",
"return_type": "bool",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "initTopologyHandlers",
"return_type": "void",
"params": [],
"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": "computeVertexMass",
"return_type": "Real",
"params": [
{
"name": "density",
"type": "Real"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "applyPointCreation",
"return_type": "void",
"params": [
{
"name": "pointIndex",
"type": "PointID"
},
{
"name": "m",
"type": "MassType &"
},
{
"name": "",
"type": "const Point &"
},
{
"name": "",
"type": "const int &"
},
{
"name": "",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "applyPointDestruction",
"return_type": "void",
"params": [
{
"name": "id",
"type": "int"
},
{
"name": "VertexMass",
"type": "MassType &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "applyEdgeCreation",
"return_type": "void",
"params": [
{
"name": "",
"type": "const int &"
},
{
"name": "",
"type": "const int &"
},
{
"name": "",
"type": "const int &"
},
{
"name": "",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "applyEdgeDestruction",
"return_type": "void",
"params": [
{
"name": "",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "protected"
},
{
"name": "getTotalMass",
"return_type": "SReal",
"params": [],
"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": "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": "massDensityValue",
"type": "Real"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setTotalMass",
"return_type": "void",
"params": [
{
"name": "totalMass",
"type": "Real"
}
],
"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": "addMass",
"return_type": "void",
"params": [
{
"name": "mass",
"type": "const MassType &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resize",
"return_type": "void",
"params": [
{
"name": "vsize",
"type": "int"
}
],
"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": "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": "mparams",
"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": "mparams",
"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": "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": "",
"type": "int"
},
{
"name": "m",
"type": "linearalgebra::BaseMatrix *"
}
],
"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": "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": "parse",
"return_type": "void",
"params": [
{
"name": "arg",
"type": "sofa::core::objectmodel::BaseObjectDescription *"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
}
]
},
"desc": {
"description": "The `DiagonalMass` component in the SOFA framework is designed to compute a lumped (diagonalized) mass matrix by integrating a density over a domain's volume. This mass computation assumes that the mass matrix is diagonal, simplifying subsequent calculations and interactions within the simulation. The component can handle different types of geometries and state data through its template parameters, allowing for flexibility in representing rigid or vectorial objects.\n\n**Role and Purpose:**\nThe `DiagonalMass` facilitates the efficient computation of mass properties by assuming a diagonal structure for the mass matrix. This simplification enables faster numerical operations while still providing an accurate representation of physical behavior within the simulation context. The component is essential for simulating interactions involving forces, momentum, and energy calculations that depend on mass distributions.\n\n**Interactions with Other Components:**\nThe `DiagonalMass` interacts primarily through its API to receive geometry information from linked components such as `MechanicalObject`, which provides the state and position data. The component also links with a topology container (`BaseMeshTopology`) for topological information regarding vertices, edges, triangles, etc., enabling it to calculate mass distributions based on geometric shapes and their associated densities.\n\n**Usage Guidance:**\nThe main data fields of `DiagonalMass` include:\n- **massDensity**: A real number representing the density used for calculating vertex masses; defaults or wrong values are overridden by totalMass settings.\n- **totalMass**: The overall mass, defaulting to 1.0 if unspecified.\n- **computeMassOnRest**: Indicates whether mass should be computed based on rest positions instead of current ones.\n- **showCenterOfGravity**: Enables the display of the system's center of gravity.\n- **showAxisSizeFactor**: Adjusts the scale factor for displayed axes, relevant for rigid object visualization.\n\nAdditionally, it can link to a topology container and a MechanicalObject associated with geometry, ensuring correct behavior during initialization."
},
"maths": {
"maths": "# Mathematical and Physical Description of DiagonalMass Component\n\n## Overview\nThe `DiagonalMass` component in the SOFA framework is designed to compute a lumped (diagonalized) mass matrix by integrating density over the volume or area of the domain. This simplification assumes that the mass distribution can be represented as a diagonal matrix, which significantly reduces the computational complexity for dynamic simulations involving forces and inertia.\n\n## Mathematical Formulation\nThe primary role of `DiagonalMass` is to compute vertex masses based on the specified density and geometric properties of the object being simulated. The mathematical formulation involves integrating the mass density over the volume or area elements corresponding to each vertex.\n\n### Mass Computation\nGiven a domain discretized into vertices, edges, faces (triangles), or tetrahedra, the `DiagonalMass` component calculates the lumped masses for each vertex. This is achieved by summing contributions from surrounding geometric entities such as triangles and tetrahedra.\n\n#### Triangular Elements:\nThe mass contribution from a triangular element to its vertices can be computed using barycentric coordinates or area-based methods, often leading to equal distribution among the three vertices of the triangle.\n\n\begin{align}\n m_i^{triangle} &= \\frac{\text{Area of Triangle}}{3}\\times\\rho \\\\\n\\end{align}\n\nWhere $m_i^{triangle}$ is the mass contribution to vertex $i$ from a triangular element, and $\rho$ is the specified density.\n\n#### Tetrahedral Elements:\nThe mass contribution for tetrahedra involves a similar approach but may also consider higher-order approximations or weighted contributions based on proximity. The total mass at each vertex is the sum of all contributing elements' masses.\n\n\begin{align}\n m_i^{tetrahedron} &= \\frac{\text{Volume of Tetrahedron}}{4}\\times\\rho \\\\\n\\end{align}\n\nWhere $m_i^{tetrahedron}$ is the mass contribution to vertex $i$ from a tetrahedral element, and $\rho$ is the specified density.\n\n### Total Mass Calculation\nThe total lumped mass at each vertex ($m_i$) is calculated as follows:\n\begin{align}\n m_i &= \\sum_{j=1}^{N_t}(m_i^{triangle}) + \\sum_{k=1}^{N_v}(m_i^{tetrahedron}) \\\\\n\\end{align}\n\nWhere $N_t$ and $N_v$ represent the number of triangles and tetrahedra, respectively, contributing to vertex $i$. The total mass of the system is then given by:\n\begin{align}\n M_{total} &= \\sum_{i=1}^{N}(m_i) \\\\\n\\end{align}\n\nWhere $N$ is the total number of vertices.\n\n## Physical Interpretation\nIn physical terms, `DiagonalMass` simplifies mass distribution by assuming that each vertex carries its own lumped mass. This approach is particularly useful for simulations where the detailed spatial distribution of mass can be approximated as concentrated at discrete points (vertices).\n\n### Gravity and Inertial Forces\nThe component also handles gravitational forces and inertial forces in the simulation. The gravity force $\textbf{F}_g$ acting on each vertex $i$ is calculated as:\n\begin{align}\n \textbf{F}_{gi} &= m_i \\cdot \textbf{g} \\\\\n\\end{align}\n\nWhere $\textbf{g}$ is the gravity vector. The `DiagonalMass` adds this gravitational force to each vertex's velocity during the simulation update step.\n\n### Center of Gravity Calculation\nThe center of gravity (COG) of the system can be computed as a weighted average of all vertices' positions:\n\begin{align}\n \textbf{COG} &= \\frac{1}{M_{total}}\\sum_{i=1}^{N}(m_i \\cdot \textbf{x}_i) \\\\\n\\end{align}\n\nWhere $\textbf{x}_i$ is the position of vertex $i$. The COG can be visualized in the simulation to aid in understanding the object's balance and movement.\n\n## Conclusion\nThe `DiagonalMass` component provides a computationally efficient method for lumped mass calculations, making it suitable for real-time dynamic simulations. By assuming a diagonal mass matrix, complex interactions involving forces and inertia can be simplified while maintaining accurate physical behavior."
},
"summary": {
"abstract": "The `DiagonalMass` computes a lumped (diagonalized) mass matrix by integrating density over the domain's volume, simplifying subsequent calculations within the simulation.",
"sheet": "<h1>DiagonalMass</h1>\n\n<h2>Overview</h2>\n<p>The <code>DiagonalMass</code> component computes a lumped (diagonalized) mass matrix by integrating density over the domain's volume. This simplification assumes that the mass distribution can be represented as a diagonal matrix, which significantly reduces computational complexity for dynamic simulations involving forces and inertia.</p>\n\n<h2>Mathematical Model</h2>\n<p>The primary role of <code>DiagonalMass</code> is to compute vertex masses based on specified density and geometric properties. The mass computation involves integrating the mass density over the volume or area elements corresponding to each vertex.</p>\n\n<ul>\n<li><strong>Triangular Elements:</strong>\n\\[ m_i^{triangle} = \\frac{\\text{Area of Triangle}}{3} \\times \\rho \\]\nWhere $m_i^{triangle}$ is the mass contribution to vertex $i$ from a triangular element, and $\\rho$ is the specified density.</li>\n\n<li><strong>Tetrahedral Elements:</strong>\n\\[ m_i^{tetrahedron} = \\frac{\\text{Volume of Tetrahedron}}{4} \\times \\rho \\]\nWhere $m_i^{tetrahedron}$ is the mass contribution to vertex $i$ from a tetrahedral element, and $\\rho$ is the specified density.</li>\n</ul>\n\n<p>The total lumped mass at each vertex ($m_i$) is calculated as follows:\n\\[ m_i = \\sum_{j=1}^{N_t}(m_i^{triangle}) + \\sum_{k=1}^{N_v}(m_i^{tetrahedron}) \\]\nWhere $N_t$ and $N_v$ represent the number of triangles and tetrahedra, respectively, contributing to vertex $i$. The total mass of the system is then given by:\n\\[ M_{total} = \\sum_{i=1}^{N}(m_i) \\]\nWhere $N$ is the total number of vertices.</p>\n\n<h2>Parameters and Data</h2>\n<table>\n<thead>\n<tr>\n<th>Name</th>\n<th>Type</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>massDensity</code></td>\n<td><code>Real</code></td>\n<td>Density used for calculating vertex masses; defaults or wrong values are overridden by totalMass settings.</td>\n</tr>\n<tr>\n<td><code>totalMass</code></td>\n<td><code>Real</code></td>\n<td>The overall mass, defaulting to 1.0 if unspecified.</td>\n</tr>\n<tr>\n<td><code>computeMassOnRest</code></td>\n<td><code>bool</code></td>\n<td>Indicates whether mass should be computed based on rest positions instead of current ones.</td>\n</tr>\n<tr>\n<td><code>showCenterOfGravity</code></td>\n<td><code>bool</code></td>\n<td>Enables the display of the system's center of gravity.</td>\n</tr>\n<tr>\n<td><code>showAxisSizeFactor</code></td>\n<td><code>float</code></td>\n<td>Adjusts the scale factor for displayed axes, relevant for rigid object visualization.</td>\n</tr>\n</tbody>\n</table>\n\n<h2>Dependencies and Connections</h2>\n<p>The <code>DiagonalMass</code> component links to a topology container (<code>BaseMeshTopology</code>) for topological information regarding vertices, edges, triangles, etc., enabling it to calculate mass distributions based on geometric shapes and their associated densities. It also interacts with the <code>MechanicalObject</code> associated with geometry to receive state and position data.</p>\n\n<h2>Practical Notes</h2>\n<p>The component assumes a diagonal structure for the mass matrix, which simplifies numerical operations but may introduce approximations in certain scenarios. Ensure that the specified density or total mass is appropriate for the simulation context to maintain physical accuracy.</p>"
}
}