Methods

{
  "name": "MechanicalComputeDfVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalComputeDfVisitor.h",
  "doc": "Compute the variation of force corresponding to a variation of position.\nThis action is typically called after a MechanicalPropagateDxVisitor.",
  "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 `MechanicalComputeDfVisitor` is part of the SOFA simulation framework and inherits from the `MechanicalVisitor`. Its role is to compute the variation of force corresponding to a variation in position, typically after a `MechanicalPropagateDxVisitor`. This visitor interacts with various components such as mechanical states, mappings, and force fields through its API. It uses methods like `fwdMechanicalState`, `fwdMappedMechanicalState`, and `fwdForceField` for forward traversal and `bwdMechanicalMapping` and `bwdMechanicalState` for backward traversal. The visitor supports accumulation of variations back to degrees-of-freedom (DOFs) through mappings. It also specifies that it can be safely used in parallel execution environments.",
  "maths": "The `MechanicalComputeDfVisitor` in the SOFA simulation framework is designed to compute the variation of force (\\( \\delta \boldsymbol{F} \\\\) or \\( d\boldsymbol{F} \\\\) corresponding to a variation in position (\\( \boldsymbol{\nabla x} \\\\)). This visitor operates within the context of nonlinear mechanics, where forces depend on the configuration of the system, and thus variations in force due to changes in position must be evaluated.\n\n### Governing Equations or Operators:\nThe primary role of `MechanicalComputeDfVisitor` is to compute the variation of internal force (\\( d\boldsymbol{F}_{int} \\\\)) for a given variation in position. This operation involves evaluating the derivative of the internal forces with respect to the displacement vector \\( \boldsymbol{x} \\\\\\\n\nThe relationship can be expressed as:\n\nd\boldsymbol{F}_{int} = \frac{\nabla d\boldsymbol{F}_{int}}{\nabla \boldsymbol{x}}\n\nd\boldsymbol{x}\n\nIn the context of nonlinear FEM, this typically involves evaluating contributions from all force fields and mappings in the system. The method `fwdForceField` adds variations to the internal forces using the mechanical parameters provided.\n\n### Constitutive or Kinematic Laws Involved:\nThe visitor interacts with various components including mechanical states (`BaseMechanicalState`), mappings, and force fields (`BaseForceField`). These interactions imply that the variation of force is computed for different types of constitutive laws (e.g., linear elasticity, hyperelasticity) as defined by the specific force field.\n\n### Role in the Global FEM Pipeline:\nThe `MechanicalComputeDfVisitor` fits into the global FEM pipeline during the assembly and nonlinear solve phases. Specifically:\n1. **Assembly**: It computes contributions to the internal forces from different elements and mappings, which are essential for constructing the residual vector \\( \boldsymbol{R} \\\\).\n2. **Nonlinear Solve**: The variation in force is used to evaluate the Jacobian of the nonlinear system, aiding in the iterative solution process.\n\n### Numerical Methods or Discretization Choices:\nThe visitor supports accumulation through mappings (`accumulate` flag). This implies that it can sum up contributions from multiple mappings, which is essential for ensuring consistent forces across different levels of discretization (e.g., multi-resolution simulations).\n\n### Broad Framework Fitment:\nThe `MechanicalComputeDfVisitor` fits into the broader variational/Lagrangian mechanics framework by contributing to the evaluation of the weak form. It computes variations in force, which are used in constructing the residual and Jacobian matrices needed for solving nonlinear systems.\n\nThe component is thread-safe, allowing efficient parallel execution in simulations.",
  "abstract": "Computes the variation of force corresponding to a variation in position, typically after a `MechanicalPropagateDxVisitor`. It interacts with mechanical states, mappings, and force fields.",
  "sheet": "# MechanicalComputeDfVisitor\n\n## Overview\nThe `MechanicalComputeDfVisitor` is part of the SOFA simulation framework and inherits from the `MechanicalVisitor`. Its primary role is to compute the variation of internal force (\\( d\\boldsymbol{F}_{int} \\)) corresponding to a variation in position (\\( \\nabla x \\)). This visitor interacts with various components such as mechanical states, mappings, and force fields through its API methods.\n\n## Mathematical Model\nThe primary role of `MechanicalComputeDfVisitor` is to compute the variation of internal force (\\( d\\boldsymbol{F}_{int} \\)) for a given variation in position. This operation involves evaluating the derivative of the internal forces with respect to the displacement vector \\( \\boldsymbol{x} \\):\n\n\nd\\boldsymbol{F}_{int} = \\frac{d\\boldsymbol{F}_{int}}{d\\boldsymbol{x}} d\\boldsymbol{x}\n\nIn the context of nonlinear FEM, this typically involves evaluating contributions from all force fields and mappings in the system.\n\n## Dependencies and Connections\nThe `MechanicalComputeDfVisitor` interacts with various components including mechanical states (`BaseMechanicalState`), mappings, and force fields (`BaseForceField`). These interactions imply that the variation of force is computed for different types of constitutive laws (e.g., linear elasticity, hyperelasticity) as defined by the specific force field.\n\n## Practical Notes\nThe visitor supports accumulation through mappings (`accumulate` flag). This implies that it can sum up contributions from multiple mappings, which is essential for ensuring consistent forces across different levels of discretization (e.g., multi-resolution simulations). The component is thread-safe, allowing efficient parallel execution in simulations."
}