Methods

{
  "name": "MechanicalAccumulateMatrixDeriv",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalAccumulateMatrixDeriv.h",
  "doc": "Accumulate Jacobian matrices through the mappings up to the independent DOFs",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "constraintParams",
      "return_type": "const sofa::core::ConstraintParams *",
      "params": [],
      "is_virtual": false,
      "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": "childOrderReversed",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::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"
    }
  ],
  "description": "The `MechanicalAccumulateMatrixDeriv` is a SOFA component in the `sofa::simulation::mechanicalvisitor` namespace, part of the Sofa.framework.Simulation.Core module. Its primary role is to accumulate Jacobian matrices through mappings up to independent degrees-of-freedom (DOFs). This component inherits from `BaseMechanicalVisitor`, which implies it operates as a visitor in the SOFA simulation pipeline, typically interacting with nodes and mappings to perform mechanical computations.\n\n**Interactions:**\n- **bwdMechanicalMapping**: Overrides this method to apply Jacobian transpose (`JT`) operations on mappings. The visitor traverses mappings from dependent DOFs back to independent ones, accumulating matrices along the way.\n- **childOrderReversed**: Indicates whether the traversal order of child nodes should be reversed; useful for controlling the direction of accumulation.\n- **stopAtMechanicalMapping**: Ensures that this visitor does not stop at any mechanical mapping and continues through all mappings regardless of their flags, ensuring a complete traversal.\n- **isThreadSafe**: Returns false indicating it is not thread-safe. This implies careful usage in parallel simulations to avoid race conditions.\n\n**Usage Guidance:**\nThis component is used internally within the simulation pipeline for accumulating Jacobian matrices across multiple levels of mechanical mappings. Users should consider its behavior when setting up complex mappings or multiresolution models where accumulation order might be critical. It operates on `sofa::core::BaseMapping` instances and interacts with constraint parameters (`ConstraintParams`).",
  "maths": "<p>The <code>MechanicalAccumulateMatrixDeriv</code> component in the <code>sofa::simulation::mechanicalvisitor</code> namespace plays a crucial role in accumulating Jacobian matrices through mappings up to independent degrees-of-freedom (DOFs) within the SOFA simulation framework. This component is integral to ensuring that mechanical computations are performed correctly, especially when dealing with complex multiresolution models or multiple levels of mechanical mappings.</p>\n\n<h3>Governing Equations and Operators</h3>\n\n<p>The <code>MechanicalAccumulateMatrixDeriv</code> primarily operates on the Jacobian matrices, which represent how changes in dependent DOFs (dependent nodes) affect independent DOFs (independent nodes). In FEM terms:</p>\n\n<ul>\n<li><strong>Jacobian Matrix (\\( J \\\\) or its transpose (\\( J^T \\\")):</strong> The Jacobian matrix represents the derivative of the mapping function. For a mapping between dependent and independent DOFs, \\( J_{ij} = \\frac{\\partial u_i^{\\text{dep}}}{\\partial x_j^{\\text{ind}}} \\), where \\( u_i^{\\text{dep}} \\) are the coordinates of the dependent nodes and \\( x_j^{\\text{ind}} \\) are the coordinates of the independent nodes. The transpose, \\( J^T \\), is used to propagate forces or constraints from the dependent DOFs back to the independent DOFs.</li>\n</ul>\n\n<p>During the backward mechanical mapping (bwdMechanicalMapping method), the component applies the Jacobian transpose operation:</p>\n\n\\[\nJ^T cparams \n\\]\n\n<p>This accumulates the forces or constraints from dependent nodes to independent nodes.</p>\n\n<h3>Constitutive or Kinematic Laws</h3>\n\n<p>The <code>MechanicalAccumulateMatrixDeriv</code> component itself does not implement any specific constitutive or kinematic laws directly. Instead, it works with the mappings and constraint parameters provided by other components in the SOFA framework.</p>\n\n<h3>Role in the Global FEM Pipeline</h3>\n\n<p>In the context of the global FEM pipeline, this component is part of the assembly phase:</p>\n\n<ul>\n<li><strong>Assembly Phase:</strong> It accumulates Jacobian matrices across multiple levels of mechanical mappings to ensure that forces and constraints are correctly propagated from dependent DOFs back to independent ones. This is essential for maintaining consistency in force and constraint distributions across different resolution levels or mapping hierarchies.</li>\n</ul>\n\n<h3>Numerical Methods and Discretization Choices</h3>\n\n<p>The component operates on a node-wise traversal mechanism, using the <code>bwdMechanicalMapping</code> method to apply Jacobian transpose operations. This ensures that all mappings are processed in the correct order, often from dependent DOFs back to independent ones:</p>\n\n<ul>\n<li><strong>Numerical Integration:</strong> While not directly performing numerical integration itself, it supports the overall integration process by ensuring that force and constraint accumulation is consistent across different levels of mappings.</li>\n</ul>\n\n<p>The <code>MechanicalAccumulateMatrixDeriv</code> also handles reverse traversal order through the <code>childOrderReversed</code> method to control the direction in which Jacobian matrices are accumulated. This can be crucial for maintaining numerical stability and consistency, especially when dealing with complex mappings or multiresolution models.</p>\n\n<h3>Fitting into the Variational / Lagrangian Mechanics Framework</h3>\n\n<p>The <code>MechanicalAccumulateMatrixDeriv</code> component is aligned with the variational mechanics framework in SOFA by ensuring that all mechanical computations, especially those related to forces and constraints, are propagated correctly through mappings. This supports the overall goal of preserving physical consistency, numerical stability, and extensibility:</p>\n\n<ul>\n<li><strong>Variational Formulation:</strong> The Jacobian transpose operations ensure that the weak form (variational formulation) is preserved as forces and constraints are distributed.</li>\n<li><strong>Mechanical Invariants:</strong> By accumulating Jacobians through mappings, it ensures that mechanical invariants such as force consistency are maintained throughout the simulation.</li>\n</ul>",
  "abstract": "The `MechanicalAccumulateMatrixDeriv` accumulates Jacobian matrices through mappings up to independent degrees-of-freedom (DOFs) in SOFA simulations, ensuring correct mechanical computations across complex multiresolution models or multiple levels of mechanical mappings.",
  "sheet": "# MechanicalAccumulateMatrixDeriv\n\n## Overview\nThe `MechanicalAccumulateMatrixDeriv` is a component within the `sofa::simulation::mechanicalvisitor` namespace that accumulates Jacobian matrices through mappings up to independent degrees-of-freedom (DOFs). It inherits from `BaseMechanicalVisitor`, indicating its role as a visitor in the mechanical computation pipeline. This component ensures correct force and constraint propagation across different resolution levels or mapping hierarchies.\n\n## Mathematical Model\nThe `MechanicalAccumulateMatrixDeriv` primarily operates on Jacobian matrices, which represent how changes in dependent DOFs affect independent DOFs. The Jacobian matrix is defined as:\n\n\begin{equation}\nJ_{ij} = \\frac{∂ u_i^{\text{dep}}}{∂ x_j^{\text{ind}}} \n\tag{1}\n\ndisplayed equation\n\\end{equation}\n\nwhere $u_i^{\\text{dep}}$ are the coordinates of dependent nodes and $x_j^{\\text{ind}}$ are the coordinates of independent nodes. The transpose, $J^T$, is used to propagate forces or constraints from dependent DOFs back to independent DOFs.\n\nDuring the backward mechanical mapping (bwdMechanicalMapping method), the component applies the Jacobian transpose operation:\n\n\begin{equation}\nJ^T cparams \n\tag{2}\n\\end{equation}\n\nThis accumulates forces or constraints from dependent nodes to independent nodes, ensuring consistency in force and constraint distributions across different resolution levels or mapping hierarchies."
}