{
  "name": "ImprovedJacobiConstraintSolver",
  "main": {
    "name": "ImprovedJacobiConstraintSolver",
    "namespace": "sofa::component::constraint::lagrangian::solver",
    "module": "Sofa.Component.Constraint.Lagrangian.Solver",
    "include": "sofa/component/constraint/lagrangian/solver/ImprovedJacobiConstraintSolver.h",
    "doc": "A Constraint Solver using the Linear Complementarity Problem formulation to solve Constraint based components using a Projected Jacobi iterative method",
    "inherits": [
      "BuiltConstraintSolver"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_useSpectralCorrection",
        "type": "bool",
        "xmlname": "useSpectralCorrection",
        "help": "If set to true, the solution found after each iteration will be multiplied by spectralCorrectionFactor*2/spr(W), with spr() denoting the spectral radius."
      },
      {
        "name": "d_spectralCorrectionFactor",
        "type": "SReal",
        "xmlname": "spectralCorrectionFactor",
        "help": "Factor used to modulate the spectral correction"
      },
      {
        "name": "d_useConjugateResidue",
        "type": "bool",
        "xmlname": "useConjugateResidue",
        "help": "If set to true, the solution found after each iteration will be corrected along the solution direction using `\\\\lambda^{i+1} -= beta^{i} * (\\\\lambda^{i} - \\\\lambda^{i-1})` with beta following the formula beta^{i} = min(1, (i/maxIterations)^{conjugateResidueSpeedFactor}) "
      },
      {
        "name": "d_conjugateResidueSpeedFactor",
        "type": "SReal",
        "xmlname": "conjugateResidueSpeedFactor",
        "help": "Factor used to modulate the speed in which beta used in the conjugate residue part reaches 1.0. The higher the value, the slower the reach. "
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "doSolve",
        "return_type": "void",
        "params": [
          {
            "name": "problem",
            "type": "GenericConstraintProblem *"
          },
          {
            "name": "timeout",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `ImprovedJacobiConstraintSolver` is a constraint solver component in the SOFA framework, designed to solve constraint-based components using a Projected Jacobi iterative method. It inherits from `BuiltConstraintSolver` and implements the Linear Complementarity Problem (LCP) formulation. This solver aims to improve upon traditional Jacobi methods by incorporating spectral correction and conjugate residue techniques for enhanced convergence.\n\n**Role in SOFA Ecosystem**: \n- **Purpose**: The component is used within mechanical systems where constraints need to be solved iteratively, ensuring that all mechanical components adhere to specified constraints (e.g., contact, boundary conditions).\n\n**Interactions with Other Components**:\n- It interacts with `GenericConstraintProblem`, which represents the constraint problem to be solved.\n- The solver operates on the `problem` object passed to its `doSolve` method, where it performs iterative updates until convergence or a maximum number of iterations is reached.\n\n**Practical Usage and Data Fields**:\n- **useSpectralCorrection**: A boolean flag that enables spectral correction. When set to true, the solution after each iteration is adjusted using a factor based on the spectral radius.\n- **spectralCorrectionFactor**: A scaling factor used in conjunction with `useSpectralCorrection` to modulate the effect of spectral correction.\n- **useConjugateResidue**: Another boolean flag enabling conjugate residue corrections, which helps improve convergence by adjusting the solution direction iteratively.\n- **conjugateResidueSpeedFactor**: A parameter that controls how quickly the beta factor in the conjugate residue method reaches 1.0; higher values slow down this process."
  },
  "maths": {
    "maths": "<p>The `ImprovedJacobiConstraintSolver` is designed to solve constraint-based systems using the Projected Jacobi iterative method within the SOFA framework. It operates by iteratively updating Lagrange multipliers associated with constraints until convergence criteria are met. This solver addresses the Linear Complementarity Problem (LCP) formulation for constraint resolution, enhancing traditional Jacobi methods through spectral correction and conjugate residue techniques.</p>\n\n<p><strong>Mathematical Formulation:</strong></p>\n\n<ol>\n\t<li>The LCP formulation is given by:\n\t$$\n\t\\begin{align*}\n\t0 \\leq d &amp;\\perp w(d) + f \\geq 0, \\\\\n\tw(d) &= Wd + f,\n\t\\end{align*}\n\t$$\n\n\twhere $d$ are the Lagrange multipliers, $W$ is a matrix representing the constraints' stiffness, and $f$ represents external forces or residuals.</li>\n\n\t<li>The iterative update process for the Lagrange multipliers involves:</li>\n</ol>\n\n<p>At each iteration $i$, the solution $d^{(i)}$ is updated as follows:\n$$\nd^{(i+1)} = \\rho d^{(i)} + \\beta (\\lambda^{(i)} - \\lambda^{(i-1)}) + w(d^{(i)}),\n$$\nwhere:</p>\n\n<ul>\n\t<li>$\\rho$ is a scaling factor based on spectral correction, defined as:\n\t$$\n\t\\rho = \\begin{cases}\n\t\\gamma \\frac{2}{\\text{spr}(W)}, &amp; \\text{if } d_{useSpectralCorrection} = \\text{true}, \\\\\n\t1, &amp; \\text{otherwise},\n\t\\end{cases}\n\t$$\n\n\twith $\\gamma$ being the spectral correction factor.</li>\n</ul>\n\n<ul>\n\t<li>$\\beta$ is a conjugate residue factor defined as:\n\t$$\n\t\\beta = \\begin{cases}\n\t\\min(1, (i / \\text{maxIterations})^{d_{conjugateResidueSpeedFactor}}), &amp; \\text{if } d_{useConjugateResidue} = \\text{true}, \\\\\n\t0, &amp; \\text{otherwise}. \n\t\\end{cases}\n\t$$\n\n\twhere $d_{conjugateResidueSpeedFactor}$ controls the speed at which $\\beta$ reaches 1.0.</li>\n</ul>\n\n<p><strong>Role in FEM Pipeline:</strong></p>\n\n<ul>\n\t<li>The `ImprovedJacobiConstraintSolver` plays a critical role during the nonlinear solution phase of the FEM pipeline by solving constraint-based systems using iterative methods.</li>\n\t<li>In the context of variational mechanics and Lagrangian dynamics, this solver ensures that constraints (e.g., contact forces, boundary conditions) are satisfied within the system. It operates on the global residual $R(x)$ to ensure the nonlinear equations of motion are solved accurately.</li>\n</ul>\n\n<p><strong>Numerical Methods:</strong></p>\n\n<ul>\n\t<li>The solver employs a Projected Jacobi method for iterative solution refinement, which is particularly useful in handling large-scale constraint systems where traditional direct methods may be computationally prohibitive.</li>\n\t<li>Spectral correction and conjugate residue techniques enhance the convergence properties of the iterative process. Spectral correction helps to avoid divergence by scaling the update step based on the spectral radius of the stiffness matrix $W$, while conjugate residue techniques adjust the solution direction iteratively, improving overall convergence speed.</li>\n</ul>"
  },
  "summary": {
    "abstract": "The `ImprovedJacobiConstraintSolver` solves constraint-based systems using the Linear Complementarity Problem (LCP) formulation with a Projected Jacobi iterative method, incorporating spectral correction and conjugate residue techniques for enhanced convergence.",
    "sheet": "\n# ImprovedJacobiConstraintSolver\n\n## Overview\n\nThe `ImprovedJacobiConstraintSolver` is designed to solve constraint-based systems within the SOFA framework using the Linear Complementarity Problem (LCP) formulation. It inherits from `BuiltConstraintSolver` and employs a Projected Jacobi iterative method, enhanced with spectral correction and conjugate residue techniques for improved convergence.\n\n## Mathematical Model\n\nThe LCP formulation is given by:\n\\[\n0 \\leq d \\perp w(d) + f \\geq 0,\n\\]\nwhere $d$ are the Lagrange multipliers, $W$ is a matrix representing the constraints' stiffness, and $f$ represents external forces or residuals.\n\nThe iterative update process for the Lagrange multipliers involves:\n\\[\nd^{(i+1)} = \\rho d^{(i)} + \\beta (\\lambda^{(i)} - \\lambda^{(i-1)}) + w(d^{(i)}),\n\\]\nwhere $\\rho$ is a scaling factor based on spectral correction, defined as:\n\\[\n\\rho = \n\\begin{cases}\n\\gamma \\frac{2}{\\text{spr}(W)}, &amp; \\text{if } d_{useSpectralCorrection} = \\text{true}, \\\\\n1, &amp; \\text{otherwise},\n\\end{cases}\n\\]\nwith $\\gamma$ being the spectral correction factor.\n\nThe conjugate residue factor $\\beta$ is defined as:\n\\[\n\\beta = \n\\begin{cases}\n\\min(1, (i / \\text{maxIterations})^{d_{conjugateResidueSpeedFactor}}), &amp; \\text{if } d_{useConjugateResidue} = \\text{true}, \\\\\n0, &amp; \\text{otherwise}. \n\\end{cases}\n\\]\nwhere $d_{conjugateResidueSpeedFactor}$ controls the speed at which $\\beta$ reaches 1.0.\n\n## Parameters and Data\n\n- **useSpectralCorrection**: A boolean flag that enables spectral correction. When set to true, the solution after each iteration is adjusted using a factor based on the spectral radius.\n- **spectralCorrectionFactor**: A scaling factor used in conjunction with `useSpectralCorrection` to modulate the effect of spectral correction.\n- **useConjugateResidue**: Another boolean flag enabling conjugate residue corrections, which helps improve convergence by adjusting the solution direction iteratively.\n- **conjugateResidueSpeedFactor**: A parameter that controls how quickly the beta factor in the conjugate residue method reaches 1.0; higher values slow down this process.\n\n## Practical Notes\n\nThe `ImprovedJacobiConstraintSolver` enhances traditional Jacobi methods by incorporating spectral correction and conjugate residue techniques, which improve convergence properties. Spectral correction helps avoid divergence by scaling the update step based on the spectral radius of the stiffness matrix $W$, while conjugate residue techniques adjust the solution direction iteratively to enhance overall convergence speed."
  }
}