Data Fields

Methods

{
  "name": "BaseMass",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/BaseMass.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 often also a ForceField, computing gravity-related forces.",
  "inherits": [],
  "templates": [],
  "data_fields": [
    {
      "name": "m_separateGravity",
      "type": "bool",
      "xmlname": "separateGravity",
      "help": "add separately gravity to velocity computation"
    },
    {
      "name": "rayleighMass",
      "type": "SReal",
      "xmlname": "rayleighMass",
      "help": "Rayleigh damping - mass matrix coefficient"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "toBaseMass",
      "return_type": "const BaseMass *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMDx",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "fid",
          "type": "MultiVecDerivId"
        },
        {
          "name": "factor",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "accFromF",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "aid",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addGravityToV",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "vid",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getKineticEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMomentum",
      "return_type": "type::Vec6",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildMassMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrices",
          "type": "sofa::core::behavior::MassMatrixAccumulator *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initGnuplot",
      "return_type": "void",
      "params": [
        {
          "name": "path",
          "type": "const int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "exportGnuplot",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "time",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getElementMass",
      "return_type": "SReal",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getElementMass",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "int"
        },
        {
          "name": "m",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isDiagonal",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "insertInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": {
    "componentName": "BaseMass",
    "namespace": "sofa::core::behavior",
    "responsibility": "Component responsible for mass-related computations, including gravity and acceleration.",
    "massDefinitions": [
      {
        "type": "scalar"
      },
      {
        "type": "vector"
      },
      {
        "type": "full mass-matrix"
      }
    ],
    "functions": [
      {
        "name": "addMDx",
        "description": "Compute force as f += factor * M * dx, where M is the mass matrix.",
        "parameters": [
          "MechanicalParams* mparams",
          "MultiVecDerivId fid",
          "SReal factor"
        ]
      },
      {
        "name": "accFromF",
        "description": "Compute acceleration from force as dx = M^-1 * f.",
        "parameters": [
          "MechanicalParams* mparams",
          "MultiVecDerivId aid"
        ]
      },
      {
        "name": "addGravityToV",
        "description": "Update velocity by adding gravity to it (v += dt*g).",
        "parameters": [
          "MechanicalParams* mparams",
          "MultiVecDerivId vid"
        ]
      },
      {
        "name": "getKineticEnergy",
        "description": "Compute kinetic energy as vMv/2.",
        "parameters": [
          "MechanicalParams* mparams"
        ]
      },
      {
        "name": "getPotentialEnergy",
        "description": "Compute potential energy as Mgx.",
        "parameters": [
          "MechanicalParams* mparams"
        ]
      },
      {
        "name": "getMomentum",
        "description": "Compute momentum (linear and angular) as (Mv, xMv+Iw).",
        "parameters": [
          "MechanicalParams* mparams"
        ]
      },
      {
        "name": "addMToMatrix",
        "description": "Add mass contribution to the global matrix assembly.",
        "parameters": [
          "MechanicalParams* mparams",
          "MultiMatrixAccessor* matrix"
        ]
      },
      {
        "name": "buildMassMatrix",
        "description": "Construct and accumulate the mass matrix.",
        "parameters": [
          "sofa::core::behavior::MassMatrixAccumulator* matrices"
        ]
      },
      {
        "name": "initGnuplot",
        "description": "Initialize gnuplot export for kinetic and potential energy.",
        "parameters": [
          "std::string path"
        ]
      },
      {
        "name": "exportGnuplot",
        "description": "Export kinetic and potential energy state to a gnuplot file at specified time.",
        "parameters": [
          "MechanicalParams* mparams",
          "SReal time"
        ]
      },
      {
        "name": "getElementMass",
        "description": [
          "Get mass relative to the degree of freedom (DOF) at index.",
          "Get matrix relative to the DOF at index."
        ],
        "parameters": [
          "sofa::Index index",
          "linearalgebra::BaseMatrix *m"
        ]
      },
      {
        "name": "isDiagonal",
        "description": "Check if the mass matrix is diagonal.",
        "parameters": []
      }
    ],
    "dataMembers": [
      {
        "name": "m_separateGravity",
        "type": "Data<bool>",
        "description": "Specify whether gravity should be added separately to DOF velocities or with other forces."
      },
      {
        "name": "rayleighMass",
        "type": "Data<SReal>",
        "description": "Coefficient for Rayleigh damping in the mass matrix."
      }
    ],
    "methods": [
      {
        "name": "insertInNode",
        "description": "Insert this component into a node, adding its mass.",
        "parameters": [
          "objectmodel::BaseNode* node"
        ]
      },
      {
        "name": "removeInNode",
        "description": "Remove this component from a node, removing its mass.",
        "parameters": [
          "objectmodel::BaseNode* node"
        ]
      }
    ],
    "deprecationNotice": "The deprecated API method `addMToMatrix` is used for compatibility reasons and will be replaced by the new `buildMassMatrix`. This change ensures better simulation behavior in the future."
  },
  "maths": "### Mathematical and Physical Description of the BaseMass Component\n\nThe **BaseMass** component in the SOFA framework is central to handling mass-related computations, including gravity and acceleration. It can define mass as a scalar, vector, or full mass matrix $M$, which plays a crucial role in converting forces into accelerations for explicit integrators and displacements into forces for implicit integrators.\n\n#### Vector Operations\n\n1. **Force Calculation (addMDx):** \n   The component computes the force $f$ using the equation:\n   \\[\n   f += factor \times M \times dx\n   \\]\n   where $dx$ is the change in displacement and `factor` is a scalar multiplier.\n\n2. **Acceleration from Force (accFromF):**\n   The acceleration $a$ can be obtained by solving for $dx$ using:\n   \\[\n   dx = M^{-1} f\n   \\]\n   Here, $M^{-1}$ represents the inverse of the mass matrix.\n\n3. **Gravity Addition (addGravityToV):**\n   The velocity $v$ is updated by adding gravity $g$ over a time step $dt$: \n   \\[\n   v += dt \times g\n   \\]\n   This method allows for separate addition of gravity to the velocities.\n\n4. **Kinetic Energy (getKineticEnergy):**\n   Kinetic energy is computed as:\n   \\[\n   KE = \\frac{1}{2} v^T M v\n   \\]\n   where $v$ is the velocity vector and $M$ is the mass matrix.\n\n5. **Potential Energy (getPotentialEnergy):**\n   Potential energy due to gravity is given by:\n   \\[\n   PE = Mgx\n   \\]\n   Here, $g$ is the gravitational acceleration, $x$ is the displacement vector, and $M$ is the mass matrix.\n\n6. **Linear and Angular Momentum (getMomentum):**\n   The total momentum $(p)$ of a system considering both linear and angular contributions can be computed as:\n   \\[\n   p = Mv + Iw\n   \\]\n   where $I$ is the moment of inertia, $w$ is the angular velocity vector, and $Mv$ represents the linear momentum.\n\n#### Matrix Operations\n\n1. **Matrix Assembly (addMToMatrix):**\n   The component adds the mass contribution to a global matrix $A$ for assembling the system of equations as follows:\n   \\[\n   A += mFactor \times M\n   \\]\n   Here, `mparams->mFactor()` is a coefficient associated with second-order derivatives (mass) in the ODE.\n\n2. **Build Mass Matrix:**\n   The method constructs and accumulates the mass matrix $M$, which is essential for solving systems of equations involving forces and displacements.\n\n#### Initialization and Export Functions\n\n1. **Gnuplot Initialization (initGnuplot):**\n   This function initializes gnuplot file formats to export kinetic and potential energy states.\n\n2. **Export Data (exportGnuplot):**\n   Exports the state of kinetic and potential energies at a given time $t$ to a gnuplot file for visualization purposes.\n\n#### Degree-of-Freedom Operations\n\n1. **Get Element Mass:** \n   Retrieves mass associated with a specific degree of freedom (DOF) index:\n   \\[\n   m = M_{ii}\n   \\]\n   where $i$ is the DOF index and $M_{ii}$ is the corresponding diagonal element in the mass matrix.\n\n2. **Get Element Mass Matrix:**\n   Retrieves the full mass submatrix associated with a specific DOF:\n   \\[\n   M_i = M[rows, cols]\n   \\]\n   Here, `rows` and `cols` are the indices corresponding to the DOF.\n\n#### Diagonal Check (isDiagonal):**\n   This function checks whether the mass matrix $M$ is diagonal, which simplifies computations if true:\n   \\[\n   M_{ij} = 0 \\quad for\\ all \\quad i \\neq j\n   \\]\n\n### Data Members and Methods\n\n- **m_separateGravity:** A boolean `Data<bool>` indicating whether gravity should be added separately to velocities or included with other forces.\n- **rayleighMass:** A scalar coefficient $\\alpha$ for Rayleigh damping in the mass matrix. The damping force is given by:\n  \\[\n  F_d = -\\alpha Mv\n  \\]\n\n- **insertInNode/removeInNode:** Methods to insert or remove the component's mass from a node, facilitating dynamic management within the simulation framework.",
  "abstract": "The BaseMass component manages mass-related computations in SOFA simulations, including gravity and acceleration calculations, kinetic and potential energy computation, and matrix assembly.",
  "sheet": "# BaseMass\n\n## Overview\nBaseMass is a core behavior component responsible for handling mass-related computations such as gravity, acceleration, and force conversions. It supports scalar, vector, or full mass-matrix definitions.\n\n## Mathematical Model\nThe mathematical model of the `BaseMass` component includes several key operations:\n\n1. **Force Calculation (addMDx):**\n   \\\\[ f += factor \\times M \\times dx \\\\]\n2. **Acceleration from Force (accFromF):**\n   \\\\[ dx = M^{-1} f \\\\]\n3. **Gravity Addition (addGravityToV):**\n   \\\\[ v += dt \\times g \\\\]\n4. **Kinetic Energy (getKineticEnergy):**\n   \\\\[ KE = \\frac{1}{2} v^T M v \\\\]\n5. **Potential Energy (getPotentialEnergy):**\n   \\\\[ PE = Mgx \\\\]\n6. **Linear and Angular Momentum (getMomentum):**\n   \\\\[ p = Mv + Iw \\\\]\n7. **Matrix Assembly (addMToMatrix):**\n   \\\\[ A += mFactor \\times M \\\\]\n8. **Build Mass Matrix:** Constructs and accumulates the mass matrix $M$.\n\n## Parameters and Data\n- `m_separateGravity` (`bool`): Indicates whether gravity should be added separately to velocities or included with other forces.\n- `rayleighMass` (`SReal`): Coefficient for Rayleigh damping in the mass matrix, given by:\n   \\\\[ F_d = -\\alpha Mv \\\\]\n\n## Practical Notes\nConfiguration caveats include ensuring that gravity is properly accounted for when using separateGravity. Additionally, Rayleigh damping should be carefully tuned to avoid numerical instability."
}