Methods

{
  "name": "MechanicalIdentityBlocksInJacobianVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalIdentityBlocksInJacobianVisitor.h",
  "doc": "",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalMapping",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdMappedMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "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 `MechanicalIdentityBlocksInJacobianVisitor` is part of the SOFA simulation framework, specifically within the mechanical visitor subsystem (`sofa::simulation::mechanicalvisitor`). It inherits from `BaseMechanicalVisitor`, indicating its role in the traversal and processing of mechanical states during simulations. This visitor processes mappings and mechanical states to identify blocks where identity transformations are applied for Jacobian construction.\n\n### Role and Purpose\nThe component is responsible for building identity blocks within the Jacobian matrix for certain degrees of freedom (DoFs) that do not have any children in their mapping hierarchy. It ensures that these identities are correctly accounted for during mechanical simulations, particularly when constructing matrices used in numerical solvers.\n\n### Interactions with Other Components\n- **fwdMechanicalMapping**: This method is called during the forward traversal of mappings and collects parent mechanical states which have children. The `Result::RESULT_CONTINUE` indicates that the visitor should continue traversing.\n- **bwdMappedMechanicalState**: This method handles backward mapping operations, where it checks if a given mechanical state has any parents in the collected set (`listParentMStates`). If not, it builds identity blocks for all DoFs of this state within the Jacobian matrix using `buildIdentityBlocksInJacobian`.\n- **stopAtMechanicalMapping**: This method determines whether to stop at a mapping node. In this visitor, it always returns false, indicating that traversal should continue without interruption.\n\n### Practical Usage Guidance\nThis component is used internally during simulation steps where Jacobian construction is required for numerical methods such as constraint projection or implicit integration. It ensures that the Jacobian correctly reflects identity transformations when certain mappings do not introduce any additional complexity in the mechanical state hierarchy.",
  "maths": "The `MechanicalIdentityBlocksInJacobianVisitor` is a visitor class in the SOFA framework designed to handle specific aspects of Jacobian construction within mechanical simulations. This component plays a critical role in ensuring that identity transformations are correctly accounted for during the assembly of matrices used in numerical solvers, particularly those involved in constraint projection or implicit integration methods.\n\n### Mathematical Description\n\n#### Role in FEM Pipeline\nThe `MechanicalIdentityBlocksInJacobianVisitor` is part of the nonlinear and linear resolution stages within the FEM simulation pipeline. Its primary function is to identify and construct identity blocks in the Jacobian matrix for degrees of freedom (DOFs) that do not have any children mappings.\n\n#### Jacobian Construction\nDuring the traversal process, the visitor collects parent mechanical states which have children mappings using `fwdMechanicalMapping`. For those mechanical states without any parents (`bwdMappedMechanicalState`), it builds identity blocks within the Jacobian matrix for all of their DOFs. This ensures that these DOFs are correctly represented as identity transformations in the overall Jacobian.\n\nThe mathematical representation involves constructing sub-blocks of the Jacobian matrix \\( J \\) where certain mappings do not introduce additional complexity. Specifically, for a mechanical state without children mappings, the relevant block within the Jacobian is set to an identity matrix:\n\\[\n    J_{ii} = I\n\\]\nwhere \\( i \\) indexes the DOFs of that particular mechanical state.\n\n#### Role in Linear and Nonlinear Solvers\nIn the context of linear solvers, constructing accurate Jacobian matrices (including appropriate identity blocks) is crucial for solving systems of equations efficiently. For nonlinear solvers, this visitor ensures that the tangent stiffness matrix (which includes the Jacobian) reflects the true mechanical behavior accurately.\n\n### Constitutive and Kinematic Laws\nThis component does not directly involve constitutive or kinematic laws such as strain measures or stress tensors. Instead, it focuses on ensuring that the numerical representation of mappings and transformations is consistent within the simulation framework.\n\n### Numerical Methods and Discretization Choices\nThe visitor employs a traversal-based approach to identify identity transformations during Jacobian construction. This ensures that the overall linear and nonlinear solvers operate with matrices that accurately reflect the mechanical state hierarchy, thereby enhancing the robustness and accuracy of the simulation results.",
  "abstract": "The `MechanicalIdentityBlocksInJacobianVisitor` identifies and constructs identity blocks in the Jacobian matrix for degrees of freedom (DOFs) without children mappings during mechanical simulations.",
  "sheet": "# MechanicalIdentityBlocksInJacobianVisitor\n\n## Overview\n\nThe `MechanicalIdentityBlocksInJacobianVisitor` is a component within the SOFA simulation framework that inherits from `BaseMechanicalVisitor`. It processes mappings and mechanical states to identify identity transformations for Jacobian construction, ensuring accurate representation of DOFs without children mappings.\n\n## Mathematical Model\n\nDuring the traversal process, the visitor collects parent mechanical states which have children mappings using `fwdMechanicalMapping`. For those mechanical states without any parents (`bwdMappedMechanicalState`), it builds identity blocks within the Jacobian matrix for all of their DOFs. This ensures that these DOFs are correctly represented as identity transformations in the overall Jacobian.\n\nThe mathematical representation involves constructing sub-blocks of the Jacobian matrix \\( J \\) where certain mappings do not introduce additional complexity. Specifically, for a mechanical state without children mappings, the relevant block within the Jacobian is set to an identity matrix:\n\\[\n    J_{ii} = I\n\\]\nwhere \\( i \\) indexes the DOFs of that particular mechanical state.\n\nIn the context of linear and nonlinear solvers, constructing accurate Jacobian matrices (including appropriate identity blocks) is crucial for solving systems of equations efficiently."
}