Methods

{
  "name": "MechanicalAddMBKdxVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalAddMBKdxVisitor.h",
  "doc": "Accumulate the product of the system matrix by a given vector.\nTypically used in implicit integration solved by a Conjugate Gradient algorithm.\nThe current value of the dx vector is used.\nThis action is typically called after a MechanicalPropagateDxAndResetForceVisitor.",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMappedMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::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": "sofa::core::behavior::BaseForceField *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdMechanicalMapping",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getInfos",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isThreadSafe",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalAddMBKdxVisitor` is a visitor in the SOFA framework, specifically designed to accumulate the product of the system matrix by a given vector. This action is typically used in implicit integration solved using a Conjugate Gradient algorithm and operates on the current value of the dx vector. The component interacts with other mechanical components through its virtual methods: `fwdMechanicalState`, `fwdMappedMechanicalState`, `fwdForceField`, `bwdMechanicalMapping`, and `bwdMechanicalState`. These methods allow it to traverse and modify the mechanical state across different nodes, mappings, and force fields in a simulation. The visitor is thread-safe and can be parallelized.\n\nIt includes data fields such as `res` (a MultiVecDerivId) for storing results, and a boolean flag `accumulate`, which specifies whether accumulation back to the degrees of freedom through mappings should occur.",
  "maths": "The `MechanicalAddMBKdxVisitor` is a visitor in the SOFA framework designed to accumulate the product of the system matrix by a given vector, typically used in implicit integration solved using a Conjugate Gradient algorithm. The primary role of this component is to contribute to the linear solve phase of the nonlinear solution process.\n\nMathematically, it operates on the following components:\n- **Mass Matrix (M)**: Represents the mass distribution across the system and contributes to the inertia term in dynamic simulations.\n- **Stiffness Matrix (K)**: Encodes the elastic properties of the material through constitutive laws such as Hooke's Law or hyperelastic potentials, contributing to the internal forces in deformable systems.\n- **Damping Matrix (B)**: Represents dissipative effects that are often used to stabilize simulations and model energy dissipation over time.\n\nThe visitor is involved in the following operations:\n- **Product of System Matrices**: It computes the product \\\\( M \\mathbf{x} + B \\dot{\\mathbf{x}} + K \\mathbf{x} \\\\) where \\\\(\\mathbf{x}\\) represents displacements, and \\(\\dot{\\mathbf{x}}\\) represents velocities.\n- **Accumulation of Contributions**: It accumulates the contributions from different force fields and mappings to compute the system residual or the right-hand side of linear systems during iterative solvers like Conjugate Gradient (CG).\n\nThe visitor interacts with various components in the SOFA simulation pipeline:\n- **Force Fields**: Calls `addMBKdx` on each `BaseForceField`, accumulating contributions from internal forces and stiffness terms.\n- **Mappings**: Uses backward passes (`bwdMechanicalMapping`) to accumulate contributions through mappings, which project forces between different levels of discretization or different parts of the system.\n\nThe visitor’s role in the global FEM pipeline is as follows:\n1. **Assembly Phase**: During this phase, it accumulates contributions from various force fields and mappings to construct the right-hand side of linear systems used in iterative solvers like CG.\n2. **Time Integration**: It operates after the `MechanicalPropagateDxAndResetForceVisitor`, typically during implicit integration schemes where the current value of the displacement increment \\\\( \\mathbf{dx} \\\\) is used to compute contributions to the linear system.\n3. **Nonlinear Solve and Linear Solve**: The visitor supports iterative solvers by accumulating contributions from different force fields and mappings, contributing to the solution of linear systems within each Newton iteration step.\n\nNumerical methods encoded in this component include:\n- **Conjugate Gradient (CG) Algorithm**: This is a common iterative solver used for large-scale symmetric positive definite problems. The visitor accumulates contributions needed by CG to solve these linear systems efficiently.\n\nThe `MechanicalAddMBKdxVisitor` fits into the broader variational/Lagrangian mechanics framework by contributing to the assembly of system matrices and force vectors, which are essential for solving the discretized weak form equations derived from the Lagrangian or Hamiltonian principles in continuum mechanics.",
  "abstract": "Accumulates contributions from force fields and mappings to construct the right-hand side of linear systems used in iterative solvers like Conjugate Gradient (CG).",
  "sheet": "\n# MechanicalAddMBKdxVisitor\n\n## Overview\nThe `MechanicalAddMBKdxVisitor` is a visitor component designed to accumulate contributions from various force fields and mappings to construct the right-hand side of linear systems used in iterative solvers like Conjugate Gradient (CG). It operates on the system matrices M, B, and K.\n\n## Mathematical Model\nThe `MechanicalAddMBKdxVisitor` accumulates the product of the system matrix by a given vector. Mathematically, it computes:\n\\[ M \\mathbf{x} + B \\dot{\\mathbf{x}} + K \\mathbf{x} \\]\nwhere \\(M\\) is the mass matrix, \\(B\\) is the damping matrix, and \\(K\\) is the stiffness matrix. The visitor accumulates contributions from different force fields and mappings to compute the system residual or the right-hand side of linear systems during iterative solvers like Conjugate Gradient (CG).\n\n## Parameters and Data\n- **res**: A `MultiVecDerivId` for storing results.\n- **accumulate**: A boolean flag specifying whether accumulation back to the degrees of freedom through mappings should occur.\n\n## Dependencies and Connections\nThe visitor interacts with various components in the SOFA simulation pipeline:\n- **Force Fields**: Calls `addMBKdx` on each `BaseForceField`, accumulating contributions from internal forces and stiffness terms.\n- **Mappings**: Uses backward passes (`bwdMechanicalMapping`) to accumulate contributions through mappings, which project forces between different levels of discretization or different parts of the system."
}