Methods

{
  "name": "MechanicalAccumulateJacobian",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalAccumulateJacobian.h",
  "doc": "This class define a visitor which will go through the scene graph in reverse order and call the method applyJT of each mechanical mapping (@sa sofa::core::BaseMapping)",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "bwdMechanicalMapping",
      "return_type": "void",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "core::BaseMapping *"
        }
      ],
      "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"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalAccumulateJacobian` class in the SOFA framework is designed to traverse the scene graph in reverse order and call the method `applyJT` on each mechanical mapping (`sofa::core::BaseMapping`). This process accumulates the Jacobian transpose of mappings, which is essential for computing derivatives needed in various numerical solvers. It inherits from `BaseMechanicalVisitor`, indicating its role as a visitor that can traverse scene graph nodes to perform specific operations.\n\nThe component interacts with other SOFA components through the following methods:\n- `bwdMechanicalMapping`: Invokes the Jacobian transpose (`applyJT`) method on each mechanical mapping encountered during traversal, passing necessary parameters for computation.\n- `isThreadSafe`: Returns a boolean indicating whether the visitor can be safely used in multithreaded contexts; here it returns `false`, implying thread safety is not guaranteed.\n- `stopAtMechanicalMapping`: Determines if the traversal should stop at certain mechanical mappings. In this case, it continues through all mappings, regardless of their `isMechanical` flag.\n\nPractical usage involves incorporating this visitor into simulations where Jacobian accumulation is necessary for solving mechanical systems, particularly when dealing with constrained dynamics and multi-resolution models.",
  "maths": "The `MechanicalAccumulateJacobian` class in the SOFA framework is designed to accumulate Jacobian transpose contributions from mechanical mappings during a reverse traversal of the scene graph. This process is essential for computing derivatives required by various numerical solvers, particularly those involving constrained dynamics and multi-resolution models.\n\n### Governing Equations or Operators\n\nThe primary mathematical operation performed by `MechanicalAccumulateJacobian` involves accumulating contributions to the Jacobian transpose matrix. Specifically, for each mechanical mapping encountered during traversal, it calls the method `applyJT`, which computes the transpose of the Jacobian matrix associated with that mapping. This is mathematically represented as:\n\n\begin{align*}\n    J^T &= \\frac{\text{d} g}{\text{d} x}(x), \\\\ \n\\end{align*}\nwhere $J^T$ is the Jacobian transpose, and $g(x)$ represents a function (e.g., mapping) that transforms the state vector $x$. The accumulation of these contributions over all mappings ensures that the global Jacobian transpose matrix reflects the combined effect of all mechanical mappings in the scene graph.\n\n### Constitutive or Kinematic Laws Involved\n\nThe component does not directly implement any constitutive laws (such as strain measures, stress tensors, hyperelastic potentials) or kinematic laws. Instead, it operates on the higher-level abstraction provided by mechanical mappings, which are typically defined elsewhere in the SOFA simulation pipeline.\n\n### Role in the Global FEM Pipeline\n\n- **Assembly Phase**: During this phase, `MechanicalAccumulateJacobian` plays a role in assembling contributions to the Jacobian transpose matrix. Each mapping's contribution is accumulated during reverse traversal of the scene graph.\n- **Nonlinear Resolution**: The accumulated Jacobian transpose contributes to the linearization process required for solving nonlinear systems via Newton-Raphson iterations or similar methods.\n\n### Numerical Methods or Discretization Choices\n\nThe component does not introduce any new numerical methods or discretization choices. Instead, it relies on the existing mappings and their respective implementations of `applyJT` to compute the necessary Jacobian transpose contributions.\n\n### Fit into the Broader Variational / Lagrangian Mechanics Framework\n\nIn a broader variational / Lagrangian mechanics framework, the Jacobian transpose plays a critical role in computing derivatives needed for constrained optimization problems. The accumulation of these transposes ensures that the numerical solver can accurately account for the constraints imposed by mappings during the nonlinear solve phase.\n\nThus, `MechanicalAccumulateJacobian` is an essential component for ensuring consistency and accuracy in simulations involving constrained dynamics and multi-resolution models.",
  "abstract": "The `MechanicalAccumulateJacobian` component traverses the scene graph in reverse order to accumulate Jacobian transpose contributions from mechanical mappings by calling their `applyJT` method.",
  "sheet": "\n# MechanicalAccumulateJacobian\n\n## Overview\n\nThe `MechanicalAccumulateJacobian` class is a visitor that traverses the SOFA scene graph in reverse order, accumulating Jacobian transpose contributions from each mechanical mapping (`sofa::core::BaseMapping`). This process involves calling the `applyJT` method on each encountered mapping. The component inherits from `BaseMechanicalVisitor`, indicating its role as a traversal mechanism for specific operations.\n\n## Mathematical Model\n\nThe primary mathematical operation performed by `MechanicalAccumulateJacobian` is accumulating contributions to the Jacobian transpose matrix, denoted as $J^T$. For each mechanical mapping encountered during traversal, it computes and accumulates the transpose of the Jacobian matrix associated with that mapping. This accumulation ensures that the global Jacobian transpose matrix reflects the combined effect of all mappings in the scene graph.\n\nThe mathematical representation is given by:\n\n\begin{align*}\n    J^T &= \frac{\text{d} g}{\text{d} x}(x), \\\n\tag{1}\\end{align*}\nwhere $J^T$ is the Jacobian transpose, and $g(x)$ represents a function (e.g., mapping) that transforms the state vector $x$. This process is essential for numerical solvers dealing with constrained dynamics and multi-resolution models.\n\n## Dependencies and Connections\n\nThe `MechanicalAccumulateJacobian` component interacts with mechanical mappings (`sofa::core::BaseMapping`) by calling their `applyJT` method during traversal. It fits into the scene graph as a visitor that accumulates Jacobian transpose contributions, which are necessary for solving nonlinear systems involving constrained dynamics."
}