{
  "name": "BlockGaussSeidelConstraintSolver",
  "main": {
    "name": "BlockGaussSeidelConstraintSolver",
    "namespace": "sofa::component::constraint::lagrangian::solver",
    "module": "Sofa.Component.Constraint.Lagrangian.Solver",
    "include": "sofa/component/constraint/lagrangian/solver/BlockGaussSeidelConstraintSolver.h",
    "doc": "A Constraint Solver using the Linear Complementarity Problem formulation to solve Constraint based components using a Block Gauss-Seidel iterative method",
    "inherits": [
      "BuiltConstraintSolver"
    ],
    "templates": [],
    "data_fields": [],
    "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"
      },
      {
        "name": "gaussSeidel_increment",
        "return_type": "void",
        "params": [
          {
            "name": "measureError",
            "type": "bool"
          },
          {
            "name": "dfree",
            "type": "SReal *"
          },
          {
            "name": "force",
            "type": "SReal *"
          },
          {
            "name": "w",
            "type": "SReal **"
          },
          {
            "name": "tol",
            "type": "SReal"
          },
          {
            "name": "d",
            "type": "SReal *"
          },
          {
            "name": "dim",
            "type": "int"
          },
          {
            "name": "constraintsAreVerified",
            "type": "bool &"
          },
          {
            "name": "error",
            "type": "SReal &"
          },
          {
            "name": "constraintCorrections",
            "type": "int &"
          },
          {
            "name": "tabErrors",
            "type": "int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BlockGaussSeidelConstraintSolver` is a constraint solver in the SOFA framework designed to solve Constraint-based components using the Linear Complementarity Problem formulation with a Block Gauss-Seidel iterative method. It inherits from the `BuiltConstraintSolver` class and is part of the `Sofa.Component.Constraint.Lagrangian.Solver` module.\n\nThe component interacts with other SOFA components through its `doSolve` method, which takes a `GenericConstraintProblem` object as input to solve constraints iteratively. This method performs multiple iterations until either convergence criteria are met or a specified timeout occurs. The solver also includes the `gaussSeidel_increment` method for computing and updating constraint forces and errors during each iteration.\n\nThis component is particularly useful in simulations requiring iterative resolution of complex, interdependent constraints within a Lagrangian system. Practical usage involves configuring it to solve specific constraint problems where a Block Gauss-Seidel approach can efficiently converge to the solution."
  },
  "maths": {
    "maths": "<p>The `BlockGaussSeidelConstraintSolver` is designed to solve constraints using the Linear Complementarity Problem (LCP) formulation, employing a Block Gauss-Seidel iterative method. The solver iteratively updates constraint forces and errors until convergence criteria are met or a specified timeout occurs.</p>\n\n<h3>Mathematical Formulation</h3>\n\n<p>In the context of Lagrangian systems, constraints can be formulated as Linear Complementarity Problems (LCP). For a given set of constraints:</p>\n\n\\[ W \\mathbf{d} = \\mathbf{f}, \\]\n\n<p>where:</p>\n<ul>\n  <li>$W$ is the constraint matrix, which represents the linear relationship between the forces and displacements.</li>\n  <li>$\\mathbf{d}$ is the vector of displacements due to constraint forces.</li>\n  <li>$\\mathbf{f}$ is the vector of applied forces.</li>\n</ul>\n\n<p>The constraints are solved iteratively using a Block Gauss-Seidel method, which updates each block (constraint) one at a time. This process involves:</p>\n<ul>\n  <li>Initialization: Setting initial values for $\\mathbf{d}$ and $\\mathbf{f}$. Typically, $\\mathbf{d}$ is set to the displacement vector $\\mathbf{dfree}$.</li>\n  <li>Iteration over constraints: For each constraint, compute the contribution of forces to displacements:</li>\n</ul>\n\n\\[ d_j = dfree_j + \\sum_{k=1}^{dim} W_{jk} f_k. \\]\n\n<p>Then, solve for the specific resolution of the constraint using a method defined in `ConstraintResolution`. This step updates $d$ and $f$ to satisfy the constraints.</p>\n\n<ul>\n  <li>Error measurement: Measure the error due to the new resolution by comparing the updated forces with their previous values. The error is computed as:</li>\n</ul>\n\n\\[ \\text{error} = \\sum_{j=1}^{dim} || W_j (f - f_0) ||, \\]\n\n<p>where $W_j$ represents a block of the constraint matrix corresponding to the current constraint.</p>\n\n<ul>\n  <li>Convergence check: The solver iterates until either the error is below a specified tolerance or a maximum number of iterations is reached. If the error for any constraint exceeds its tolerance, `constraintsAreVerified` is set to false, and the iteration continues.</li>\n</ul>\n\n<h3>Implementation Details</h3>\n\n<p>The solver interacts with other SOFA components through the `doSolve` method:</p>\n<ul>\n  <li>Takes a `GenericConstraintProblem` object containing the constraint matrix $W$, displacement vector $\\mathbf{dfree}$, and applied forces $\\mathbf{f}$.</li>\n  <li>Performs iterations until convergence or timeout.</li>\n</ul>\n\n<p>The `gaussSeidel_increment` method is responsible for updating the constraint forces and errors during each iteration:</p>\n<ul>\n  <li>For each block (constraint), it computes the contribution of forces to displacements.</li>\n  <li>Calls the specific resolution method defined in `ConstraintResolution` for that block.</li>\n  <li>Measures error by comparing updated forces with their previous values and updates convergence criteria accordingly.</li>\n</ul>\n\n<p>The solver is particularly useful for simulations involving complex, interdependent constraints where iterative methods can efficiently converge to a solution.</p>"
  },
  "summary": {
    "abstract": "The `BlockGaussSeidelConstraintSolver` solves constraints using a Block Gauss-Seidel iterative method with Linear Complementarity Problem (LCP) formulation until convergence or timeout.",
    "sheet": "# BlockGaussSeidelConstraintSolver\n\n## Overview\n\nThe `BlockGaussSeidelConstraintSolver` is a constraint solver that uses the Linear Complementarity Problem (LCP) formulation to solve constraints iteratively. It inherits from the `BuiltConstraintSolver` class and operates within the SOFA framework.\n\n## Mathematical Model\n\nIn the context of Lagrangian systems, constraints can be formulated as Linear Complementarity Problems (LCP). The solver iteratively updates constraint forces and errors until convergence criteria are met or a specified timeout occurs. Given a set of constraints:\n\n\\[ W \\mathbf{d} = \\mathbf{f}, \\]\n\nwhere:\n- $W$ is the constraint matrix, representing the linear relationship between forces and displacements.\n- $\\mathbf{d}$ is the vector of displacements due to constraint forces.\n- $\\mathbf{f}$ is the vector of applied forces.\n\nThe Block Gauss-Seidel method updates each block (constraint) one at a time. Initialization sets initial values for $\\mathbf{d}$ and $\\mathbf{f}$. Typically, $\\mathbf{d}$ is set to the displacement vector $\\mathbf{dfree}$. For each constraint, compute the contribution of forces to displacements:\n\n\\[ d_j = dfree_j + \\sum_{k=1}^{dim} W_{jk} f_k. \\]\n\nThen, solve for the specific resolution of the constraint using a method defined in `ConstraintResolution`. This step updates $d$ and $f$ to satisfy the constraints.\n\nError measurement involves comparing updated forces with their previous values:\n\n\\[ \\text{error} = \\sum_{j=1}^{dim} || W_j (f - f_0) ||, \\]\n\nwhere $W_j$ represents a block of the constraint matrix corresponding to the current constraint. The solver iterates until either the error is below a specified tolerance or a maximum number of iterations is reached."
  }
}