Methods

{
  "name": "MechanicalIntegrationVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalIntegrationVisitor.h",
  "doc": "Visitor used to do a time integration step using OdeSolvers",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdOdeSolver",
      "return_type": "Result",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "obj",
          "type": "sofa::core::behavior::OdeSolver *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdInteractionForceField",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "obj",
          "type": "sofa::core::behavior::BaseInteractionForceField *"
        }
      ],
      "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 `MechanicalIntegrationVisitor` in the SOFA framework is used to perform time integration steps using OdeSolvers, which are essential for advancing the mechanical state of simulation objects over time. It inherits from `BaseMechanicalVisitor`, allowing it to interact with various components within the SOFA scene graph structure.\n\nThe component interacts with other SOFA components through its methods: \n- `fwdOdeSolver` processes OdeSolvers at specific nodes, facilitating the integration of mechanical state changes. \n- `fwdInteractionForceField` handles BaseInteractionForceFields to manage forces affecting simulation objects.\n- `isThreadSafe` checks if the visitor can operate in a thread-safe manner, enabling parallel processing where appropriate.\n\nIn practical usage, the component integrates OdeSolvers and manages force fields within nodes of the scene graph. It supports mechanical integration by executing various visitors that handle different aspects such as constraint matrix construction and force accumulation. The field `dt` represents the time step used in the integration process.",
  "maths": "The `MechanicalIntegrationVisitor` in the SOFA framework is responsible for performing time integration steps using ODE solvers, which are essential for advancing the mechanical state of simulation objects over time. This visitor plays a critical role in the FEM pipeline by facilitating the propagation and accumulation of forces and updating the positions and velocities of the nodes within the scene graph.\n\n### Governing Equations or Operators Involved:\n- **Mass Matrix (M)**: The mass matrix encapsulates the inertial properties of the system. In implicit time integration schemes, it is typically involved in the residual calculation and nonlinear solve phases.\n- **Stiffness Matrix (K)**: This matrix captures the elastic response of the material based on the constitutive law. It is derived from the internal forces and plays a central role in the linearization and solution process.\n- **Internal Force (\textbf{f}_{int})**: The vector representing internal forces, which includes contributions from both deformational energy (stress) and possibly external loads (e.g., body forces).\n- **Residual (\textbf{R})**: In implicit time integration schemes like backward Euler, the residual is formulated as:\n  \begin{equation}\n    \\textbf{R}(\\mathbf{x}_{n+1}) = M\\frac{\\mathbf{x}_{n+1} - \\mathbf{x}_n}{\\Delta t} - \\Delta t (f_{ext} - f_{int}(\\mathbf{x}_{n+1}))\n  \\end{equation}\n\n### Constitutive or Kinematic Laws Involved:\n- **Strain Measures**: The component interacts with ODE solvers that may use various strain measures depending on the constitutive law, such as Green–Lagrange strains for large deformations.\n- **Stress Tensors**: Depending on the material model, stress tensors like Cauchy or Piola-Kirchhoff stresses are computed and used in the internal force calculations.\n- **Damping Models**: Implicit time integration schemes may also incorporate damping models to account for energy dissipation during deformation.\n\n### Role in the Global FEM Pipeline:\n1. **Assembly Phase**:\n   - Assembles contributions from various components, such as ODE solvers and interaction force fields.\n2. **Time Integration**:\n   - Advances the mechanical state by solving the nonlinear residual equation using implicit time integration methods (e.g., backward Euler).\n3. **Nonlinear Resolution**:\n   - Utilizes Newton-Raphson iteration to solve for the updated positions and velocities at each time step.\n4. **Linear Solution**:\n   - Involves iterative solvers like Conjugate Gradient or direct factorizations to solve the linearized system of equations during each Newton-Raphson iteration.\n5. **Constraint Handling**:\n   - Manages constraint projection through visitors like `MechanicalBuildConstraintMatrix` and `MechanicalAccumulateMatrixDeriv`, ensuring that constraints are consistently applied throughout the integration process.\n\n### Numerical Methods or Discretization Choices Encoded:\n- The time step (`dt`) is a key parameter used to discretize the continuous-time problem into discrete steps.\n- Implicit schemes like backward Euler ensure unconditional stability for linear systems, which is beneficial for stiff problems and large deformations.\n- Various visitors handle the propagation of mechanical state changes (position and velocity) across nodes in parallel where possible, leveraging thread-safe operations.\n\n### Fit into the Broader Variational / Lagrangian Mechanics Framework:\n- The `MechanicalIntegrationVisitor` operates within the variational framework by ensuring that each time integration step is consistent with the underlying weak form of the governing equations derived from Lagrangian mechanics.\n- It facilitates the numerical solution process, aligning with principles such as conservation of energy and momentum in the discretized system.",
  "abstract": "The `MechanicalIntegrationVisitor` performs time integration steps using ODE solvers to advance the mechanical state of simulation objects over time in SOFA simulations.",
  "sheet": "# MechanicalIntegrationVisitor\n\n## Overview\nThe `MechanicalIntegrationVisitor` is a core component that advances the mechanical state of simulation objects over time by performing time integration steps using OdeSolvers. It inherits from `BaseMechanicalVisitor`, enabling it to interact with various components within the SOFA scene graph structure.\n\n## Mathematical Model\nIn implicit time integration schemes, the mass matrix (\\(M\")), stiffness matrix (\\(K\")), and internal forces (\\(\\mathbf{f}_{int}\")) are key elements. The residual equation for backward Euler is given by:\n\n\\[ \textbf{R}(\textbf{x}_{n+1}) = M \\frac{\textbf{x}_{n+1} - \textbf{x}_n}{Δ t} - Δ t (f_{ext} - f_{int}(\textbf{x}_{n+1})) \\]\n\nThis equation is solved iteratively using methods like Newton-Raphson to update the positions and velocities at each time step.\n\n## Parameters and Data\nThe `MechanicalIntegrationVisitor` does not expose any significant data fields. Its functionality is primarily driven by its methods and interactions with other components in the scene graph.\n\n## Dependencies and Connections\nThis component typically requires interaction with OdeSolvers and BaseInteractionForceFields to manage forces affecting simulation objects. It fits into the SOFA scene graph structure by processing these components at specific nodes during each integration step.\n\n## Practical Notes\nThe `isThreadSafe` method allows for parallel processing where appropriate, enhancing performance in multi-threaded environments. The time step (`dt`) is a critical parameter that discretizes the continuous-time problem and affects numerical stability."
}