{
  "name": "GenericConstraintSolver",
  "main": {
    "name": "GenericConstraintSolver",
    "namespace": "sofa::component::constraint::lagrangian::solver",
    "module": "Sofa.Component.Constraint.Lagrangian.Solver",
    "include": "sofa/component/constraint/lagrangian/solver/GenericConstraintSolver.h",
    "doc": "",
    "inherits": [
      "ConstraintSolverImpl"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_maxIt",
        "type": "int",
        "xmlname": "maxIterations",
        "help": "maximal number of iterations of iterative algorithm"
      },
      {
        "name": "d_tolerance",
        "type": "SReal",
        "xmlname": "tolerance",
        "help": "residual error threshold for termination of the Gauss-Seidel algorithm"
      },
      {
        "name": "d_sor",
        "type": "SReal",
        "xmlname": "sor",
        "help": "Successive Over Relaxation parameter (0-2)"
      },
      {
        "name": "d_regularizationTerm",
        "type": "SReal",
        "xmlname": "regularizationTerm",
        "help": "Add regularization factor times the identity matrix to the compliance W when solving constraints"
      },
      {
        "name": "d_scaleTolerance",
        "type": "bool",
        "xmlname": "scaleTolerance",
        "help": "Scale the error tolerance with the number of constraints"
      },
      {
        "name": "d_allVerified",
        "type": "bool",
        "xmlname": "allVerified",
        "help": "All constraints must be verified (each constraint's error < tolerance)"
      },
      {
        "name": "d_computeGraphs",
        "type": "bool",
        "xmlname": "computeGraphs",
        "help": "Compute graphs of errors and forces during resolution"
      },
      {
        "name": "d_currentNumConstraints",
        "type": "int",
        "xmlname": "currentNumConstraints",
        "help": "OUTPUT: current number of constraints"
      },
      {
        "name": "d_currentNumConstraintGroups",
        "type": "int",
        "xmlname": "currentNumConstraintGroups",
        "help": "OUTPUT: current number of constraints"
      },
      {
        "name": "d_currentIterations",
        "type": "int",
        "xmlname": "currentIterations",
        "help": "OUTPUT: current number of constraint groups"
      },
      {
        "name": "d_currentError",
        "type": "SReal",
        "xmlname": "currentError",
        "help": "OUTPUT: current error"
      },
      {
        "name": "d_computeConstraintForces",
        "type": "bool",
        "xmlname": "computeConstraintForces",
        "help": "enable the storage of the constraintForces."
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "cleanup",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "prepareStates",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "res1",
            "type": "MultiVecId"
          },
          {
            "name": "res2",
            "type": "MultiVecId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildSystem",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "res1",
            "type": "MultiVecId"
          },
          {
            "name": "res2",
            "type": "MultiVecId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "rebuildSystem",
        "return_type": "void",
        "params": [
          {
            "name": "massFactor",
            "type": "const SReal"
          },
          {
            "name": "forceFactor",
            "type": "const SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "solveSystem",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "res1",
            "type": "MultiVecId"
          },
          {
            "name": "res2",
            "type": "MultiVecId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyCorrection",
        "return_type": "bool",
        "params": [
          {
            "name": "",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "res1",
            "type": "MultiVecId"
          },
          {
            "name": "res2",
            "type": "MultiVecId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeResidual",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::ExecParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintProblem",
        "return_type": "ConstraintProblem *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "lockConstraintProblem",
        "return_type": "void",
        "params": [
          {
            "name": "from",
            "type": "sofa::core::objectmodel::BaseObject *"
          },
          {
            "name": "p1",
            "type": "ConstraintProblem *"
          },
          {
            "name": "p2",
            "type": "ConstraintProblem *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getLambda",
        "return_type": "sofa::core::MultiVecDerivId",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getDx",
        "return_type": "sofa::core::MultiVecDerivId",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "clearConstraintProblemLocks",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "initializeConstraintProblems",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "doBuildSystem",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "problem",
            "type": "GenericConstraintProblem *"
          },
          {
            "name": "numConstraints",
            "type": "unsigned int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "doSolve",
        "return_type": "void",
        "params": [
          {
            "name": "problem",
            "type": "GenericConstraintProblem *"
          },
          {
            "name": "timeout",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addRegularization",
        "return_type": "void",
        "params": [
          {
            "name": "W",
            "type": "linearalgebra::BaseMatrix &"
          },
          {
            "name": "regularization",
            "type": "const SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `GenericConstraintSolver` is a SOFA component in the Lagrangian constraint solver module, designed to handle and solve general constraint problems involving constraints on degrees-of-freedom (DOFs). This component inherits from `ConstraintSolverImpl` and provides an interface for preparing, building, solving, and applying corrections to constraint systems. The interactions with other components are primarily through the API methods that prepare states, build systems, solve constraint problems, apply motion correction, and compute residuals.\n\nIt supports iterative algorithms such as Gauss-Seidel and allows customization via parameters like `maxIterations`, `tolerance`, and `Successive Over Relaxation (SOR)` factor. The component also manages regularization for the constraints to improve numerical stability.\n\nUsers can configure `GenericConstraintSolver` with several data fields, including setting the maximum number of iterations (`maxIterations`), tolerance levels (`tolerance`), SOR relaxation parameter (`sor`), and regularization term (`regularizationTerm`). The solver stores output information like the current error, number of constraints, constraint groups, and iterations.\n\nAdditionally, it provides options to compute and store graphs of errors, forces, and violations during the resolution process. Users can enable or disable the storage of constraint forces with `computeConstraintForces`."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the GenericConstraintSolver Component\n\n## Introduction\nThe `GenericConstraintSolver` is a key component in the SOFA framework, specifically designed to handle general constraint problems in Lagrangian mechanics. It is responsible for solving systems of constraints that are applied to degrees-of-freedom (DOFs) within a mechanical system. The solver supports iterative methods such as Gauss-Seidel and allows customization through parameters like maximum iterations, tolerance levels, and the Successive Over Relaxation (SOR) factor.\n\n## Mathematical Model\nThe core problem addressed by `GenericConstraintSolver` can be formulated in terms of a system of constraints on the mechanical DOFs. Let's denote the set of all constraints as $C = \\{c_1, c_2, ..., c_m\\}$ where each constraint $c_i$ imposes a restriction on the positions and velocities of the objects within the simulation.\n\n### Constraint Matrix (W)\nThe system of constraints is typically represented by a matrix $W$, often referred to as the Jacobian or constraint matrix. Each row of $W$ corresponds to a specific constraint, and each column corresponds to a degree-of-freedom (DOF). The entries in the matrix are partial derivatives of the constraints with respect to the DOFs:\n\n\\[ W_{ij} = \\frac{\\partial c_i}{\\partial q_j}, \\]\nwhere $q_j$ represents the j-th DOF.\n\n### Free Violation and Unknown Vector (f)\nThe vector $f$, known as the free violation, represents the violations of constraints that are not directly resolved by enforcing the constraints. The goal is to find a solution vector $\\lambda$ such that the system:\n\n\\[ W^T \\lambda + f = 0, \\]\nis satisfied within some tolerance level.\n\n### Iterative Solvers (Gauss-Seidel)\nThe `GenericConstraintSolver` employs iterative methods like Gauss-Seidel for solving the above equation. The Gauss-Seidel method updates the solution vector $\\lambda$ iteratively:\n\n1. **Initialization**: Initialize the vector $\\lambda^{(0)} = 0$.\n2. **Iteration**:\n   \\[ \\lambda_i^{(k+1)} = -\\frac{1}{W_{ii}} (f_i + W_{i,i-1} \\lambda_{i-1}^{(k+1)} + W_{i,i+1} \\lambda_{i+1}^{(k)} + ...), \\]\n   where $\\lambda_i^{(k+1)}$ is the updated value of the i-th component at iteration $(k+1)$.\n\n### Regularization (Id)\nThe system can be regularized by adding a multiple of the identity matrix to the constraint matrix $W$, which helps in improving numerical stability:\n\n\\[ W_{regularized} = W + \\alpha I, \\]\nwhere $\\alpha$ is the regularization term and $I$ is the identity matrix.\n\n### Successive Over Relaxation (SOR)\nThe SOR method accelerates convergence by using a relaxation parameter $\\omega$ that adjusts the step size of each update:\n   \\[ \\lambda_i^{(k+1)} = \\lambda_i^{(k)} + \\omega \\left(-\\frac{f_i + W_{i,i-1} \\lambda_{i-1}^{(k+1)} + ...}{W_{ii}}\\right). \\]\n\n## Physical Interpretation\nIn the physical context, each constraint $c_i$ represents a physical condition that must be satisfied by the mechanical system. For example:\n- **Position Constraints**: Ensure that certain points or objects maintain specific positions.\n- **Velocity Constraints**: Restrict the velocities of certain parts to achieve desired motion profiles.\n- **Contact Constraints**: Enforce non-penetration conditions between colliding bodies.\n\nThe solution vector $\\lambda$ represents Lagrange multipliers, which quantify the forces required to enforce these constraints. The free violation $f$ captures any remaining discrepancies in constraint satisfaction after applying $\\lambda$.\n\n## Conclusion\n`GenericConstraintSolver` provides a robust framework for solving complex constraint problems in mechanical simulations, ensuring that all imposed conditions are met within specified tolerances while maintaining numerical stability through regularization and iterative refinement techniques."
  },
  "summary": {
    "abstract": "The `GenericConstraintSolver` handles general constraint problems in Lagrangian mechanics by solving systems of constraints using iterative methods like Gauss-Seidel with Successive Over Relaxation (SOR) and regularization for numerical stability.",
    "sheet": "# GenericConstraintSolver\n\n## Overview\nThe `GenericConstraintSolver` is a component in the SOFA framework designed to handle general constraint problems in Lagrangian mechanics. It inherits from `ConstraintSolverImpl` and provides methods for preparing, building, solving, and applying corrections to constraint systems.\n\n## Mathematical Model\nThe core problem addressed by `GenericConstraintSolver` involves solving a system of constraints on degrees-of-freedom (DOFs). The constraints are represented by the matrix $W$, where each row corresponds to a specific constraint and each column to a DOF. The goal is to find a solution vector $\\lambda$ such that:\n\n\\[ W^T \\lambda + f = 0, \\]\nwhere $f$ represents the free violation.\n\nThe solver employs iterative methods like Gauss-Seidel for solving this equation. Regularization can be applied by adding a multiple of the identity matrix to $W$:\n\n\\[ W_{regularized} = W + \\alpha I, \\]\nwhere $\\alpha$ is the regularization term and $I$ is the identity matrix.\n\nSuccessive Over Relaxation (SOR) accelerates convergence using a relaxation parameter $\\omega$:\n\n\\[ \\lambda_i^{(k+1)} = \\lambda_i^{(k)} + \\omega \\left(-\\frac{f_i + W_{i,i-1} \\lambda_{i-1}^{(k+1)} + ...}{W_{ii}}\\right). \\]\n\n## Parameters and Data\nThe `GenericConstraintSolver` exposes several parameters for customization:\n\n- **maxIterations**: Maximum number of iterations of the iterative algorithm (`int`, default: not specified).\n- **tolerance**: Residual error threshold for termination of the Gauss-Seidel algorithm (`SReal`, default: not specified).\n- **sor**: Successive Over Relaxation parameter (0-2) (`SReal`, default: not specified).\n- **regularizationTerm**: Regularization factor added to the identity matrix when solving constraints (`SReal`, default: not specified).\n- **scaleTolerance**: Scale the error tolerance with the number of constraints (`bool`, default: not specified).\n- **allVerified**: All constraints must be verified (each constraint's error < tolerance) (`bool`, default: not specified).\n- **computeGraphs**: Compute graphs of errors and forces during resolution (`bool`, default: not specified).\n- **currentNumConstraints**: Current number of constraints (OUTPUT, `int`).\n- **currentNumConstraintGroups**: Current number of constraint groups (OUTPUT, `int`).\n- **currentIterations**: Current number of iterations (OUTPUT, `int`).\n- **currentError**: Current error (OUTPUT, `SReal`).\n- **computeConstraintForces**: Enable the storage of constraint forces (`bool`, default: not specified).\n\n## Practical Notes\nThe solver supports iterative methods like Gauss-Seidel and SOR for solving constraint systems. Regularization improves numerical stability by adding a multiple of the identity matrix to the constraint matrix $W$. The `maxIterations` parameter controls the maximum number of iterations, while `tolerance` sets the residual error threshold for termination. The `sor` parameter accelerates convergence with a relaxation factor between 0 and 2.\n\nThe solver also provides options to compute graphs of errors and forces during resolution (`computeGraphs`) and to store constraint forces (`computeConstraintForces`)."
  }
}