{
  "name": "ConstraintSolverImpl",
  "main": {
    "name": "ConstraintSolverImpl",
    "namespace": "sofa::component::constraint::lagrangian::solver",
    "module": "Sofa.Component.Constraint.Lagrangian.Solver",
    "include": "sofa/component/constraint/lagrangian/solver/ConstraintSolverImpl.h",
    "doc": "",
    "inherits": [
      "ConstraintSolver"
    ],
    "templates": [],
    "data_fields": [],
    "links": [
      {
        "name": "l_constraintCorrections",
        "target": "BaseConstraintCorrection",
        "kind": "multi",
        "xmlname": "constraintCorrections",
        "help": "List of constraint corrections handled by this constraint solver"
      }
    ],
    "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": "getConstraintProblem",
        "return_type": "ConstraintProblem *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "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": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeConstraintCorrection",
        "return_type": "void",
        "params": [
          {
            "name": "s",
            "type": "core::behavior::BaseConstraintCorrection *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "postBuildSystem",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "postSolveSystem",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "clearConstraintCorrections",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "resetConstraints",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "buildLocalConstraintMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "constraintId",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "accumulateMatrixDeriv",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "buildConstraintMatrix",
        "return_type": "unsigned int",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "applyProjectiveConstraintOnConstraintMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "getConstraintViolation",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "v",
            "type": "sofa::linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "component": "ConstraintSolverImpl",
    "description": "The ConstraintSolverImpl is an abstract class in the SOFA (Simulation Open-Framework Architecture) framework that serves as a base for implementing constraint solvers within the Lagrangian solver context. It inherits from the `sofa::core::behavior::ConstraintSolver` class and is designed to handle constraints applied to mechanical systems, such as maintaining specific positions or orientations of objects.",
    "functions": {
      "init()": "Initializes the component by clearing any existing constraint corrections and adding all available BaseConstraintCorrection objects found in the current context to the list of links. It also registers this solver with each of these constraint corrections.",
      "cleanup()": "Cleans up by removing all registered constraint corrections and performing additional cleanup operations inherited from `sofa::core::behavior::ConstraintSolver`.",
      "removeConstraintCorrection(core::behavior::BaseConstraintCorrection* s)": "Removes a specific BaseConstraintCorrection object from the internal list of links and unregisters this solver from it.",
      "postBuildSystem(const core::ConstraintParams* cParams)": "Handles events post the build of system constraints by propagating a `sofa::simulation::BuildConstraintSystemEndEvent` through the context.",
      "postSolveSystem(const core::ConstraintParams* cParams)": "Propagates a `sofa::simulation::SolveConstraintSystemEndEvent` event through the context after the solving process is complete.",
      "clearConstraintCorrections()": "Clears all constraint corrections by unregistering this solver from each BaseConstraintCorrection object in the list and then clears the internal link list.",
      "resetConstraints(const core::ConstraintParams* cParams)": "Resets constraints for all mechanical states and BaseConstraintSet objects within the current context, such as clearing the constraint Jacobian matrix of a MechanicalObject.",
      "buildLocalConstraintMatrix(const core::ConstraintParams* cparams, unsigned int &constraintId)": "Builds local constraint matrices by executing `MechanicalBuildConstraintMatrix` visitor on the context's mechanical objects and updating the given constraint ID.",
      "accumulateMatrixDeriv(const core::ConstraintParams* cparams)": "Accumulates matrix derivatives of constraints through the `MechanicalAccumulateMatrixDeriv` visitor, projecting mapped constraint matrices onto the main constraint matrix.",
      "buildConstraintMatrix(const core::ConstraintParams* cparams)": "Constructs a complete constraint matrix by resetting existing constraints, building local constraint matrices, and accumulating matrix derivatives. It returns the total number of constraints created.",
      "applyProjectiveConstraintOnConstraintMatrix(const core::ConstraintParams* cparams)": "Applies projective constraints on the main constraint matrix through `MechanicalProjectJacobianMatrixVisitor` for the provided mechanical parameters.",
      "getConstraintViolation(const core::ConstraintParams* cparams, sofa::linearalgebra::BaseVector *v)": "Retrieves the current violation of constraints by executing a visitor to calculate the constraint violations and store them in the given vector."
    },
    "abstract_methods": {
      "getConstraintProblem()": "Returns a pointer to the ConstraintProblem instance that represents the problem to be solved.",
      "lockConstraintProblem(sofa::core::objectmodel::BaseObject* from, ConstraintProblem* p1, ConstraintProblem* p2=nullptr)": "Prevents concurrent access to the constraint problem until the next call. Used in scenarios like haptic feedback to prevent data race conditions."
    },
    "purpose": "This component serves as a backbone for more specific implementations of constraint solvers in SOFA, handling tasks such as registering constraints, building and solving constraint matrices, and ensuring proper synchronization during multi-threaded operations.",
    "related_classes": [
      "ConstraintSolver",
      "BaseConstraintCorrection",
      "MechanicalBuildConstraintMatrix",
      "MechanicalAccumulateMatrixDeriv",
      "MechanicalProjectJacobianMatrixVisitor"
    ],
    "context_usage": "This component is typically used in simulations where mechanical constraints need to be enforced, such as maintaining the shape of deformable objects or ensuring the correct positioning of rigid bodies."
  },
  "maths": {
    "maths": "### Mathematical and Physical Description of the ConstraintSolverImpl Component\n\n#### Overview:\nThe `ConstraintSolverImpl` class in the SOFA framework is designed to solve constraints within a mechanical system. It serves as an abstract base class for constraint solvers, providing fundamental functionality that must be extended by derived classes to handle specific types of constraints.\n\n#### Physical Context:\nThe context here involves mechanical systems where certain constraints need to be enforced, such as maintaining specific positions or orientations. These constraints are often formulated in terms of Lagrange multipliers and involve modifying the system's equations of motion accordingly.\n\n#### Mathematical Formulation:\n1. **Constraint Equations:*\n   - Constraints can be expressed mathematically using constraint functions $g(q)$, where $q$ represents the generalized coordinates (e.g., positions or orientations). \n   - For example, a position constraint might look like $g_i(q) = p_{i}^{\\text{actual}} - p_{i}^{\\text{desired}}$, where $p_i^{\\text{actual}}$ and $p_i^{\\text{desired}}$ are the actual and desired positions of point $i$, respectively.\n\n2. **Lagrange Multipliers:*\n   - The Lagrangian multipliers ($λ$) associated with constraints are used to enforce these conditions in the system dynamics.\n   - For a set of constraints $g(q)$, the augmented Lagrangian can be written as:\n     \n    $$ L_{\\text{aug}}(q,δλ) = T(q,δq) + V(q) + δλ^T g(q)$$\n\n   where $T$ is the kinetic energy and $V$ is the potential energy of the system.\n\n3. **Constraint Matrix:*\n   - The class includes a method to build the constraint matrix, which captures how constraints affect the overall dynamics.\n   - If $J(q)$ represents the Jacobian of the constraint functions (i.e., $∇_q g(q)$), and $A$ is the system's mass or stiffness matrix, then the projected compliance matrix can be expressed as:\n     \n    $$ W = J(q) A^{-1} J^T(q)$$\n\n   This matrix $W$ describes how constraints are projected onto the constraint space.\n\n4. **Solving for Constraints:*\n   - The `solveTimed` method in the `ConstraintProblem` class suggests that an iterative process is employed to solve for Lagrange multipliers, with parameters like tolerance (`tolerance`) and maximum iterations (`maxIt`).\n   - At each iteration, constraints are solved using equations such as $Wλ = d_{free}$, where $β$ represents the constraint values.\n\n5. **Constraint Correction:*\n   - The `clearConstraintCorrections` method indicates that corrections to the system's state due to constraints must be cleared periodically or under certain conditions (e.g., initialization).\n   - The corrected states are stored in vectors such as $d_{free}$ and $λ$.\n\n6. **Post-Processing:*\n   - Post-processing steps like `accumulateMatrixDeriv` suggest that after constraint enforcement, the system's matrix representation needs to be updated (e.g., applying Jacobian transpose mappings).\n   - Methods such as `postBuildSystem`, `postSolveSystem`, and `applyProjectiveConstraintOnConstraintMatrix` are part of this process.\n\n#### Summary:\nThe `ConstraintSolverImpl` class encapsulates the mathematical framework for enforcing constraints in mechanical systems using Lagrange multipliers, Jacobians, and iterative solution methods. It provides a robust foundation for derived classes to implement specific constraint-solving algorithms within the SOFA simulation environment."
  },
  "summary": {
    "abstract": "The `ConstraintSolverImpl` class serves as an abstract base for implementing constraint solvers within the Lagrangian solver context in SOFA, handling constraints using Lagrange multipliers and iterative methods.",
    "sheet": "# ConstraintSolverImpl\n\n## Overview\nThe `ConstraintSolverImpl` is an abstract class that provides a framework for implementing constraint solvers within the Lagrangian solver context of the SOFA simulation environment. It inherits from the `sofa::core::behavior::ConstraintSolver` and manages constraints through methods such as initialization, cleanup, and solving constraint problems.\n\n## Parameters and Data\nThe component does not expose any significant data fields directly but relies on a list of constraint corrections (`l_constraintCorrections`) that it handles. This list is managed via the `constraintCorrections` link.\n\n## Dependencies and Connections\nThis class typically requires or exchanges data with other components such as `BaseConstraintCorrection`, which are linked through the `constraintCorrections` multi-link field. It fits into the SOFA scene graph by providing a foundational structure for constraint solving, which is essential for enforcing specific conditions in mechanical systems.\n\n## Practical Notes\nDerived classes must implement methods like `getConstraintProblem` and `lockConstraintProblem`. The class includes several protected methods for building and post-processing constraint matrices, indicating that derived classes should handle these operations carefully to ensure numerical stability and correctness."
  }
}