Methods

{
  "name": "MechanicalComputeForceVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalComputeForceVisitor.h",
  "doc": "Accumulate the forces (internal and interactions).\nThis action is typically called after a MechanicalResetForceVisitor.",
  "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 `MechanicalComputeForceVisitor` is part of the SOFA framework and is designed to accumulate forces (both internal and interactions). This visitor typically follows a `MechanicalResetForceVisitor`, ensuring that all forces are properly computed and accumulated across various mechanical states and mappings within the simulation.\n\nIt interacts with other components such as `BaseMechanicalState` and `BaseForceField`. Its API includes virtual methods to handle forward and backward traversal of mechanical states, force fields, and mappings. This visitor also supports thread-safe operation.\n\nPractical usage involves configuring it with `mechaparams`, a `MultiVecDerivId` for results, and an optional accumulation flag (`bAccumulate`). The component accumulates forces into the specified result vector (`res`) through the various traversal methods. It ensures that force computations are correctly propagated back to degrees of freedom via mappings when the `accumulate` flag is set.",
  "maths": "The `MechanicalComputeForceVisitor` in the SOFA framework is designed to accumulate forces (both internal and interaction forces) within a simulation. This visitor plays a crucial role in the FEM pipeline, specifically during the assembly phase where it ensures that all force contributions are properly computed and accumulated across various mechanical states and mappings.\n\n### Governing Equations and Operators\n- **Internal Forces:** The component accumulates internal forces from `BaseMechanicalState` objects. This is mathematically represented as:\n  \\\\[ f_{int} = \\sum_i f^{(i)}_{int} \\\\]\n  where each $f^{(i)}_{int}$ represents the internal force contribution from a mechanical state or force field.\n\n- **Interaction Forces:** The visitor also handles interaction forces contributed by `BaseForceField` objects. These are added to the global force vector:\n  \\\\[ f_{ext} = \\sum_i f^{(i)}_{ext} \\\\]\n  where each $f^{(i)}_{ext}$ represents an external force contribution from a force field.\n\n- **Mapping:** When the `accumulate` flag is set, the visitor applies the Jacobian transpose of mappings to propagate forces back to degrees of freedom (DOFs):\n  \\\\[ f_{dof} = \\sum_i J^T_i f^{(i)} \\\\]\n  where $J_i$ represents the Jacobian of a mapping.\n\n### Constitutive and Kinematic Laws Involved\nThe visitor does not directly implement constitutive or kinematic laws. Instead, it relies on other components such as `BaseMechanicalState` and `BaseForceField`, which are responsible for computing internal forces based on material models (e.g., hyperelastic potentials) and external forces.\n\n### Role in the Global FEM Pipeline\n- **Assembly:** The visitor accumulates force contributions into a global vector. This is part of the assembly phase where individual force components from various mechanical states and mappings are summed up to form the total internal force $f_{int}$.\n- **Time Integration:** Although not directly involved in time integration, the accumulated forces contribute to the residual in implicit schemes like Backward Euler:\n  \\\\[ R(x) = M \\frac{x_{n+1} - x_n}{\\Delta t} - f_{ext} + f_{int}(x_{n+1}) \\\\]\n- **Nonlinear Solve:** The accumulated forces are used in the nonlinear residual to solve for displacements in each time step.\n\n### Numerical Methods and Discretization Choices\nThe visitor itself does not encode any specific numerical methods or discretization choices. It is a generic component designed to accumulate forces, which can be integrated into various FEM formulations such as linear elasticity, corotational elasticity, or large deformation hyperelasticity models.\n\n### Variational / Lagrangian Mechanics Framework\nIn the broader variational framework, the visitor ensures that all force contributions (internal and external) are properly accumulated. This is essential for maintaining consistency in the weak form of the governing equations:\n  \\\\[ \\int_\\Omega \\rho \\ddot{u} \\cdot w \\, d\\Omega + \\int_\\Omega \\sigma : \\varepsilon(w) \\, d\\Omega = \\int_\\Omega \\rho b \\cdot w \\, d\\Omega + \\int_{\\Gamma_N} \\bar{t} \\cdot w \\, d\\Gamma \\\\]\n  where $w$ are test functions and the visitor ensures that all terms on the right-hand side (external forces) and left-hand side (internal forces) are correctly computed.",
  "abstract": "Accumulates internal and interaction forces within a simulation by traversing mechanical states and force fields, ensuring correct propagation of forces through mappings.",
  "sheet": "# MechanicalComputeForceVisitor\n\n## Overview\nThe `MechanicalComputeForceVisitor` is part of the SOFA framework and accumulates forces (both internal and interactions) within a simulation. It interacts with other components such as `BaseMechanicalState`, `BaseForceField`, and mappings to ensure proper force accumulation.\n\n## Mathematical Model\n- **Internal Forces:** The component accumulates internal forces from `BaseMechanicalState` objects:\n  \\[ f_{int} = \\\\[ \\sum_i f^{(i)}_{int} \\]\n  where each $f^{(i)}_{int}$ represents the internal force contribution from a mechanical state or force field.\n\n- **Interaction Forces:** The visitor also handles interaction forces contributed by `BaseForceField` objects:\n  \\[ f_{ext} = \\\\[ \\sum_i f^{(i)}_{ext} \\]\n  where each $f^{(i)}_{ext}$ represents an external force contribution from a force field.\n\n- **Mapping:** When the `accumulate` flag is set, the visitor applies the Jacobian transpose of mappings to propagate forces back to degrees of freedom (DOFs):\n  \\[ f_{dof} = \\\\[ \\sum_i J^T_i f^{(i)} \\]\n  where $J_i$ represents the Jacobian of a mapping.\n\n## Dependencies and Connections\nThe `MechanicalComputeForceVisitor` typically requires interactions with other components such as `BaseMechanicalState`, `BaseForceField`, and mappings to accumulate forces correctly. It fits into the scene graph by traversing these components in both forward and backward directions, ensuring that all force contributions are properly accounted for."
}