Methods

{
  "name": "Mass",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/Mass.h",
  "doc": "Component responsible for mass-related computations (gravity, acceleration).\n Mass can be defined either as a scalar, vector, or a full mass-matrix.\n It is responsible for converting forces to accelerations (for explicit integrators),\n or displacements to forces (for implicit integrators).\n It is also a ForceField, computing gravity-related forces.",
  "inherits": [
    "BaseMass",
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "Mass",
      "description": "Constructor for `Mass` component. Optionally takes a `MechanicalState` object as an argument.",
      "arguments": [
        {
          "type": "MechanicalState<DataTypes>",
          "name": "mm",
          "optional": true,
          "default_value": "nullptr"
        }
      ]
    },
    {
      "name": "~Mass",
      "description": "Destructor for `Mass` component."
    },
    {
      "name": "addMDx",
      "description": "Adds the mass matrix multiplied by a vector to another vector. Retrieves force and displacement vectors, calls internal method.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "MultiVecDerivId",
          "name": "fid"
        },
        {
          "type": "SReal",
          "name": "factor"
        }
      ]
    },
    {
      "name": "addMDx",
      "description": "Virtual method to add mass matrix times displacement vector to force vector, multiplied by a scalar factor.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "DataVecDeriv&",
          "name": "f"
        },
        {
          "type": "const DataVecDeriv&",
          "name": "dx"
        },
        {
          "type": "SReal",
          "name": "factor"
        }
      ]
    },
    {
      "name": "accFromF",
      "description": "Computes acceleration from force vector using the inverse of the mass matrix. Retrieves acceleration and force vectors, calls internal method.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "MultiVecDerivId",
          "name": "aid"
        }
      ]
    },
    {
      "name": "accFromF",
      "description": "Virtual method to compute acceleration from force vector using the inverse of the mass matrix.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "DataVecDeriv&",
          "name": "a"
        },
        {
          "type": "const DataVecDeriv&",
          "name": "f"
        }
      ]
    },
    {
      "name": "addDForce",
      "description": "Adds the derivative of forces due to mass (gravity). Typically empty for `Mass`.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "DataVecDeriv&",
          "name": "df"
        },
        {
          "type": "const DataVecDeriv&",
          "name": "dx"
        }
      ]
    },
    {
      "name": "addMBKdx",
      "description": "Accumulates the contributions of M (mass), B (damping) and K (stiffness) matrices multiplied by a displacement vector.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "MultiVecDerivId",
          "name": "dfId"
        }
      ]
    },
    {
      "name": "getKineticEnergy",
      "description": "Calculates the kinetic energy using velocity vector and mass matrix. Retrieves velocity vector, calls internal method.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        }
      ],
      "return_type": "SReal"
    },
    {
      "name": "getKineticEnergy",
      "description": "Virtual method to calculate kinetic energy using the given velocity vector and mass matrix.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "const DataVecDeriv&",
          "name": "v"
        }
      ],
      "return_type": "SReal"
    },
    {
      "name": "getPotentialEnergy",
      "description": "Calculates the potential energy using position vector and gravity. Retrieves positions vector, calls internal method.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        }
      ],
      "return_type": "SReal"
    },
    {
      "name": "getPotentialEnergy",
      "description": "Virtual method to calculate the potential energy using the given position vector and gravity.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "const DataVecCoord&",
          "name": "x"
        }
      ],
      "return_type": "SReal"
    },
    {
      "name": "getMomentum",
      "description": "Calculates the momentum using position and velocity vectors. Retrieves positions and velocities, calls internal method.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        }
      ],
      "return_type": "type::Vec6"
    },
    {
      "name": "getMomentum",
      "description": "Virtual method to calculate the momentum using given position and velocity vectors.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "unused_mparams"
        },
        {
          "type": "const DataVecCoord&",
          "name": "x"
        },
        {
          "type": "const DataVecDeriv&",
          "name": "v"
        }
      ],
      "return_type": "type::Vec6"
    },
    {
      "name": "addMToMatrix",
      "description": "Adds the mass matrix to a given matrix, scaled by a factor.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "sofa::core::behavior::MultiMatrixAccessor*",
          "name": "matrix"
        }
      ]
    },
    {
      "name": "addMToMatrix",
      "description": "Virtual method to add the mass matrix scaled by a factor to a given matrix.",
      "arguments": [
        {
          "type": "sofa::linearalgebra::BaseMatrix*",
          "name": "matrix"
        },
        {
          "type": "SReal",
          "name": "mFact"
        },
        {
          "type": "unsigned int&",
          "name": "offset"
        }
      ]
    },
    {
      "name": "addMBKToMatrix",
      "description": "Computes the system matrix corresponding to m M + b B + k K, where M is mass, B is damping and K is stiffness matrices.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "sofa::core::behavior::MultiMatrixAccessor*",
          "name": "matrix"
        }
      ]
    },
    {
      "name": "initGnuplot",
      "description": "Initializes the export of kinetic and potential energy to gnuplot files with a given path.",
      "arguments": [
        {
          "type": "const std::string",
          "name": "path"
        }
      ]
    },
    {
      "name": "exportGnuplot",
      "description": "Exports the current state of kinetic and potential energy at 'time' to a gnuplot file using provided MechanicalParams.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "SReal",
          "name": "time"
        }
      ]
    },
    {
      "name": "addGravityToV",
      "description": "Adds gravity to velocity vector, used if mass wants to add G separately from other forces.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "MultiVecDerivId",
          "name": "vid"
        }
      ]
    },
    {
      "name": "addGravityToV",
      "description": "Virtual method to add gravity to velocity vector using provided MechanicalParams.",
      "arguments": [
        {
          "type": "const MechanicalParams*",
          "name": "mparams"
        },
        {
          "type": "DataVecDeriv&",
          "name": "d_v"
        }
      ]
    },
    {
      "name": "getElementMass",
      "description": "Retrieves the mass of a specific element.",
      "arguments": [
        {
          "type": "sofa::Index",
          "name": "index"
        }
      ],
      "return_type": "SReal"
    },
    {
      "name": "getElementMass",
      "description": "Virtual method to retrieve the mass matrix for an element at given index.",
      "arguments": [
        {
          "type": "sofa::Index",
          "name": "index"
        },
        {
          "type": "linearalgebra::BaseMatrix*",
          "name": "m"
        }
      ]
    },
    {
      "name": "insertInNode",
      "description": "Inserts this component into a base node, ensuring proper registration.",
      "arguments": [
        {
          "type": "objectmodel::BaseNode*",
          "name": "node"
        }
      ],
      "return_type": "bool"
    },
    {
      "name": "removeInNode",
      "description": "Removes this component from a base node, ensuring proper deregistration.",
      "arguments": [
        {
          "type": "objectmodel::BaseNode*",
          "name": "node"
        }
      ],
      "return_type": "bool"
    }
  ],
  "description": "The `Mass` component is part of the SofaPhysics framework and represents mass properties for physical simulations. It serves as both a force field, computing gravity-related forces, and a mass matrix contributor in the system's dynamics.",
  "parameters": [
    {
      "name": "m_gnuplotFileEnergy",
      "description": "Stream to export Kinetic, Potential and Mechanical Energy to gnuplot files."
    }
  ],
  "maths": "The `Mass` component in the SofaPhysics framework is responsible for mass-related computations, including gravity and acceleration. It can define mass either as a scalar, vector, or full mass matrix and plays a crucial role in converting forces to accelerations (for explicit integrators) and displacements to forces (for implicit integrators). Additionally, it acts as a `ForceField`, computing gravity-related forces. Below is the detailed mathematical and physical description of this component.\n\n### Governing Equations\n\n#### Mass Matrix Contributions\nThe mass matrix $M$ represents the inertial properties of the system and relates force to acceleration through the relation:\n\begin{align*}\n\\mathbf{f} = M \\mathbf{a}\n\\end{align*}\nwhere $\\mathbf{f}$ is the force vector, and $\\mathbf{a}$ is the acceleration vector. For implicit integrators, this can be expressed as:\n\begin{align*}\nM \frac{\text{d}^2 \textbf{x}}{\text{d} t^2} = \\mathbf{f},\n\\end{align*}\nwhere $\\textbf{x}$ is the displacement vector.\n\n#### Kinetic Energy Contribution\nThe kinetic energy $E_k$ associated with the mass matrix can be computed as:\n\begin{align*}\nE_k = \frac{1}{2} \\mathbf{v}^T M \\mathbf{v},\n\\end{align*}\nwhere $\\mathbf{v}$ is the velocity vector.\n\n#### Potential Energy Contribution (Gravity)\nThe potential energy due to gravity can be expressed as:\n\begin{align*}\nE_p = -M \textbf{g} \\cdot \\textbf{x},\n\\end{align*}\nwhere $\\textbf{g}$ is the gravitational acceleration vector, and $\\textbf{x}$ is the displacement vector.\n\n### Numerical Methods and Discretization Choices\n- **Spatial Discretization**: The mass matrix $M$ is computed based on the nodal masses of the discretized system. This component supports both scalar (uniform mass), vector (different mass per node), and full matrix forms, depending on the specific use case.\n\n- **Time Integration**: For explicit integrators, forces are converted to accelerations using the inverse of the mass matrix:\n\begin{align*}\n\\mathbf{a} = M^{-1} \\mathbf{f},\n\\end{align*}\nwhereas for implicit integrators, the force and displacement relationship is maintained in the form $M \\frac{\text{d}^2 \textbf{x}}{\text{d} t^2}$.\n\n### Role in Global FEM Pipeline\nThe `Mass` component contributes to the global FEM pipeline by providing mass-related computations essential for accurate simulations:\n- **Assembly**: It assembles the contributions of $M$ into the global system matrix during both explicit and implicit integrations.\n- **Time Integration**: In implicit schemes, it handles the conversion of forces to accelerations or displacements to forces, which is crucial for stability and accuracy.\n- **Nonlinear Solution**: During nonlinear solves, it ensures that mass-related contributions are correctly accounted for in the residual and Jacobian evaluations.\n- **Linear Solve**: It contributes to the linear system solution by providing necessary terms related to the mass matrix $M$.\n\n### Constraints and Mappings\nThe `Mass` component also supports constraints and mappings:\n- **Gravity Force Application**: Gravity-related forces are computed as part of its role as a `ForceField`, where it applies gravity forces to the system.\n\n### Variational Mechanics Framework\nIn the broader variational mechanics framework, the `Mass` component fits into the Lagrangian formulation by providing mass-based kinetic energy and potential energy contributions. It ensures that inertial effects are correctly included in the simulation through its role as both a force field and a contributor to the system's dynamics.\n\n### Summary\nThe `Mass` component is critical for simulating dynamic systems within SofaPhysics, ensuring accurate computation of forces, accelerations, kinetic energies, and potential energies due to gravity. It supports various mass definitions (scalar, vector, matrix) and integrates seamlessly into both explicit and implicit time integration schemes.",
  "abstract": "The `Mass` component manages mass-related computations in SOFA simulations, including force-to-acceleration conversion for explicit integrators and displacement-to-force conversion for implicit integrators. It also computes gravity forces as a `ForceField`.",
  "sheet": "# Mass\n\n## Overview\nThe `Mass` component is responsible for mass-related computations in SOFA simulations, handling both explicit and implicit time integration schemes. As part of the `BaseMass` and `ForceField` classes, it converts forces to accelerations (for explicit integrators) and displacements to forces (for implicit integrators). It also computes gravity-related forces.\n\n## Mathematical Model\nThe mass matrix $M$ represents the inertial properties of the system. For explicit integrators, forces are converted to accelerations using:\n\\begin{align*}\n  \\mathbf{a} = M^{-1} \\mathbf{f},\n\\end{align*}\nwhere $\\mathbf{f}$ is the force vector and $\\mathbf{a}$ is the acceleration vector. For implicit integrators, the relationship between forces and displacements is maintained as:\n\\begin{align*}\n  M \\frac{d^2 \\textbf{x}}{dt^2} = \\mathbf{f},\n\\end{align*}\nwhere $\\textbf{x}$ is the displacement vector.\nThe kinetic energy $E_k$ associated with the mass matrix can be computed as:\n\\begin{align*}\n  E_k = \\frac{1}{2} \\mathbf{v}^T M \\mathbf{v},\n\\end{align*}\nwhere $\\mathbf{v}$ is the velocity vector. The potential energy due to gravity can be expressed as:\n\\begin{align*}\n  E_p = -M \\textbf{g} \\cdot \\textbf{x},\n\\end{align*}\nwhere $\\textbf{g}$ is the gravitational acceleration vector.\n\n## Parameters and Data\nThe `Mass` component does not expose any significant data fields. Its behavior is determined by its role in the simulation pipeline, specifically through its methods for force-to-acceleration conversion and gravity-related computations.\n\n## Dependencies and Connections\nThe `Mass` component typically requires connections to other components such as solvers (for implicit integrators) and mechanical state components (to provide forces and displacements). It fits into the scene graph by contributing to the global system matrix during both explicit and implicit time integration schemes.\n\n## Practical Notes\nFor numerical stability, ensure that the mass matrix $M$ is well-conditioned. In explicit integrations, avoid small masses to prevent large accelerations due to forces. For implicit integrators, ensure that the mass matrix is positive definite for stable solutions."
}