Methods

{
  "name": "MechanicalAddMBK_ToMatrixVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalAddMBK_ToMatrixVisitor.h",
  "doc": "Accumulate the entries of a mechanical matrix (mass or stiffness) of the whole scene */",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdForceField",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "ff",
          "type": "core::behavior::BaseForceField *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalAddMBK_ToMatrixVisitor` is a component in the SOFA framework designed to accumulate entries of mechanical matrices (mass or stiffness) for the entire scene. It inherits from the `MechanicalVisitor` class and operates within the simulation mechanics pipeline.\n\n### Role and Purpose:\nThe primary purpose of this visitor is to aggregate mass, damping, and stiffness contributions from all relevant force fields across the whole simulation scene into a single mechanical matrix. This visitor facilitates efficient assembly of global system matrices which are critical for solving equations of motion in finite element simulations and other mechanical models.\n\n### Interactions with Other Components:\nThe `MechanicalAddMBK_ToMatrixVisitor` interacts with various SOFA components through its API methods:\n- **fwdMechanicalState**: This method is called at each mechanical state during the forward pass, but it does not modify the state directly and simply returns a result indicating that processing should continue.\n- **fwdForceField**: It accumulates contributions from individual force fields by calling their `addMBKToMatrix` method. The visitor passes its internal `MultiMatrixAccessor`, which is used to store mass (M), damping (B), and stiffness (K) matrix entries.\n- **stopAtMechanicalMapping**: This method determines whether the traversal should stop at a mechanical mapping node, based on whether matrices are mapped or not. If they are not mapped, processing continues.\n\n### Practical Usage:\nThe visitor is typically used in conjunction with force fields and mappings to assemble global system matrices for solving dynamics problems within SOFA simulations. The component relies on internal `MultiMatrixAccessor` objects to store the accumulated matrix entries.\n\n### Data Fields:\nThe component maintains a pointer to a `MultiMatrixAccessor`, which it uses to accumulate mechanical matrix entries from various force fields throughout the scene.",
  "maths": "The `MechanicalAddMBK_ToMatrixVisitor` is a key component in the SOFA framework designed to accumulate contributions from various force fields into global mass (M), damping (B), and stiffness (K) matrices for solving mechanical systems. This visitor plays a critical role in assembling these matrices across the entire simulation scene, ensuring that all relevant contributions are properly accounted for.\n\n### Governing Equations and Operators:\n- **Mass Matrix (\\(M\\)])**: The mass matrix encodes the distribution of mass within the deformable object, often derived from the kinetic energy term. Each entry in this matrix represents a contribution to the overall inertial behavior of the system. In FEM terms, the mass matrix is assembled element-wise and then aggregated across the entire scene.\n- **Damping Matrix (\\(B\\)])**: The damping matrix encodes viscous or hysteretic dissipation effects. Similar to the mass matrix, each entry in this matrix represents a contribution from individual force fields that model dissipative behavior.\n- **Stiffness Matrix (\\(K\"]]**: The stiffness matrix encodes the elastic response of materials and is derived from the potential energy term. Each element-wise stiffness contribution is aggregated into the global stiffness matrix to represent the overall elastic behavior of the system.\n\n### Constitutive or Kinematic Laws:\n- This component does not directly implement constitutive laws but rather accumulates contributions from force fields that do so, such as linear elasticity or hyperelastic material models. The specific form of these contributions depends on the underlying physics and material properties defined in each force field.\n\n### Role in the FEM Pipeline:\n- **Assembly Phase**: During the assembly phase, this visitor iterates over all mechanical states and force fields to accumulate their mass, damping, and stiffness contributions into a single set of matrices. This is achieved through method calls like `fwdForceField`, where each force field's `addMBKToMatrix` function is invoked.\n\n### Numerical Methods or Discretization Choices:\n- The visitor operates on discrete entities (force fields) within the scene graph, leveraging finite element discretizations to accumulate contributions from individual elements into global matrices. This process ensures that the resulting system of equations is consistent with variational mechanics principles.\n\n### Variational / Lagrangian Mechanics Framework:\n- From a broader perspective, this visitor supports the variational framework by ensuring that all relevant energetic terms (kinetic energy for mass, dissipation for damping, and potential energy for stiffness) are correctly accounted for in the global system matrices. This alignment with the variational principles ensures numerical stability and physical consistency in the simulation.\n\nIn summary, `MechanicalAddMBK_ToMatrixVisitor` facilitates the efficient assembly of global mechanical matrices by aggregating contributions from force fields across the entire scene, thereby enabling the solution of complex mechanical systems within the SOFA framework.",
  "abstract": "The `MechanicalAddMBK_ToMatrixVisitor` accumulates mass (M), damping (B), and stiffness (K) matrix entries from all force fields in the scene to assemble global mechanical matrices for solving equations of motion.",
  "sheet": "# MechanicalAddMBK_ToMatrixVisitor\n\n## Overview\nThe `MechanicalAddMBK_ToMatrixVisitor` is a visitor component that aggregates mass, damping, and stiffness contributions from various force fields across the entire simulation scene into a single set of global mechanical matrices. This visitor facilitates efficient assembly of these matrices for solving equations of motion in finite element simulations.\n\n## Mathematical Model\nThe `MechanicalAddMBK_ToMatrixVisitor` accumulates entries of the mass (\\(M\"]), damping (\\(B\"]), and stiffness (\\(K\"]) matrices from all relevant force fields. Each entry represents contributions to the overall inertial, dissipative, and elastic behavior of the system.\n- **Mass Matrix (\\(M\"))**: Encodes the distribution of mass within the deformable object, derived from kinetic energy terms.\n- **Damping Matrix (\\(B\"))**: Encodes viscous or hysteretic dissipation effects, representing contributions to dissipative behavior.\n- **Stiffness Matrix (\\(K\"))**: Encodes elastic response of materials, derived from potential energy terms.\n\n## Dependencies and Connections\nThe `MechanicalAddMBK_ToMatrixVisitor` interacts with various SOFA components through its API methods:\n- **fwdMechanicalState**: Called at each mechanical state during the forward pass to continue processing without modifying the state directly.\n- **fwdForceField**: Accumulates contributions from individual force fields by calling their `addMBKToMatrix` method, using an internal `MultiMatrixAccessor` to store matrix entries.\n- **stopAtMechanicalMapping**: Determines whether traversal should stop at a mechanical mapping node based on whether matrices are mapped or not."
}