{
  "name": "BaseLinearMultiStepMethod",
  "main": {
    "name": "BaseLinearMultiStepMethod",
    "namespace": "sofa::component::odesolver::backward",
    "module": "Sofa.Component.ODESolver.Backward",
    "include": "sofa/component/odesolver/backward/BaseLinearMultiStepMethod.h",
    "doc": "Base class for a linear multistep method\nGeneric class computing a residual based on any coefficients given by a linear multistep method.\nDerived class just have to define the coefficients.\nA linear multistep method is defined by:\n$$\n\\sum_{j=0}^s a_j y_{n+j} = h\\sum_{j=0}^s b_j f(t_{n+j},y_{n+j})\n$$\nThe coefficients a and b are class members and must be computed by derived classes.\nThe linear system from the Newton-Raphson solver is solved in 2 steps:\n1) A first linear system leads to solve for a velocity difference\n2) Based on the velocity, the position is computed",
    "inherits": [
      "LinearSolverAccessor",
      "OdeSolver"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_rayleighStiffness",
        "type": "SReal",
        "xmlname": "rayleighStiffness",
        "help": "Rayleigh damping coefficient related to stiffness, > 0"
      },
      {
        "name": "d_rayleighMass",
        "type": "SReal",
        "xmlname": "rayleighMass",
        "help": "Rayleigh damping coefficient related to mass, > 0"
      }
    ],
    "links": [
      {
        "name": "l_newtonSolver",
        "target": "NewtonRaphsonSolver",
        "kind": "single",
        "xmlname": "newtonSolver",
        "help": "Link to a Newton-Raphson solver to solve the nonlinear equation produced by this numerical method"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reset",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "solve",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const core::ExecParams *"
          },
          {
            "name": "dt",
            "type": "SReal"
          },
          {
            "name": "xResult",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "vResult",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "realloc",
        "return_type": "void",
        "params": [
          {
            "name": "vop",
            "type": "sofa::simulation::common::VectorOperations &"
          },
          {
            "name": "id",
            "type": "core::TMultiVecId<vtype, core::VecAccess::V_WRITE> &"
          },
          {
            "name": "vecIdName",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "recomputeCoefficients",
        "return_type": "void",
        "params": [
          {
            "name": "order",
            "type": "int"
          },
          {
            "name": "dt",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BaseLinearMultiStepMethod` is a base class for linear multistep methods used in the SOFA framework to solve ordinary differential equations (ODEs). It provides a generic implementation that computes residuals based on coefficients defined by derived classes. The method relies on a Newton-Raphson solver to handle nonlinear equations.\n\n**Interactions with Other Components: **\n- **LinearSolverAccessor:** Accesses linear solvers for solving the system of equations.\n- **OdeSolver:** Implements ODE solving functionalities, inheriting from this base class.\n- **NewtonRaphsonSolver:** A linked component used to solve nonlinear equations generated by the numerical method. The link is established during initialization (`init()`).\n\n**Data Fields: **\n- `d_rayleighStiffness`: Rayleigh damping coefficient related to stiffness, greater than 0.\n- `d_rayleighMass`: Rayleigh damping coefficient related to mass, greater than 0.\n\n**Methods: **\n- `init()`: Initializes the component and ensures a Newton-Raphson solver is linked. Sets up data structures for time steps.\n- `reset()`: Resets internal states by clearing stored vectors.\n- `solve()`: Solves the ODE using linear multistep methods, computing residuals and updating positions and velocities based on the method's order and coefficients.\n- `realloc()`: Reallocates memory for multi-vectors used in mechanical operations.\n- `recomputeCoefficients()`: Pure virtual method that must be implemented by derived classes to compute the coefficients for the multistep method."
  },
  "maths": {
    "maths": "<h2>Mathematical Description</h2>\n\n<p>The `BaseLinearMultiStepMethod` class in the SOFA framework is designed to solve ordinary differential equations (ODEs) using linear multistep methods. This approach is widely used for time integration of ODE systems arising from the dynamics of mechanical models, particularly those involving constraints and nonlinearities.</p>\n\n<h3>Linear Multistep Methods</h3>\n\n<p>A general form of a linear multistep method can be expressed as:</p>\n\n\\[\n\\sum_{j=0}^{s} a_j y_{n+j} = h \\sum_{j=0}^{s} b_j f(t_{n+j}, y_{n+j}),\n\\]\n\n<p>where:</p>\n\n<ul>\n  <li>\\(y_n\\) represents the solution at time step \\(t_n\\).</li>\n  <li>\\(f(t, y)\\) is the right-hand side of the ODE (the derivative function).</li>\n  <li>\\(a_j\\) and \\(b_j\\) are coefficients that define the specific multistep method.</li>\n  <li>\\(h\\) is the time step size.</li>\n</ul>\n\n<p>The class provides a generic framework for implementing such methods by defining the residual based on these coefficients. The coefficients \\(a_j\\) and \\(b_j\\) are stored in `m_a_coef` and `m_b_coef`, respectively, which must be computed by derived classes according to their specific method (e.g., Adams-Bashforth, Adams-Moulton).</p>\n\n<h3>Residual Computation</h3>\n\n<p>The residual is a measure of the discrepancy between the current solution estimate and the exact solution. In `BaseLinearMultiStepMethod`, the residual \\(r\\) is split into two parts:</p>\n\n\\[\nr = (r_1, r_2),\n\\]\n\n<p>where:</p>\n\n<ul>\n  <li>\\(r_1\\): Residual related to position updates.</li>\n  <li>\\(r_2\\): Residual related to velocity updates and forces.</li>\n</ul>\n\n<h3>Newtown-Raphson Solver Integration</h3>\n\n<p>To handle nonlinear systems, the class utilizes a Newton-Raphson solver (`NewtonRaphsonSolver`). The `solve()` method performs the following steps:</p>\n\n<ol>\n  <li>Initializes the state (positions and velocities) using previous time step values.</li>\n  <li>Predicts positions based on current velocity estimates.</li>\n  <li>Evaluates the residual \\(r\\).</li>\n  <li>Solves a linear system for the change in velocity \\(dv\\).</li>\n  <li>Updates positions and velocities based on the computed changes.</li>\n</ol>\n\n<h3>Rayleigh Damping</h3>\n\n<p>The class also incorporates Rayleigh damping, which is defined by two parameters:</p>\n\n<ul>\n  <li>\\(C_M\\) (d_rayleighMass): Mass-proportional damping coefficient.</li>\n  <li>\\(C_K\\) (d_rayleighStiffness): Stiffness-proportional damping coefficient.</li>\n</ul>\n\n<p>The damping matrix \\(D\\) is given by:</p>\n\n\\[\nD = C_M M + C_K K,\n\\]\n\n<p>where:</p>\n\n<ul>\n  <li>\\(M\\): Mass matrix.</li>\n  <li>\\(K\\): Stiffness matrix.</li>\n</ul>\n\n<h3>Data Structures and Memory Management</h3>\n\n<p>The class manages multiple vectors to store positions, velocities, forces, residuals, and intermediate values. These are dynamically allocated as needed using the `realloc()` method.</p>\n\n<h2>Physical Description</h2>\n\n<p>In physical terms, the `BaseLinearMultiStepMethod` is used for time integration of mechanical systems described by ODEs. This can include:</p>\n\n<ul>\n  <li>Rigid and deformable bodies.</li>\n  <li>Contact mechanics (collisions and contacts between objects).</li>\n  <li>Constraints (e.g., rigid links, joints).</li>\n</ul>\n\n<p>The method integrates the equations of motion over time steps to predict future states. By leveraging multistep methods, it can achieve higher accuracy with fewer evaluations compared to single-step methods like Euler or Runge-Kutta.</p>\n\n<h3>Application in SOFA Framework</h3>\n\n<p>In the context of the SOFA framework, this method is crucial for simulating dynamic mechanical systems. The derived classes (such as specific multistep solvers) can be tailored to meet the requirements of different simulations, such as:</p>\n\n<ul>\n  <li>Real-time physics-based animation.</li>\n  <li>Mechanical engineering analysis.</li>\n  <li>Bio-mechanical modeling.</li>\n</ul>"
  },
  "summary": {
    "abstract": "`BaseLinearMultiStepMethod` is a base class for linear multistep methods in SOFA, providing a generic framework to solve ODEs using coefficients defined by derived classes and integrating with a Newton-Raphson solver.",
    "sheet": "# BaseLinearMultiStepMethod\n\n## Overview\n\nThe `BaseLinearMultiStepMethod` is a base class for implementing linear multistep methods used in the SOFA framework to solve ordinary differential equations (ODEs). It provides a generic framework that computes residuals based on coefficients defined by derived classes. The component integrates with a Newton-Raphson solver (`NewtonRaphsonSolver`) to handle nonlinear systems.\n\n## Mathematical Model\n\nA linear multistep method is defined as:\n\n\begin{equation}\n\\sum_{j=0}^{s} a_j y_{n+j} = h \\sum_{j=0}^{s} b_j f(t_{n+j}, y_{n+j}),\n\\end{equation}\n\nwhere $y_n$ represents the solution at time step $t_n$, $f(t, y)$ is the derivative function, and $a_j$ and $b_j$ are coefficients that define the specific multistep method. The class provides a generic framework for implementing such methods by defining the residual based on these coefficients.\n\nThe damping matrix $D$ incorporates Rayleigh damping:\n\n\begin{equation}\nD = C_M M + C_K K,\n\\end{equation}\n\nwhere $C_M$ and $C_K$ are mass-proportional and stiffness-proportional damping coefficients, respectively.\n\n## Parameters and Data\n\n- **d_rayleighStiffness**: Rayleigh damping coefficient related to stiffness, greater than 0. (Type: SReal)\n- **d_rayleighMass**: Rayleigh damping coefficient related to mass, greater than 0. (Type: SReal)\n\n## Dependencies and Connections\n\nThe `BaseLinearMultiStepMethod` requires a Newton-Raphson solver (`NewtonRaphsonSolver`) linked through the `l_newtonSolver` field to solve nonlinear equations generated by the numerical method."
  }
}