Data Fields

Methods

{
  "name": "NewtonRaphsonSolver",
  "namespace": "sofa::component::odesolver::backward",
  "module": "Sofa.Component.ODESolver.Backward",
  "include": "sofa/component/odesolver/backward/NewtonRaphsonSolver.h",
  "doc": "Generic Newton-Raphson algorithm solving nonlinear equations.",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_maxNbIterationsNewton",
      "type": "unsigned int",
      "xmlname": "maxNbIterationsNewton",
      "help": "Maximum number of iterations of the Newton's method if it has not converged."
    },
    {
      "name": "d_relativeSuccessiveStoppingThreshold",
      "type": "SReal",
      "xmlname": "relativeSuccessiveStoppingThreshold",
      "help": " than this threshold."
    },
    {
      "name": "d_relativeInitialStoppingThreshold",
      "type": "SReal",
      "xmlname": "relativeInitialStoppingThreshold",
      "help": " root."
    },
    {
      "name": "d_absoluteResidualStoppingThreshold",
      "type": "SReal",
      "xmlname": "absoluteResidualStoppingThreshold",
      "help": "iteration found an estimate close to the root."
    },
    {
      "name": "d_relativeEstimateDifferenceThreshold",
      "type": "SReal",
      "xmlname": "relativeEstimateDifferenceThreshold",
      "help": "estimates divided by the previous estimate is smaller than this threshold"
    },
    {
      "name": "d_absoluteEstimateDifferenceThreshold",
      "type": "SReal",
      "xmlname": "absoluteEstimateDifferenceThreshold",
      "help": "estimates is smaller than this threshold."
    },
    {
      "name": "d_maxNbIterationsLineSearch",
      "type": "unsigned int",
      "xmlname": "maxNbIterationsLineSearch",
      "help": "Maximum number of iterations of the line search method if it has not converged."
    },
    {
      "name": "d_lineSearchCoefficient",
      "type": "SReal",
      "xmlname": "lineSearchCoefficient",
      "help": "Line search coefficient"
    },
    {
      "name": "d_updateStateWhenDiverged",
      "type": "bool",
      "xmlname": "updateStateWhenDiverged",
      "help": "iterative process is considered diverged."
    },
    {
      "name": "d_status",
      "type": "NewtonStatus",
      "xmlname": "status",
      "help": "status\\n"
    },
    {
      "name": "d_warnWhenLineSearchFails",
      "type": "bool",
      "xmlname": "warnWhenLineSearchFails",
      "help": "Trigger a warning if line search fails"
    },
    {
      "name": "d_warnWhenDiverge",
      "type": "bool",
      "xmlname": "warnWhenDiverge",
      "help": "Trigger a warning if Newton-Raphson diverges"
    }
  ],
  "links": [],
  "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": "function",
          "type": "newton_raphson::BaseNonLinearFunction &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "start",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initialConvergence",
      "return_type": "void",
      "params": [
        {
          "name": "squaredResidualNorm",
          "type": "SReal"
        },
        {
          "name": "squaredAbsoluteStoppingThreshold",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "measureConvergence",
      "return_type": "bool",
      "params": [
        {
          "name": "measure",
          "type": "const NewtonRaphsonConvergenceMeasure &"
        },
        {
          "name": "os",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "lineSearchIteration",
      "return_type": "void",
      "params": [
        {
          "name": "function",
          "type": "newton_raphson::BaseNonLinearFunction &"
        },
        {
          "name": "squaredResidualNorm",
          "type": "SReal &"
        },
        {
          "name": "lineSearchCoefficient",
          "type": "const SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    }
  ],
  "description": "The `NewtonRaphsonSolver` is a nonlinear solver in the SOFA framework, designed to solve nonlinear equations using the Newton-Raphson algorithm. It inherits from `BaseObject`, which is fundamental for integrating with the scene graph architecture and interacting with other components. The component provides configurable stopping criteria and convergence measures, enabling precise control over the iterative solution process.\n\nThe solver interacts with other SOFA components through its `solve` method, which takes a nonlinear function object (`newton_raphson::BaseNonLinearFunction`) as input. This allows it to be integrated into various simulation scenarios where nonlinear equations need to be solved.\n\nPractical usage involves setting the stopping criteria and thresholds to ensure convergence. Key data fields include:\n- `maxNbIterationsNewton`: Maximum number of Newton iterations before convergence is forced.\n- `relativeSuccessiveStoppingThreshold`, `relativeInitialStoppingThreshold`, `absoluteResidualStoppingThreshold`, `relativeEstimateDifferenceThreshold`, `absoluteEstimateDifferenceThreshold`: Various thresholds for different stopping criteria.\n- `maxNbIterationsLineSearch` and `lineSearchCoefficient`: Parameters to control the line search method within each Newton iteration.\n\nThe solver can also trigger warnings when it fails to converge or encounters issues with the line search, aiding in debugging and tuning the simulation parameters.",
  "maths": "The `NewtonRaphsonSolver` in the SOFA framework implements the Newton-Raphson algorithm to solve nonlinear equations, which are typically derived from variational formulations and discretizations. The solver is designed for scenarios where a system of nonlinear equations needs to be solved implicitly, such as in nonlinear structural dynamics or large deformation mechanics.\n\n### Governing Equations\nThe Newton-Raphson method is used to find the roots of a system of nonlinear equations, denoted by \\( R(x) = 0 \\), where \\( x \\) represents the unknown variables (e.g., nodal displacements). The residual vector \\( R(x) \\) can be related to the governing equations in FEM as follows:\n\n\begin{equation}\nR(x_{k+1}) = M\\frac{x_{k+1}-x_k}{Δ t} - Δ t f_{int}(x_{k+1}) - Δ t f_{ext} = 0\n\tag{1}\n\tag{2}\n\tag{3}\n\tag{4}\n\tag{5}\n\tag{6}\n\tag{7}\n\tag{8}\n\tag{9}\n\tag{10}\n\tag{11}\n\tag{12}\n\tag{13}\n\tag{14}\n\tag{15}\n\tag{16}\n\tag{17}\n\tag{18}\n\tag{19}\n\tag{20}\n\tag{21}\n\tag{22}\n\tag{23}\n\tag{24}\n\tag{25}\n\tag{26}\n\tag{27}\n\tag{28}\n\tag{29}\n\tag{30}\n\tag{31}\n\tag{32}\n\tag{33}\n\tag{34}\n\tag{35}\n\tag{36}\n\tag{37}\n\tag{38}\n\tag{39}\n\tag{40}\n\tag{41}\n\tag{42}\n\tag{43}\n\tag{44}\n\tag{45}\n\tag{46}\n\tag{47}\n\tag{48}\n\tag{49}\n\tag{50}\n\tag{51}\n\tag{52}\n\tag{53}\n\tag{54}\n\tag{55}\n\tag{56}\n\tag{57}\n\tag{58}\n\tag{59}\n\tag{60}\n\tag{61}\n\tag{62}\n\tag{63}\n\tag{64}\n\tag{65}\n\tag{66}\n\tag{67}\n\tag{68}\n\tag{69}\n\tag{70}\n\tag{71}\n\tag{72}\n\tag{73}\n\tag{74}\n\tag{75}\n\tag{76}\n\tag{77}\n\tag{78}\n\tag{79}\n\tag{80}\n\tag{81}\n\tag{82}\n\tag{83}\n\tag{84}\n\tag{85}\n\tag{86}\n\tag{87}\n\tag{88}\n\tag{89}\n\tag{90}\n\tag{91}\n\tag{92}\n\tag{93}\n\tag{94}\n\tag{95}\n\tag{96}\n\tag{97}\n\tag{98}\n\tag{99}\n\tag{100}\n\n\begin{equation}\nR(x_{k+1}) = M\frac{x_{k+1}-x_k}{Δ t} - Δ t f_{int}(x_{k+1}) - Δ t f_{ext} = 0\n\tag{2}\n\n### Linearization and Iterative Process\nAt each iteration \\( k \\), the Newton-Raphson method linearizes the residual around an estimate \\( x_k \\):\n\n\begin{equation}\nR(x_k + Δ x) ≈ R(x_k) + J(x_k)Δ x = 0,\n\tag{3}\n\nwhere \\( J(x_k) \\) is the Jacobian matrix of \\( R(x) \\):\n\n\begin{equation}\nJ(x_k) = ∂ R / ∂ x |_{x=x_k}.\n\tag{4}\n\nSolving for \\( Δ x \\), we get:\n\n\begin{equation}\nΔ x = - J(x_k)^{-1} R(x_k).\n\tag{5}\n\nThe new estimate is then updated as:\n\n\begin{equation}\nx_{k+1} = x_k + Δ x.\n\tag{6}\n\n### Convergence Criteria\nThe solver employs multiple stopping criteria to ensure convergence:\n- **Relative Successive Stopping Threshold**: The iteration stops if the ratio of successive residual norms is below a threshold \\( θ_{ss} \\):\n\n\begin{equation}\nρ_k = \frac{∣ R(x_k) ∣}{∣ R(x_{k-1}) ∣} < θ_{ss}.\n\tag{7}\n\n- **Relative Initial Stopping Threshold**: The iteration stops if the ratio of the current residual norm to the initial residual norm is below a threshold \\( θ_{ri} \\):\n\n\begin{equation}\nρ_k = \frac{∣ R(x_k) ∣}{∣ R(x_0) ∣} < θ_{ri}.\n\tag{8}\n\n- **Absolute Residual Stopping Threshold**: The iteration stops if the current residual norm is below an absolute threshold \\( τ_a \\):\n\n\begin{equation}\n∣ R(x_k) ∣ < τ_a.\n\tag{9}\n\n- **Relative and Absolute Estimate Difference Thresholds**: The iteration stops if the difference between successive estimates is below a relative or absolute threshold:\n\n\begin{equation}\nθ_{rd} = \frac{∣ x_k - x_{k-1} ∣}{∣ x_{k-1} ∣}, τ_d = ∣ x_k - x_{k-1} ∣.\n\tag{10}\n\n### Numerical Methods and Discretization\nThe solver uses iterative methods to solve the linear system \\( J(x_k)Δ x = -R(x_k) \\). Line search is employed within each Newton iteration to ensure descent:\n- **Line Search**: The step size \\( α \\) in \\( x_{k+1} = x_k + α Δ x \\) is adjusted until a sufficient decrease condition is met.\n\n### Role in the FEM Pipeline\nThe `NewtonRaphsonSolver` fits into the broader variational / Lagrangian mechanics framework by:\n- **Handling Nonlinear Solve**: It linearizes and iteratively solves nonlinear residual equations derived from weak forms and discretizations.\n- **Convergence Control**: It ensures that the iterative process converges to a solution through various stopping criteria.\n- **Time Integration Compatibility**: The solver can be used in conjunction with implicit time integration schemes, such as Backward Euler or Newmark-type methods, for dynamic simulations.\n\n### Summary\nThe `NewtonRaphsonSolver` provides a robust and flexible nonlinear solver that is essential for solving complex systems of equations arising from variational formulations and FEM discretizations. Its role in the simulation pipeline ensures accurate and stable solutions for deformable body mechanics.",
  "abstract": "The `NewtonRaphsonSolver` solves systems of nonlinear equations using the Newton-Raphson algorithm with configurable stopping criteria and convergence measures.",
  "sheet": "# NewtonRaphsonSolver\n\n## Overview\nThe `NewtonRaphsonSolver` is a nonlinear solver in SOFA that uses the Newton-Raphson method to solve systems of nonlinear equations. It interacts with other components through its `solve` method, which takes a nonlinear function object as input.\n\n## Mathematical Model\nThe Newton-Raphson method linearizes and iteratively solves the residual equation:\n\\[ R(x_{k+1}) = M \\frac{x_{k+1} - x_k}{Δt} - Δt f_{int}(x_{k+1}) - Δt f_{ext} = 0. \\]\nAt each iteration, it linearizes the residual around an estimate $x_k$:\n\\[ R(x_k + Δx) ≈ R(x_k) + J(x_k)Δx = 0, \\]\nwhere $J(x_k)$ is the Jacobian matrix of $R(x)$. The new estimate is updated as:\n\\[ x_{k+1} = x_k + Δx. \\]\nThe solver employs multiple stopping criteria to ensure convergence.\n\n## Parameters and Data\n- `maxNbIterationsNewton`: Maximum number of Newton iterations before convergence is forced (default: not specified).\n- `relativeSuccessiveStoppingThreshold`, `relativeInitialStoppingThreshold`, `absoluteResidualStoppingThreshold`, `relativeEstimateDifferenceThreshold`, `absoluteEstimateDifferenceThreshold`: Various thresholds for different stopping criteria.\n- `maxNbIterationsLineSearch` and `lineSearchCoefficient`: Parameters to control the line search method within each Newton iteration.\n\n## Practical Notes\nThe solver can trigger warnings when it fails to converge or encounters issues with the line search, aiding in debugging and tuning simulation parameters."
}