Methods

{
  "name": "MechanicalAddMDxVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalAddMDxVisitor.h",
  "doc": "Accumulate the product of the mass matrix by a given vector.\nTypically used in implicit integration solved by a Conjugate Gradient algorithm.\nNote that if a dx vector is given, it is used and propagated by the mappings, Otherwise the current value is used.",
  "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": "fwdMass",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mass",
          "type": "sofa::core::behavior::BaseMass *"
        }
      ],
      "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": "fwdMechanicalMapping",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMappedMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "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 `MechanicalAddMDxVisitor` is a visitor in the SOFA simulation framework, designed to accumulate the product of the mass matrix by a given vector. This operation is typically used in implicit integration methods solved using Conjugate Gradient algorithms. If a `dx` (displacement) vector is provided, it will be used and propagated through mappings; otherwise, the current displacement value is utilized.\n\n### Role and Purpose:\nThe visitor's primary role is to facilitate the accumulation of mass matrix-vector products during implicit integration schemes, which are common in FEM-based simulations. It inherits from `MechanicalVisitor`, a base class for various mechanical operations within SOFA.\n\n### Interactions with Other Components:\n- **`fwdMechanicalState`**: This method processes a given node and mechanical state but does not modify the result directly (`RESULT_CONTINUE`).\n- **`fwdMass`**: Performs the actual accumulation of `MDx` (mass matrix times displacement vector) into the result vector, using the provided mass component. The method returns `RESULT_PRUNE`, indicating that further traversal is not necessary.\n- **`getInfos`**: Returns a string with information about the visitor's operations, including details on the vectors used (`dx` and `res`).\n- **`fwdMechanicalMapping`** and **`fwdMappedMechanicalState`**: These methods handle mappings but do not modify the result (`RESULT_PRUNE`).\n\n### Practical Usage Guidance:\nThe `MechanicalAddMDxVisitor` requires a set of parameters to function, including mechanical parameters, the vectors for results (`res`) and displacements (`dx`), and a scaling factor (`factor`). It is typically used internally within the SOFA framework during implicit integration steps. The visitor supports thread-safe operations, making it suitable for parallel execution in multi-threaded environments.",
  "maths": "The `MechanicalAddMDxVisitor` in the SOFA simulation framework is designed to accumulate the product of the mass matrix by a given displacement vector. This operation plays a crucial role in implicit integration schemes, particularly those solved using Conjugate Gradient algorithms, which are common in FEM-based simulations.\n\n### Governing Equations and Operators:\nThe visitor accumulates contributions to the following mathematical expression:\n\begin{equation}\nM \times dx \\rightarrow res,\n\\end{equation}\nwhere $M$ is the mass matrix, $dx$ is a displacement vector, and $res$ is the result vector. The operation can be scaled by a factor $f$, yielding:\n\begin{equation}\nres = f \times M \\times dx.\n\\end{equation}\nThe accumulation process is performed element-wise across all elements in the simulation domain, propagating through mappings if necessary.\n\n### Constitutive or Kinematic Laws Involved:\nThis visitor does not directly involve specific constitutive laws (e.g., hyperelastic potentials) or kinematic measures beyond the standard mass matrix and displacement vector. However, it plays a key role in the implicit integration process by updating the residual vectors used to solve for displacements in nonlinear systems.\n\n### Role in Global FEM Pipeline:\nThe `MechanicalAddMDxVisitor` is part of the implicit time integration phase. Specifically, during each iteration of the implicit solver (such as Conjugate Gradient), it computes and accumulates contributions from mass matrices, facilitating the solution of linear system equations such as:\n\begin{equation}\nM \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t).\n\\end{equation}\nThe visitor's role is to handle the accumulation of $M \times dx$ contributions, which are essential for updating the residual and solving for displacements.\n\n### Numerical Methods or Discretization Choices:\nThe operation performed by this component involves standard matrix-vector multiplication and vector accumulation. The use of implicit integration schemes implies that the visitor contributes to the solution of a linear system at each time step, where $M$ is a sparse matrix derived from FEM spatial discretization.\n\n### Integration into Variational / Lagrangian Mechanics Framework:\nThe `MechanicalAddMDxVisitor` supports variational mechanics by contributing to the implicit integration process. This integration scheme ensures that the global balance of forces and inertial effects are accounted for at each time step, consistent with Lagrangian principles. The mass matrix $M$ is derived from the kinetic energy term in the Lagrangian:\n\begin{equation}\n\\mathcal{L}(q, \\dot{q}) = T(q, \\dot{q}) - V(q),\n\\end{equation}\nwhere $T$ represents the kinetic energy. The operation performed by this visitor ensures that inertial forces are correctly accounted for in the overall nonlinear solve process.",
  "abstract": "Accumulates the product of the mass matrix by a given displacement vector for implicit integration schemes in SOFA simulations.",
  "sheet": "# MechanicalAddMDxVisitor\n\n## Overview\nThe `MechanicalAddMDxVisitor` is a visitor component in the SOFA framework designed to accumulate the product of the mass matrix by a given displacement vector. This operation is crucial for implicit integration schemes, particularly those solved using Conjugate Gradient algorithms.\n\n## Mathematical Model\nThe `MechanicalAddMDxVisitor` accumulates contributions to the following mathematical expression:\n\\[ M \\times dx \\rightarrow res, \\]\nwhere $M$ is the mass matrix, $dx$ is a displacement vector, and $res$ is the result vector. The operation can be scaled by a factor $f$, yielding:\n\\[ res = f \\times M \\times dx. \\]\nThe accumulation process is performed element-wise across all elements in the simulation domain, propagating through mappings if necessary.\n\n## Dependencies and Connections\nThe `MechanicalAddMDxVisitor` interacts with mechanical states (`BaseMechanicalState`) and mappings (`BaseMapping`). It processes nodes and mass components to accumulate the product of the mass matrix by a given displacement vector. The visitor is typically used in implicit integration schemes, where it contributes to solving linear system equations such as:\n\\[ M \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t). \\]"
}