Methods

{
  "name": "RungeKutta4Solver",
  "namespace": "sofa::component::odesolver::forward",
  "module": "Sofa.Component.ODESolver.Forward",
  "include": "sofa/component/odesolver/forward/RungeKutta4Solver.h",
  "doc": "A popular explicit time integrator.\n\nA popular time integration method, much more precise than the EulerSolver */",
  "inherits": [
    "OdeSolver"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "solve",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "dt",
          "type": "SReal"
        },
        {
          "name": "xResult",
          "type": "sofa::core::MultiVecCoordId"
        },
        {
          "name": "vResult",
          "type": "sofa::core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "inputDerivative",
          "type": "int"
        },
        {
          "name": "outputDerivative",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSolutionIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "outputDerivative",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `RungeKutta4Solver` is an explicit time integrator in the SOFA framework, derived from the `OdeSolver` class. It implements the popular 4th-order Runge-Kutta method for numerical integration, providing a higher degree of accuracy compared to simpler methods like Euler's solver.\n\n**Key Features and Methods: **\n- **solve**: This method performs one time step using the 4th-order Runge-Kutta scheme. It computes intermediate positions and velocities at each sub-step (k1, k2, k3, k4) before updating the final position and velocity vectors.\n\n- **getIntegrationFactor**: Provides scaling factors for input derivatives (position, velocity, acceleration) affecting output derivatives of specified orders. These are used to compute the impact on different derivative orders during integration steps.\n\n- **getSolutionIntegrationFactor**: Offers similar functionality but tailored specifically for solutions derived from linear systems solved during each time step.\n\n**Interaction with Other Components: **\n- `RungeKutta4Solver` interacts primarily with mechanical state data, such as positions and velocities of particles or rigid bodies in the simulation. It relies on methods like `computeAcc`, which computes accelerations based on forces and constraints, and `solveConstraint`, to enforce constraints after updating positions.\n\n**Use Cases: **\n- Suitable for simulations requiring accurate integration over time with less stringent requirements for stability compared to implicit solvers. Ideal for scenarios where higher precision in temporal evolution is critical.",
  "maths": "The `RungeKutta4Solver` is an explicit time integrator that implements the fourth-order Runge-Kutta (RK4) method for numerical integration. This solver provides a higher degree of accuracy compared to simpler methods like Euler's solver, making it suitable for simulations where precise temporal evolution is critical.\n\n### Governing Equations and Operators\nThe RK4 method integrates ordinary differential equations (ODEs) of the form:\n\begin{align*}\n\\dot{x}(t) &= f(x(t), t) \\\\\nx(t_0) &= x_0\n\ndot{x} = \\frac{d}{dt}x,\n\\end{align*}\nwhere $f$ is a function that describes the time derivative of the state vector $x$. In the context of FEM and SOFA, this typically represents the velocity or acceleration.\n\n### Implementation Details (RK4 Method)\nThe RK4 method computes four intermediate evaluations ($k_1$, $k_2$, $k_3$, $k_4$) to update the state vector over a time step $\\Delta t$. These intermediate evaluations are given by:\n\begin{align*}\nk_{1} &= f(x(t_n), t_n) \\\\\nk_{2} &= f\\left( x(t_n) + \\frac{\\Delta t}{2} k_1, t_n + \\frac{\\Delta t}{2} \\right) \\\\\nk_{3} &= f\\left( x(t_n) + \\frac{\\Delta t}{2} k_2, t_n + \\frac{\\Delta t}{2} \\right) \\\\\nk_{4} &= f(x(t_n) + \\Delta t k_3, t_n + \\Delta t)\n\ndot{x}(t) = f(x(t), t).\n\\end{align*}\nThe final update for the state vector $x$ is:\n\begin{align*}\nx_{n+1} &= x_n + \\frac{\\Delta t}{6} (k_1 + 2k_2 + 2k_3 + k_4).\n\ndot{x}(t) = f(x(t), t)\n\nt_n = n \\Delta t.\n\\end{align*}\n\n### Constitutive and Kinematic Laws Involved\nIn the context of FEM within SOFA, the function $f$ typically represents forces or accelerations. For example, in a deformable system governed by Lagrangian mechanics:\n\begin{equation*}\nM\\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t),\n\ndot{x} = \\frac{d}{dt} x,\n\\end{equation*}\nwhere $M$ is the mass matrix, $f_{int}$ are internal forces (stiffness contributions from constitutive laws such as hyperelastic potentials or linear elasticity), and $f_{ext}$ are external forces.\n\n### Role in the Global FEM Pipeline\nThe `RungeKutta4Solver` plays a crucial role in the time integration phase of the FEM pipeline. Specifically, it updates the state vectors (positions and velocities) using explicit RK4 steps:\n1. **Compute Accelerations**: Evaluate intermediate accelerations $k_1$, $k_2$, $k_3$, and $k_4$ based on current positions and velocities.\n2. **Update Positions and Velocities**: Use the weighted average of these accelerations to update the final position and velocity vectors at the end of each time step.\n\n### Numerical Methods and Discretization Choices\nThe RK4 method is a four-stage explicit Runge-Kutta scheme that uses the following intermediate steps:\n- **First Stage (k1)**: Compute initial acceleration $k_1$ based on current state.\n- **Second Stage (k2)**: Update position and velocity by half-step, then compute new acceleration $k_2$.\n- **Third Stage (k3)**: Update position and velocity again by half-step using the updated acceleration from k2, then compute $k_3$.\n- **Fourth Stage (k4)**: Update position and velocity by full step using the updated acceleration from k3, then compute final acceleration $k_4$.\nThe final state update is a weighted average of these intermediate accelerations. This method ensures higher accuracy through multiple evaluations within each time step.\n\n### Constraint Handling\nThe `RungeKutta4Solver` also handles constraints after updating positions and velocities using the method `solveConstraint`. This ensures that any positional or velocity constraints are enforced at each stage of the RK4 integration.\n\n### Variational / Lagrangian Mechanics Framework\nWithin the broader variational/Lagrangian mechanics framework, the RungeKutta4Solver integrates equations derived from the weak (variational) form of continuum mechanics. It provides an explicit method for advancing state variables in time while maintaining higher accuracy compared to simpler methods like Euler integration.\n\n### Integration Factor Methods\nThe `getIntegrationFactor` and `getSolutionIntegrationFactor` methods provide scaling factors that describe how input derivatives influence output derivatives during the RK4 steps. These are used internally within SOFA's ODE solver framework for consistent time integration.",
  "abstract": "The `RungeKutta4Solver` implements the fourth-order Runge-Kutta method for explicit time integration in SOFA simulations, providing higher accuracy than simpler methods like Euler's solver.",
  "sheet": "# RungeKutta4Solver\n\n## Overview\n\nThe `RungeKutta4Solver` is an explicit time integrator derived from the `OdeSolver` class. It implements the fourth-order Runge-Kutta (RK4) method for numerical integration, offering higher accuracy compared to simpler methods like Euler's solver.\n\n## Mathematical Model\n\nThe RK4 method integrates ordinary differential equations (ODEs) of the form:\n\\[ \\dot{x}(t) = f(x(t), t) \\]\nwhere $f$ is a function that describes the time derivative of the state vector $x$. In the context of FEM and SOFA, this typically represents velocity or acceleration.\n\nThe RK4 method computes four intermediate evaluations ($k_1$, $k_2$, $k_3$, $k_4$) to update the state vector over a time step $\\Delta t$:\n\\[ k_{1} = f(x(t_n), t_n) \\]\n\\[ k_{2} = f\\left( x(t_n) + \\frac{\\Delta t}{2} k_1, t_n + \\frac{\\Delta t}{2} \\right) \\]\n\\[ k_{3} = f\\left( x(t_n) + \\frac{\\Delta t}{2} k_2, t_n + \\frac{\\Delta t}{2} \\right) \\]\n\\[ k_{4} = f(x(t_n) + \\Delta t k_3, t_n + \\Delta t) \\]\nThe final update for the state vector $x$ is:\n\\[ x_{n+1} = x_n + \\frac{\\Delta t}{6} (k_1 + 2k_2 + 2k_3 + k_4). \\]\n\nIn the context of FEM within SOFA, the function $f$ typically represents forces or accelerations. For example, in a deformable system governed by Lagrangian mechanics:\n\\[ M\\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t), \\]\nwhere $M$ is the mass matrix, $f_{int}$ are internal forces (stiffness contributions from constitutive laws such as hyperelastic potentials or linear elasticity), and $f_{ext}$ are external forces.\n\n## Practical Notes\n\nThe `RungeKutta4Solver` provides higher accuracy but requires more computational effort compared to simpler methods like Euler's solver. It is suitable for simulations where precise temporal evolution is critical, but it may be less stable in scenarios with stiff systems or large time steps."
}