{
  "name": "GenericConstraintCorrection",
  "main": {
    "name": "GenericConstraintCorrection",
    "namespace": "sofa::component::constraint::lagrangian::correction",
    "module": "Sofa.Component.Constraint.Lagrangian.Correction",
    "include": "sofa/component/constraint/lagrangian/correction/GenericConstraintCorrection.h",
    "doc": "Component computing constraint forces within a simulated body using the compliance method.",
    "inherits": [
      "BaseConstraintCorrection"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_complianceFactor",
        "type": "SReal",
        "xmlname": "complianceFactor",
        "help": "Factor applied to the position factor and velocity factor used to calculate compliance matrix"
      },
      {
        "name": "d_regularizationTerm",
        "type": "SReal",
        "xmlname": "regularizationTerm",
        "help": "Add regularization factor times the identity matrix to the compliance W when solving constraints"
      }
    ],
    "links": [
      {
        "name": "l_linearSolver",
        "target": "LinearSolver",
        "kind": "single",
        "xmlname": "linearSolver",
        "help": "Link towards the linear solver used to compute the compliance matrix, requiring the inverse of the linear system matrix"
      },
      {
        "name": "l_ODESolver",
        "target": "OdeSolver",
        "kind": "single",
        "xmlname": "ODESolver",
        "help": "Link towards the ODE solver used to recover the integration factors"
      }
    ],
    "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": "addConstraintSolver",
        "return_type": "void",
        "params": [
          {
            "name": "s",
            "type": "core::behavior::ConstraintSolver *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeConstraintSolver",
        "return_type": "void",
        "params": [
          {
            "name": "s",
            "type": "core::behavior::ConstraintSolver *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeMotionCorrectionFromLambda",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "dx",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "lambda",
            "type": "const linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addComplianceInConstraintSpace",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "W",
            "type": "linearalgebra::BaseMatrix *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getComplianceMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "linearalgebra::BaseMatrix *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyMotionCorrection",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "x",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "dx",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyPositionCorrection",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "x",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "dx",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyVelocityCorrection",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "dv",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyPredictiveConstraintForce",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "f",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "lambda",
            "type": "const linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "rebuildSystem",
        "return_type": "void",
        "params": [
          {
            "name": "massFactor",
            "type": "SReal"
          },
          {
            "name": "forceFactor",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyContactForce",
        "return_type": "void",
        "params": [
          {
            "name": "f",
            "type": "const linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resetContactForce",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeResidual",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const core::ExecParams *"
          },
          {
            "name": "lambda",
            "type": "linearalgebra::BaseVector *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "applyMotionCorrection",
        "return_type": "void",
        "params": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "xId",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "vId",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "dxId",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          },
          {
            "name": "positionFactor",
            "type": "SReal"
          },
          {
            "name": "velocityFactor",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "GenericConstraintCorrection",
    "author": "SOFA Team and external contributors",
    "class_hierarchy": [
      "sofa.core.behavior.BaseConstraintCorrection",
      "GenericConstraintCorrection"
    ],
    "description": "The GenericConstraintCorrection component is part of the SOFA (Simulation Open-Framework Architecture) framework. It computes constraint forces within a simulated body using the compliance method.",
    "parameters": [
      {
        "name": "l_linearSolver",
        "type": "SingleLink",
        "description": "Link to the linear solver used for computing the compliance matrix, which requires the inverse of the linear system matrix."
      },
      {
        "name": "l_ODESolver",
        "type": "SingleLink",
        "description": "Link to the ODE (Ordinary Differential Equation) solver to recover integration factors needed for motion correction."
      },
      {
        "name": "d_complianceFactor",
        "type": "Data<SReal>",
        "description": "A factor applied to position and velocity factors when calculating the compliance matrix."
      },
      {
        "name": "d_regularizationTerm",
        "type": "Data<SReal>",
        "description": "Regularization term added to the identity matrix (Id) when solving constraints. This helps in improving numerical stability during constraint resolution."
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "description": "Initializes the component and performs any necessary setup operations before simulation starts."
      },
      {
        "name": "cleanup",
        "return_type": "void",
        "description": "Performs cleanup operations, such as releasing resources, after the simulation has ended or when the component is being removed."
      },
      {
        "name": "addComplianceInConstraintSpace",
        "return_type": "void",
        "parameters": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "W",
            "type": "linearalgebra::BaseMatrix*"
          }
        ],
        "description": "Adds the compliance matrix to a given matrix W, which is computed as J A^-1 J^T where J represents the Jacobian of constraints and A^-1 is the inverse of the system matrix."
      },
      {
        "name": "applyMotionCorrection",
        "return_type": "void",
        "parameters": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "x",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "dx",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "description": "Applies motion correction to positions and velocities based on the provided correction vector, scaled by factors derived from the ODE solver."
      },
      {
        "name": "applyPositionCorrection",
        "return_type": "void",
        "parameters": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "x",
            "type": "core::MultiVecCoordId"
          },
          {
            "name": "dx",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "description": "Applies a correction to the position vector based on the provided correction vector, scaled by a factor from the ODE solver."
      },
      {
        "name": "applyVelocityCorrection",
        "return_type": "void",
        "parameters": [
          {
            "name": "cparams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "dv",
            "type": "core::MultiVecDerivId"
          },
          {
            "name": "correction",
            "type": "core::ConstMultiVecDerivId"
          }
        ],
        "description": "Applies a correction to the velocity vector based on the provided correction vector, scaled by a factor from the ODE solver."
      },
      {
        "name": "applyContactForce",
        "return_type": "void",
        "parameters": [
          {
            "name": "f",
            "type": "const linearalgebra::BaseVector *"
          }
        ],
        "description": "Applies contact forces computed as J^T * f, where f is the external force vector."
      }
    ]
  },
  "maths": {
    "maths": "The **GenericConstraintCorrection** component in the SOFA framework computes constraint forces within a simulated body using the compliance method. This approach is often used to ensure that constraints, such as fixed positions or contacts between bodies, are satisfied by applying corrective forces derived from a compliance matrix. The mathematical and physical description of this component involves several key aspects:\n\n### Compliance Matrix\nThe core of the compliance method lies in the computation of the **compliance matrix** $W$, which is defined as:\n\\[ W = J A^{-1} J^T \\]\nwhere $J$ is the Jacobian matrix that captures how constraints change with respect to the system's degrees of freedom, and $A^{-1}$ represents the inverse of the mass or stiffness matrix associated with the system. The compliance matrix essentially describes the \"softness\" of the constraints by quantifying the reaction forces required to enforce these constraints.\n\n### Constraint Forces Calculation\nThe constraint correction method involves calculating corrective displacements $dx$ which are then used to update positions and velocities. This is done in two main steps:\n1. **Force Calculation**: The constraint forces $f$ are computed as the product of the Jacobian transpose and the Lagrange multipliers (or dual variables) $\\lambda$, i.e.,\n   \\[ f = J^T \\lambda \\]\n2. **Displacement Update**: The corrective displacements are obtained by solving a linear system involving the inverse mass matrix or stiffness matrix:\n   \\[ dx = A^{-1} f \\]\n\n### Corrective Motion Application\nOnce $dx$ is calculated, it is used to update the position and velocity of the simulated body as follows:\n\\[\n    x_{new} = x_{free} + dx \n    v_{new} = v_{free} + dv \n\\]\nwhere $x_{free}$ and $v_{free}$ are the free-motion positions and velocities, respectively. The correction factors ($positionFactor$ and $velocityFactor$) provided by the ODE solver modulate these updates to ensure stability and physical consistency.\n\n### Contact Forces Application\nIn the context of contact forces, this component applies corrective forces based on external forces $f$. Specifically, the function `applyContactForce` modifies positions and velocities as follows:\n\\[\n    dx = A^{-1} (J^T f) \n    x_{new} = x_{free} + positionFactor \\times dx \n    v_{new} = v_{free} + velocityFactor \\times dx \n\\]\nThe compliance matrix $W$ ensures that the corrective displacements account for both positional and velocity constraints.\n\n### Integration with ODE Solvers\nThe integration factors ($positionFactor$ and $velocityFactor$) are derived from the chosen ODE solver (e.g., Euler, Runge-Kutta). These factors scale the corrections to ensure physical consistency over time steps:\n\\[\n    correctionFactor = \\begin{cases} \n        positionFactor & \\text{if } cparams->constOrder() == POSITION \\\\ \n        velocityFactor & \\text{otherwise}\n    \\end{cases}\n\\]\nThe `applyMotionCorrection` function applies these corrections, ensuring that the system evolves according to both constraint forces and free motion.\n\n### Regularization Term\nTo avoid singularities or numerical instability in the inversion of $A$, a regularization term can be added to the compliance matrix:\n\\[\n    W = J A^{-1} J^T + \\text{regularizationTerm} \\times I \n\\]\nwhere $I$ is the identity matrix, and `d_regularizationTerm` is a user-defined parameter that controls this regularization.\n\n### Summary\nThe GenericConstraintCorrection component effectively ensures physical constraints are satisfied by applying corrective forces computed through the compliance method. This involves calculating the compliance matrix, solving for corrective displacements, and updating positions and velocities in accordance with both free motion and constraint enforcement."
  },
  "summary": {
    "abstract": "The GenericConstraintCorrection component computes constraint forces within a simulated body using the compliance method, ensuring that constraints are satisfied by applying corrective forces derived from a compliance matrix.",
    "sheet": "# GenericConstraintCorrection\n\n## Overview\nThe GenericConstraintCorrection component is part of the SOFA framework and handles the computation of constraint forces within a simulated body. It uses the compliance method to ensure that physical constraints (such as fixed positions or contacts) are satisfied by applying corrective forces.\n\n## Mathematical Model\nThe core of the compliance method lies in the computation of the **compliance matrix** $W$, defined as:\n\\[ W = J A^{-1} J^T \\]\nwhere $J$ is the Jacobian matrix capturing how constraints change with respect to the system's degrees of freedom, and $A^{-1}$ represents the inverse of the mass or stiffness matrix associated with the system.\n\nThe constraint forces $f$ are computed as:\n\\[ f = J^T \\lambda \\]\nwhere $\\lambda$ are the Lagrange multipliers. The corrective displacements $dx$ are obtained by solving a linear system involving the inverse mass matrix or stiffness matrix:\n\\[ dx = A^{-1} f \\]\n\nOnce $dx$ is calculated, it is used to update positions and velocities as follows:\n\\[\n    x_{new} = x_{free} + dx \\\\\n    v_{new} = v_{free} + dv \n\\]\nwhere $x_{free}$ and $v_{free}$ are the free-motion positions and velocities, respectively. The correction factors ($positionFactor$ and $velocityFactor$) provided by the ODE solver modulate these updates to ensure stability and physical consistency.\n\n## Parameters and Data\nThe significant Data fields exposed by this component include:\n- **complianceFactor**: Factor applied to the position factor and velocity factor used to calculate compliance matrix (type: `SReal`).\n- **regularizationTerm**: Add regularization factor times the identity matrix to the compliance $W$ when solving constraints (type: `SReal`).\n\n## Dependencies and Connections\nThis component typically requires links towards a linear solver (`LinearSolver`) for computing the compliance matrix and an ODE solver (`OdeSolver`) for recovering integration factors.\n"
  }
}