Mathematical and Physical Description of ConstraintCorrection Component in the SOFA Framework

Links

Methods

{
  "name": "ConstraintCorrection",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/ConstraintCorrection.h",
  "doc": "Component computing constraint forces within a simulated body using the compliance method.",
  "inherits": [
    "BaseConstraintCorrection",
    "SingleStateAccessor"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [
    {
      "name": "l_constraintsolvers",
      "target": "ConstraintSolver",
      "kind": "multi"
    }
  ],
  "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": "computeMotionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "dx",
          "type": "core::MultiVecDerivId"
        },
        {
          "name": "f",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": "applyMotionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "x",
          "type": "Data<VecCoord> &"
        },
        {
          "name": "v",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "dx",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "correction",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": "applyPositionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "x",
          "type": "Data<VecCoord> &"
        },
        {
          "name": "dx",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "correction",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": "applyVelocityCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "v",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "dv",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "correction",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "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": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "setMState",
      "return_type": "void",
      "params": [
        {
          "name": "_mstate",
          "type": "MechanicalState<DataTypes> *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `ConstraintCorrection` component in the SOFA framework is responsible for computing constraint forces within a simulated body using the compliance method. It inherits from `BaseConstraintCorrection` and `SingleStateAccessor`, indicating its role in handling mechanical state interactions and enforcing constraints.\n\nThis component interacts with other components through links to `ConstraintSolver`. The primary methods include initialization (`init`) and cleanup, adding and removing constraint solvers (`addConstraintSolver`, `removeConstraintSolver`), and applying various corrections (motion, position, velocity) based on the computed motion correction from lambda forces. Methods such as `computeMotionCorrectionFromLambda`, `applyMotionCorrection`, `applyPositionCorrection`, and `applyVelocityCorrection` are key to enforcing constraints by adjusting positions and velocities.\n\nThe component also includes virtual methods for extending functionality with custom constraint corrections, making it flexible for different use cases within the simulation framework. Practical usage involves setting up mechanical states and linking appropriate constraint solvers.",
  "maths": "# Mathematical and Physical Description of ConstraintCorrection Component in the SOFA Framework\n\n## Overview\nThe `ConstraintCorrection` component in the SOFA (Simulation OpenFramework Architecture) framework is a crucial element for enforcing constraints within a simulated body. It uses the compliance method to compute constraint forces and enforce them on the mechanical state of the simulation.\n\n## Constraints and Compliance Method\nIn physics-based simulations, especially those involving contact dynamics or other complex interactions, enforcing constraints accurately is essential. The **compliance method** involves modifying the motion of bodies in response to constraints by computing corrective forces or displacements.\n\n### Key Concepts:\n- **Constraint Jacobian (J)**: A matrix that represents how each constraint equation depends on the positions and velocities of the bodies involved.\n- **Dynamic Matrix (A)**: Typically, it is a combination of mass matrix (M) and stiffness matrix (K), often modified by time step size (h).\n\n## Mathematical Formulations\n\n### Motion Correction from Lambda Forces\nThe `ConstraintCorrection` component computes the motion correction (`dx`) based on the constraint space force vector (`lambda`). The mathematical formulation can be described as follows:\n\n1. **Jacobian Matrix** (`J`): Represents how each constraint depends on the positions/velocities of bodies.\n2. **Lambda Forces**: These are forces in the constraint space, calculated during the LCP (Linear Complementarity Problem) resolution phase to enforce constraints.\n3. **Dynamic Matrix** (`A`): The matrix representing the overall dynamics of the system (e.g., `M - h^2 * K`).\n\nThe motion correction is computed as:\n\\[ dx = A^{-1} \\times J^T \\times lambda \\]\nwhere:\n- `J^T` denotes the transpose of the Jacobian matrix.\n- `A^-1` represents the inverse of the dynamic matrix.\n\n### Applying Corrections\nThe component provides methods to apply corrections based on the computed forces or displacements. These include motion correction, position correction, and velocity correction.\n\n#### Motion Correction (`applyMotionCorrection`)\nThis method applies corrective motions to positions and velocities:\n\\[ x_{new} = x + dx \\]\n\\[ v_{new} = v + dv \\]\nwhere `dx` and `dv` are the computed corrections.\n\n#### Position Correction (`applyPositionCorrection`)\nThe position correction is applied directly to the positions of the bodies:\n\\[ x_{new} = x + dx \\]\n\n#### Velocity Correction (`applyVelocityCorrection`)\nThe velocity correction modifies the velocities based on the constraint forces:\n\\[ v_{new} = v + dv \\]\n\n### Predictive Constraint Force Application (`applyPredictiveConstraintForce`)\nThis method applies predictive constraint forces to ensure stability and accuracy in the simulation. It involves converting constraint space forces to motion space forces and accumulating them into the overall force vector.\n\n#### Conversion of Forces\nThe conversion from constraint space to motion space is done using:\n\\[ f_{motion} = J^T \\times lambda \\]\nwhere `f_motion` represents the resulting motion space force vector.\n\n### Initialization (`init`) and Cleanup (`cleanup`)\nThe `init` method ensures that the component is properly set up with the necessary mechanical state, while the `cleanup` method handles resource release and cleanup procedures.\n\n## Interaction with Constraint Solvers\nThe `ConstraintCorrection` interacts with `ConstraintSolver` components via links. The methods `addConstraintSolver` and `removeConstraintSolver` allow dynamic management of these interactions.\n\n### Extensibility\nThe component includes virtual methods for custom constraint corrections, providing flexibility to extend functionality for specific use cases within the simulation framework.\n\n## Practical Usage\nSetting up mechanical states and linking appropriate constraint solvers is essential. The `canCreate` method ensures that a compatible mechanical state exists before initializing the component.\n",
  "abstract": "The `ConstraintCorrection` component computes constraint forces within a simulated body using the compliance method, enforcing constraints by modifying positions and velocities.",
  "sheet": "# ConstraintCorrection\n\n## Overview\nThe `ConstraintCorrection` component in the SOFA framework is responsible for computing constraint forces within a simulated body using the compliance method. It interacts with other components through links to `ConstraintSolver`, enabling enforcement of constraints on mechanical states.\n\n## Mathematical Model\nIn physics-based simulations, enforcing constraints accurately is essential. The **compliance method** involves modifying the motion of bodies in response to constraints by computing corrective forces or displacements.\n\n### Key Concepts:\n- **Jacobian Matrix (J)**: Represents how each constraint depends on the positions/velocities of bodies.\n- **Dynamic Matrix (A)**: Typically, it is a combination of mass matrix (M) and stiffness matrix (K), often modified by time step size (h).\n\n### Motion Correction from Lambda Forces\nThe motion correction (`dx`) based on the constraint space force vector (`lambda`) can be described as follows:\n1. **Jacobian Matrix** (`J`): Represents how each constraint depends on the positions/velocities of bodies.\n2. **Lambda Forces**: These are forces in the constraint space, calculated during the LCP (Linear Complementarity Problem) resolution phase to enforce constraints.\n3. **Dynamic Matrix** (`A`): The matrix representing the overall dynamics of the system (e.g., `M - h^2 * K`).\nThe motion correction is computed as:\n\\[ dx = A^{-1} \\times J^T \\times lambda \\]\nwhere:\n- `J^T` denotes the transpose of the Jacobian matrix.\n- `A^-1` represents the inverse of the dynamic matrix.\n\n### Applying Corrections\nThe component provides methods to apply corrections based on the computed forces or displacements. These include motion correction, position correction, and velocity correction.\n#### Motion Correction (`applyMotionCorrection`)\nThe method applies corrective motions to positions and velocities:\n\\[ x_{new} = x + dx \\]\n\\[ v_{new} = v + dv \\]\nwhere `dx` and `dv` are the computed corrections.\n\n#### Position Correction (`applyPositionCorrection`)\nThe position correction is applied directly to the positions of the bodies:\n\\[ x_{new} = x + dx \\]\n\n#### Velocity Correction (`applyVelocityCorrection`)\nThe velocity correction modifies the velocities based on the constraint forces:\n\\[ v_{new} = v + dv \\]\n\n### Predictive Constraint Force Application (`applyPredictiveConstraintForce`)\nThis method applies predictive constraint forces to ensure stability and accuracy in the simulation. It involves converting constraint space forces to motion space forces and accumulating them into the overall force vector.\n#### Conversion of Forces\nThe conversion from constraint space to motion space is done using:\n\\[ f_{motion} = J^T \\times lambda \\]\nwhere `f_motion` represents the resulting motion space force vector.\n\n## Parameters and Data\n- **l_constraintsolvers**: A multi-link to `ConstraintSolver` components, indicating which solvers are associated with this constraint correction component.\n\n## Dependencies and Connections\nThe `ConstraintCorrection` interacts with `ConstraintSolver` components via links. The methods `addConstraintSolver` and `removeConstraintSolver` allow dynamic management of these interactions."
}