Methods

{
  "name": "MechanicalPropagateDxAndResetForceVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalPropagateDxAndResetForceVisitor.h",
  "doc": "Same as MechanicalPropagateDxVisitor followed by 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": "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": "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 `MechanicalPropagateDxAndResetForceVisitor` is a visitor in the SOFA framework designed to perform two operations: propagate displacements (`dx`) and reset forces (`f`). This functionality is similar to executing both the `MechanicalPropagateDxVisitor` and `MechanicalResetForceVisitor`. It inherits from the `MechanicalVisitor` class, allowing it to interact with mechanical states and mappings within the SOFA simulation framework. \n\nIt interacts with other components through several virtual methods such as `fwdMechanicalState`, `fwdMappedMechanicalState`, `fwdMechanicalMapping`, and `bwdMechanicalState`. These methods are called during forward or backward traversal of the scene graph to propagate displacements and reset forces at mechanical states. The component is thread-safe, making it suitable for parallelized operations.\n\nPractical usage involves setting up the visitor with specific displacement (`dx`) and force (`f`) vector IDs, typically passed through constructor parameters. It uses these IDs to operate on the corresponding vectors during its execution.",
  "maths": "<maths_md_description>\n\nThe `MechanicalPropagateDxAndResetForceVisitor` component in the SOFA framework is responsible for propagating displacements and resetting forces within a mechanical system. This visitor combines functionalities similar to those of two separate visitors: `MechanicalPropagateDxVisitor` and `MechanicalResetForceVisitor`. Below is a detailed mathematical and physical description of this component.\n\n### Governing Equations or Operators\n\n1. **Displacement Propagation**: The displacements \\(dx_i(t)\\), where \\(i\\) indexes the degrees-of-freedom (DOFs), are propagated through the mechanical state using the following operation:\n   - In each `fwdMechanicalState` and `fwdMappedMechanicalState`, the displacement vector is applied to the nodes of the mechanical system.\n\n2. **Force Reset**: The internal forces \\(f_i(t)\\) at each DOF are reset to zero during the forward pass through the scene graph:\n   - This is accomplished by calling `mm->resetForce(this->params, f.getId(mm))` in both `fwdMechanicalState` and `fwdMappedMechanicalState` methods.\n\n### Constitutive or Kinematic Laws Involved\n\n- **Displacement Propagation**: The displacement vector \\(dx\\) represents the incremental change in positions of nodes due to applied forces, constraints, and time integration. It is a direct result of solving the nonlinear dynamical system described by:\n  \n  \n  \\[\n  M\frac{d^2x(t)}{dt^2} + f_{int}(x(t)) = f_{ext}(t)\n  \\]\n\n- **Force Reset**: The internal force vector \\(f\\) is reset to zero, indicating that the system's current state will have no residual forces acting on it. This is a preparatory step for subsequent iterations or time steps where new forces may be computed.\n\n### Role in the Global FEM Pipeline\n\n1. **Assembly**: The component does not directly contribute to assembling global matrices such as mass \\(M\\) and stiffness \\(K\\). However, it indirectly supports the assembly phase by ensuring that displacements are correctly propagated through mappings between different mechanical states.\n\n2. **Time Integration**: Although this visitor itself is not a time integrator, it plays a crucial role in the pre-processing steps of each time step. It ensures that displacements and forces are appropriately managed before nonlinear or linear solve stages.\n\n3. **Nonlinear Solve**: The reset of internal forces is an essential step for starting a new iteration in nonlinear solvers like Newton-Raphson, where the residual \\(R(x_{n+1})\\) must be recomputed with zero initial force contributions.\n\n4. **Linear Solve**: Before entering the linear solve phase, the visitor ensures that all internal forces are reset to prepare for the next linearization step in nonlinear solvers.\n\n5. **Constraint Handling and Mapping**: The `fwdMechanicalMapping` method applies the Jacobian \\(J\\) of mappings between different states (e.g., from slave to master nodes), ensuring consistency across connected systems or multi-resolution meshes.\n\n### Numerical Methods or Discretization Choices\n\n- **Displacement Propagation**: This involves a straightforward update of nodal positions based on computed displacements, adhering to the discretized weak form and variational principles used in FEM.\n\n- **Force Reset**: The force reset operation is a simple assignment of zero values to internal force vectors, preparing for the next step in iterative solvers or time integration schemes.\n\n### Fit into Variational / Lagrangian Mechanics Framework\n\nThe visitor supports the overall variational mechanics framework by ensuring that:\n\n1. Displacements are consistently propagated through the system, reflecting the solution of the Euler-Lagrange equations in generalized coordinates.\n2. Forces are reset to ensure that each iteration or time step starts with a clean slate, ready for recomputing new contributions from potential energy variations and constraints.\n\nIn summary, `MechanicalPropagateDxAndResetForceVisitor` plays a crucial role in maintaining consistency within the FEM pipeline by correctly managing displacements and forces during simulation steps.</maths_md_description>",
  "abstract": "The `MechanicalPropagateDxAndResetForceVisitor` propagates displacements (`dx`) through mechanical states and resets internal forces (`f`). It combines functionalities of `MechanicalPropagateDxVisitor` and `MechanicalResetForceVisitor`, ensuring consistency in the FEM pipeline.",
  "sheet": "# MechanicalPropagateDxAndResetForceVisitor\n\n**Overview**\nThe `MechanicalPropagateDxAndResetForceVisitor` is a visitor component that propagates displacements (`dx`) through mechanical states and resets internal forces (`f`). It inherits from `MechanicalVisitor`, indicating its role in managing the mechanical state during simulation steps. This visitor combines functionalities similar to those of two separate visitors: `MechanicalPropagateDxVisitor` and `MechanicalResetForceVisitor`. \n\n**Mathematical Model**\nThe component handles displacement propagation and force reset as follows:\n1. **Displacement Propagation**: The displacements \\(dx_i(t)\\), where \\(i\\) indexes the degrees-of-freedom (DOFs), are propagated through the mechanical state using the following operation:\n   - In each `fwdMechanicalState` and `fwdMappedMechanicalState`, the displacement vector is applied to the nodes of the mechanical system.\n2. **Force Reset**: The internal forces \\(f_i(t)\\) at each DOF are reset to zero during the forward pass through the scene graph:\n   - This is accomplished by calling `mm->resetForce(this->params, f.getId(mm))` in both `fwdMechanicalState` and `fwdMappedMechanicalState` methods.\n\n**Dependencies and Connections**\nThe component interacts with other mechanical states (`BaseMechanicalState`) and mappings (`BaseMapping`). It is typically used within the scene graph traversal to ensure that displacements are correctly propagated and forces are reset before subsequent operations such as nonlinear or linear solves. The visitor's methods `fwdMechanicalState`, `fwdMappedMechanicalState`, and `fwdMechanicalMapping` are called during forward traversal, while `bwdMechanicalState` is used for backward traversal.\n\n**Practical Notes**\nThe component ensures that displacements are consistently propagated through the system and forces are reset to zero before new iterations or time steps. This is crucial for maintaining consistency in the FEM pipeline."
}