Methods

{
  "name": "OdeSolver",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/OdeSolver.h",
  "doc": "Component responsible for timestep integration, i.e. advancing the state from time t to t+dt.\n This class currently control both the integration scheme (explicit,\n implicit, static, etc).\n While all computations required to do the integration step are handled by\n this object, they should not be implemented directly in it, but instead\n the solver propagates orders (or Visitor) to the other components in the\n scenegraph that will locally execute them. This allows for greater\n flexibility (the solver can just ask for the forces to be computed without\n knowing what type of forces are present), as well as performances\n (some computations can be executed in parallel).",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "toOdeSolver",
      "return_type": "const OdeSolver *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "solve",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::ExecParams *"
        },
        {
          "name": "",
          "type": "SReal"
        },
        {
          "name": "",
          "type": "MultiVecCoordId"
        },
        {
          "name": "",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "solve",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "dt",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeResidual",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::ExecParams *"
        },
        {
          "name": "",
          "type": "SReal"
        },
        {
          "name": "",
          "type": "sofa::core::MultiVecCoordId"
        },
        {
          "name": "",
          "type": "sofa::core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "int"
        },
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSolutionIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVelocityIntegrationFactor",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPositionIntegrationFactor",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "insertInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `OdeSolver` component in the SOFA framework is responsible for timestep integration, advancing the state from time t to t+dt. It controls both the integration scheme (e.g., explicit or implicit) and handles all computations required for the integration step by propagating orders or visitors to other components in the scenegraph. This design allows for flexibility and performance improvements, as some computations can be executed in parallel. The component provides methods such as `solve` for advancing the state, `computeResidual` for computing the residual of the Newton iteration, and various integration factor methods (`getIntegrationFactor`, `getSolutionIntegrationFactor`, etc.) to manage how input derivatives affect output derivatives. Additionally, it includes methods for inserting and removing itself from a scene graph node (`insertInNode`, `removeInNode`).",
  "maths": "The `OdeSolver` component in the SOFA framework is responsible for advancing the state from time $t$ to $t+\text{dt}$, which involves performing timestep integration. This component plays a crucial role in the FEM pipeline by controlling both the integration scheme (e.g., explicit or implicit) and managing computations required for the integration step.\n\n**Governing Equations: **\nThe primary method `solve` is used to advance the state from $t$ to $t+\text{dt}$. This involves solving the semi-discrete dynamical system, which can be represented as a nonlinear ODE:\n\\[\nM \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t)\n\\]\nwhere $M$ is the mass matrix, $\\ddot{x}$ is the acceleration, $f_{int}$ represents internal forces, and $f_{ext}$ are external forces.\n\n**Integration Scheme: **\nThe integration scheme can be explicit or implicit. For example, in an implicit Backward Euler method, the system becomes:\n\\[\nM \\frac{x_{n+1} - x_n}{\\text{dt}} = f_{int}(x_{n+1}) + f_{ext}\n\\]\nwhich is a nonlinear equation solved iteratively using methods such as Newton-Raphson.\n\n**Residual Computation: **\nThe method `computeResidual` computes the residual of the system, typically defined as:\n\\[\nR(x) = M \\frac{x_{t+\text{dt}} - x_t}{\\text{dt}} + f_{int}(x_{t+\text{dt}}) - f_{ext}\n\\]\nThe residual is used in iterative solvers to check convergence.\n\n**Integration Factors: **\nThe `getIntegrationFactor` method provides the integration factors that describe how input derivatives affect output derivatives. For example, in a backward-Euler scheme:\n- Position at $t+\text{dt}$: $x_{t+\text{dt}} = x_t + \\text{dt} v_t$\n- Velocity at $t+\text{dt}$: $v_{t+\text{dt}} = v_t + \\text{dt} a_t$\n\nThese factors help in solving linear systems and updating state variables.\n\n**Role in the Global FEM Pipeline: **\nThe `OdeSolver` component fits into the broader variational/Lagrangian mechanics framework by advancing the simulation step-by-step. It handles the time integration phase, ensuring that the physical system evolves correctly over discrete timesteps while preserving numerical stability and accuracy.\n\n**Numerical Methods and Discretization Choices: **\nThe `OdeSolver` component does not directly perform the discretization or assembly of finite element operators but controls how these steps are performed. It propagates orders to other components in the scene graph, allowing for flexible and efficient computation.\n\nOverall, the `OdeSolver` is a critical component that ensures accurate temporal evolution of the physical system within the SOFA framework.",
  "abstract": "The `OdeSolver` component advances the state from time $t$ to $t+\\text{dt}$ by controlling integration schemes (explicit, implicit) and propagating orders to other components in the scene graph for flexible and efficient computation.",
  "sheet": "# OdeSolver\n\n## Overview\nThe `OdeSolver` is responsible for timestep integration, advancing the state from time $t$ to $t+\\text{dt}$. It controls both explicit and implicit integration schemes and propagates orders or visitors to other components in the scene graph. This design allows for flexibility and performance improvements through parallel computation.\n\n## Mathematical Model\nThe `OdeSolver` advances the state by solving the semi-discrete dynamical system represented as a nonlinear ODE:\n\\[\nM \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t)\n\\]\nwhere $M$ is the mass matrix, $\\ddot{x}$ is the acceleration, $f_{int}$ represents internal forces, and $f_{ext}$ are external forces.\n\nFor implicit integration schemes like Backward Euler, the system becomes:\n\\[\nM \\frac{x_{n+1} - x_n}{\\text{dt}} = f_{int}(x_{n+1}) + f_{ext}\n\\]\nwhich is solved iteratively using methods such as Newton-Raphson.\n\nThe `computeResidual` method computes the residual of the system:\n\\[\nR(x) = M \\frac{x_{t+\\text{dt}} - x_t}{\\text{dt}} + f_{int}(x_{t+\\text{dt}}) - f_{ext}\n\\]\nThe residual is used in iterative solvers to check convergence.\n\n## Parameters and Data\nThe `OdeSolver` does not expose any significant data fields. Its behavior is controlled through its methods and the integration scheme it implements.\n\n## Dependencies and Connections\nThe `OdeSolver` typically requires other components such as force fields, constraints, and solvers to compute forces and solve linear systems. It fits into the scene graph by propagating orders or visitors to these components for efficient computation."
}