Methods

{
  "name": "MechanicalComputeContactForceVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalComputeContactForceVisitor.h",
  "doc": "Accumulate only the contact forces computed in applyContactForce.\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": "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": "isThreadSafe",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalComputeContactForceVisitor` is a component in the SOFA framework designed to accumulate only the contact forces computed during an applyContactForce operation. This visitor typically follows the execution of a `MechanicalResetForceVisitor`, allowing for precise force accumulation specifically from contact interactions.\n\nIt inherits from the `MechanicalVisitor` class, which implies it operates within the mechanical simulation pipeline and interacts with other components in this context. The component is designed to work seamlessly with nodes (`simulation::Node*`) and mechanical states (`BaseMechanicalState*`). It also supports mappings (`BaseMapping*`), enabling integration with various mechanical models.\n\nThe `fwdMechanicalState` and `fwdMappedMechanicalState` methods accumulate forces from the given mechanical state, while the `bwdMechanicalMapping` method applies the Jacobian transpose to map forces between different representations. The visitor specifies that it is thread-safe (`isThreadSafe`), which allows for parallel execution where applicable.\n\nThis component plays a crucial role in ensuring accurate and efficient contact force computation within the SOFA simulation environment, particularly useful in simulations involving detailed interaction dynamics.",
  "maths": "The `MechanicalComputeContactForceVisitor` is an essential component in the SOFA framework, designed to accumulate contact forces computed during a simulation. It operates within the mechanical simulation pipeline and interacts with various components involved in force accumulation and mapping.\n\n### Governing Equations and Operators\n\nThis visitor primarily contributes to the computation of internal forces $f_{int}$ specifically related to contact interactions. The internal force vector $f_{int}$ is given by:\n\n\begin{equation}\n f_{int} = \\sum_e f^{e}_{contact}\n\tag{1}\n\\end{equation}\n\nwhere $f^{e}_{contact}$ represents the contact forces computed for each element or node in the system.\n\n### Constitutive Laws and Kinematic Models\n\nThe component does not directly define constitutive laws or kinematic models. Instead, it relies on the contact force computation performed by other components within the SOFA framework. The specific nature of these contact forces depends on the type of contact model (e.g., penalty-based, Lagrangian multiplier-based) and the associated constitutive relations.\n\n### Role in the Global FEM Pipeline\n\n1. **Assembly Phase**: During this phase, `MechanicalComputeContactForceVisitor` accumulates the computed contact forces into a global force vector $f_{int}$ using the `accumulateForce` method:\n\n\begin{equation}\n mm->accumulateForce(this->params, res.getId(mm))\n\tag{2}\n\\end{equation}\n\nwhere `$mm$` represents the mechanical state and `$res.getId(mm)$` returns the appropriate identifier for force accumulation.\n\n2. **Mapping**: The `bwdMechanicalMapping` method applies the Jacobian transpose to map forces between different representations:\n\n\begin{equation}\n map->applyJT(mparams, res, res)\n\tag{3}\n\\end{equation}\n\n### Numerical Methods and Discretization Choices\n\nThe component does not directly encode numerical methods or discretization choices. Instead, it operates on the contact forces computed by other components, which may involve various discretization schemes (e.g., penalty-based methods, Lagrangian multipliers).\n\n### Integration into Variational / Lagrangian Mechanics Framework\n\nIn a variational or Lagrangian mechanics framework, the internal force $f_{int}$ is a key component of the residual equation in implicit time integration schemes. The `MechanicalComputeContactForceVisitor` ensures that contact forces are accurately accumulated and mapped within this framework.\n\n\begin{equation}\n R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}=0 \n\tag{4}\n\\end{equation}\n\nwhere `$M$` is the mass matrix, `$f_{ext}$` represents external forces, and `$R(x_{n+1})$` denotes the residual force.\n\n### Summary\n\nThe `MechanicalComputeContactForceVisitor` plays a critical role in accumulating contact forces within the SOFA simulation pipeline. It ensures that these forces are accurately computed, accumulated, and mapped between different representations, contributing to precise and efficient simulation of contact interactions.",
  "abstract": "The `MechanicalComputeContactForceVisitor` accumulates contact forces computed during the simulation, ensuring precise force accumulation from contact interactions within the SOFA framework.",
  "sheet": "# MechanicalComputeContactForceVisitor\n\n## Overview\nThe `MechanicalComputeContactForceVisitor` is a visitor component in the SOFA framework designed to accumulate only the contact forces computed during an applyContactForce operation. This visitor typically follows the execution of a `MechanicalResetForceVisitor`, allowing for precise force accumulation specifically from contact interactions.\n\n## Mathematical Model\nThis visitor primarily contributes to the computation of internal forces $f_{int}$ specifically related to contact interactions. The internal force vector $f_{int}$ is given by:\n\n\\[ f_{int} = \\sum_e f^{e}_{contact} \\]\n\nwhere $f^{e}_{contact}$ represents the contact forces computed for each element or node in the system.\n\nIn a variational or Lagrangian mechanics framework, the internal force $f_{int}$ is a key component of the residual equation in implicit time integration schemes:\n\n\\[ R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}=0 \\]\n\nwhere $M$ is the mass matrix, $f_{ext}$ represents external forces, and $R(x_{n+1})$ denotes the residual force.\n\n## Practical Notes\nThe `MechanicalComputeContactForceVisitor` ensures that contact forces are accurately accumulated and mapped within the simulation pipeline. It operates on mechanical states and mappings to ensure precise force accumulation for contact interactions."
}