BaseConstraintCorrection
- abstract
- The BaseConstraintCorrection component computes constraint forces within a simulated body using the compliance method, ensuring constraints are satisfied by adjusting the system's states.
- sheet
- # BaseConstraintCorrection ## Overview BaseConstraintCorrection is an abstract class that handles the computation of constraint forces within a simulated body using the compliance method. It ensures constraints are satisfied by adjusting the position, velocity, and additional motions in the simulation. ## Mathematical Model The compliance method relies on computing corrective forces based on the system's mechanical properties (mass matrix, stiffness) and constraint equations. The Jacobian matrix $J(q)$ linearizes constraints around the current configuration $q$. The compliance matrix $C$ is given by: \[ C = J(q) A^{-1} J(q)^T, \] where $A$ is the mechanical matrix (a function of mass and stiffness). Given a vector of Lagrange multipliers $λ$, the corrective motion $Δx$ is computed as: \[ Δx = A^{-1} J(q)^T λ. \] The method `computeMotionCorrectionFromLambda` computes this corrective motion from the constraint space force vector $λ$. The corrections are then applied using methods like `applyMotionCorrection`, which adjusts the position, velocity, and additional motions to ensure constraints are satisfied.
- component
-
{ "abstract_class": true, "description": "Component computing constraint forces within a simulated body using the compliance method.", "inherits_from": [ "objectmodel::BaseObject" ], "methods": [ { "accessibility": "public", "description": "Indicates whether the component is active within its context.", "name": "isActive", "return_type": "bool" }, { "accessibility": "public", "description": "Computes the compliance matrix projected in the constraint space and accumulates it into W.", "name": "addComplianceInConstraintSpace", "parameters": [ { "name": "cparams", "type": "const ConstraintParams*" }, { "name": "W", "type": "linearalgebra::BaseMatrix*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Fills the matrix m with the full Compliance Matrix.", "name": "getComplianceMatrix", "parameters": [ { "name": "m", "type": "linearalgebra::BaseMatrix*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Keeps track of the constraint solver by adding it.", "name": "addConstraintSolver", "parameters": [ { "name": "s", "type": "ConstraintSolver*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Removes reference to a previously added constraint solver.", "name": "removeConstraintSolver", "parameters": [ { "name": "s", "type": "ConstraintSolver*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Computes the corrective motion from the constraint space lambda.", "name": "computeMotionCorrectionFromLambda", "parameters": [ { "name": "cparams", "type": "const core::ConstraintParams*" }, { "name": "dx", "type": "core::MultiVecDerivId" }, { "name": "lambda", "type": "const linearalgebra::BaseVector*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Applies the motion correction based on a constraint resolution calculated force.", "name": "applyMotionCorrection", "parameters": [ { "name": "cparams", "type": "const ConstraintParams*" }, { "name": "x", "type": "MultiVecCoordId" }, { "name": "v", "type": "MultiVecDerivId" }, { "name": "dx", "type": "MultiVecDerivId" }, { "name": "correction", "type": "ConstMultiVecDerivId" } ], "return_type": "void" }, { "accessibility": "public", "description": "Applies the position correction based on a constraint resolution calculated force.", "name": "applyPositionCorrection", "parameters": [ { "name": "cparams", "type": "const ConstraintParams*" }, { "name": "x", "type": "MultiVecCoordId" }, { "name": "dx", "type": "MultiVecDerivId" }, { "name": "correction", "type": "ConstMultiVecDerivId" } ], "return_type": "void" }, { "accessibility": "public", "description": "Applies the velocity correction based on a constraint resolution calculated force.", "name": "applyVelocityCorrection", "parameters": [ { "name": "cparams", "type": "const ConstraintParams*" }, { "name": "v", "type": "MultiVecDerivId" }, { "name": "dv", "type": "MultiVecDerivId" }, { "name": "correction", "type": "ConstMultiVecDerivId" } ], "return_type": "void" }, { "accessibility": "public", "description": "Applies the predictive constraint force based on given parameters and lambda.", "name": "applyPredictiveConstraintForce", "parameters": [ { "name": "cparams", "type": "const ConstraintParams*" }, { "name": "f", "type": "MultiVecDerivId" }, { "name": "lambda", "type": "const linearalgebra::BaseVector*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Rebuilds the system using a mass and force factor.", "name": "rebuildSystem", "parameters": [ { "name": "massFactor", "type": "SReal" }, { "name": "forceFactor", "type": "SReal" } ], "return_type": "void" }, { "accessibility": "public", "description": "Computes the residual in Newton iterations due to constraint forces.", "name": "computeResidual", "parameters": [ { "name": "params", "type": "const core::ExecParams*" }, { "name": "lambda", "type": "linearalgebra::BaseVector*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Applies a contact force based on given lambda vector.", "name": "applyContactForce", "parameters": [ { "name": "f", "type": "const linearalgebra::BaseVector*" } ], "return_type": "void" }, { "accessibility": "public", "description": "Resets the contact forces to their default state.", "name": "resetContactForce", "parameters": [], "return_type": "void" } ], "name": "BaseConstraintCorrection", "namespace": "sofa::core::behavior" }
- maths
- # Mathematical and Physical Description of BaseConstraintCorrection Component ## Overview The `BaseConstraintCorrection` class in the SOFA (Simulation Open-Framework Architecture) framework is an abstract base class used to compute constraint forces within a simulated body using the compliance method. The goal is to ensure that constraints are satisfied by adjusting the motion of bodies involved in interactions, such as contacts or joints. This component plays a crucial role in the simulation of constrained dynamical systems. ## Constraint Satisfaction via Compliance Method The compliance method relies on computing corrective forces and motions based on the system's mechanical properties (mass matrix, stiffness) and constraint equations. The following sections detail the mathematical formulation used to achieve this. ### Constraints and Jacobian Matrix Constraints in a simulation are represented by a set of equations that relate the degrees of freedom (DOFs) of bodies within the simulation environment. Mathematically, these constraints can be expressed as: \[ J(q) Δq = 0, \] where \( q \) is the vector of DOFs, and \( J(q) \) is the constraint Jacobian matrix. The Jacobian matrix \( J(q) \) provides a linearization of constraints around the current configuration \( q \). ### Compliance Matrix The compliance method involves computing the compliance matrix, which represents how much the system can deform in response to external forces due to its mechanical properties. Mathematically, this is given by: \[ C = J(q) A^{-1} J(q)^T, \] where \( A \) is the mechanical matrix (a function of mass and stiffness), which relates applied forces to resulting motions in the absence of constraints. ### Correction from Constraint Forces The corrective motion or force derived from constraint resolution can be computed using the compliance matrix. Given a vector of Lagrange multipliers (constraint forces) \( λ \), the correction \( Δx \) is given by: \[ Δx = A^{-1} J(q)^T λ. \] The method `computeMotionCorrectionFromLambda` in the class computes this corrective motion from the constraint space force vector \( λ \). ### Application of Corrections The corrections computed are applied to adjust the position, velocity, and/or forces within the simulation to satisfy constraints. This involves applying these corrections to the system's states (position, velocity) in a way that minimizes deviations from the desired constraint conditions. For example, `applyMotionCorrection` applies corrective motion derived from solving the LCP (Linear Complementarity Problem), which results from formulating and solving constraint satisfaction problems. The method adjusts the position \( x \), velocity \( v \) and additional motions \( dx \) to ensure constraints are satisfied. ### Rebuilding the System The `rebuildSystem` method is used in experimental setups to investigate convergence issues by reconstructing the system with different mass and force factors. This can be useful for tuning the simulation's stability and performance under various conditions. ## Conclusion The `BaseConstraintCorrection` class provides a framework for ensuring that constraints are satisfied within SOFA simulations through compliance-based methods. The mathematical formulation involves linear algebra and systems of equations, which enable precise control over constraint satisfaction in complex dynamical systems.
{
"name": "BaseConstraintCorrection",
"main": {
"name": "BaseConstraintCorrection",
"namespace": "sofa::core::behavior",
"module": "Sofa.framework.Core",
"include": "sofa/core/behavior/BaseConstraintCorrection.h",
"doc": "Component computing constraint forces within a simulated body using the compliance method.",
"inherits": [
"BaseObject"
],
"templates": [],
"data_fields": [],
"links": [],
"methods": [
{
"name": "isActive",
"return_type": "bool",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addComplianceInConstraintSpace",
"return_type": "void",
"params": [
{
"name": "",
"type": "const ConstraintParams *"
},
{
"name": "W",
"type": "linearalgebra::BaseMatrix *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "getComplianceMatrix",
"return_type": "void",
"params": [
{
"name": "m",
"type": "linearalgebra::BaseMatrix *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "getComplianceWithConstraintMerge",
"return_type": "void",
"params": [
{
"name": "",
"type": "linearalgebra::BaseMatrix *"
},
{
"name": "",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addConstraintSolver",
"return_type": "void",
"params": [
{
"name": "s",
"type": "ConstraintSolver *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "removeConstraintSolver",
"return_type": "void",
"params": [
{
"name": "s",
"type": "ConstraintSolver *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"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": true,
"is_static": false,
"access": "public"
},
{
"name": "applyMotionCorrection",
"return_type": "void",
"params": [
{
"name": "cparams",
"type": "const ConstraintParams *"
},
{
"name": "x",
"type": "MultiVecCoordId"
},
{
"name": "v",
"type": "MultiVecDerivId"
},
{
"name": "dx",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "applyPositionCorrection",
"return_type": "void",
"params": [
{
"name": "cparams",
"type": "const ConstraintParams *"
},
{
"name": "x",
"type": "MultiVecCoordId"
},
{
"name": "dx",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "applyVelocityCorrection",
"return_type": "void",
"params": [
{
"name": "cparams",
"type": "const ConstraintParams *"
},
{
"name": "v",
"type": "MultiVecDerivId"
},
{
"name": "dv",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "applyPredictiveConstraintForce",
"return_type": "void",
"params": [
{
"name": "cparams",
"type": "const ConstraintParams *"
},
{
"name": "f",
"type": "MultiVecDerivId"
},
{
"name": "lambda",
"type": "const linearalgebra::BaseVector *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "rebuildSystem",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal"
},
{
"name": "",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "computeResidual",
"return_type": "void",
"params": [
{
"name": "",
"type": "const core::ExecParams *"
},
{
"name": "",
"type": "linearalgebra::BaseVector *"
}
],
"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": true,
"is_static": false,
"access": "public"
},
{
"name": "resetContactForce",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "hasConstraintNumber",
"return_type": "bool",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resetForUnbuiltResolution",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal *"
},
{
"name": "",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addConstraintDisplacement",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal *"
},
{
"name": "",
"type": "int"
},
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setConstraintDForce",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal *"
},
{
"name": "",
"type": "int"
},
{
"name": "",
"type": "int"
},
{
"name": "",
"type": "bool"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getBlockDiagonalCompliance",
"return_type": "void",
"params": [
{
"name": "",
"type": "linearalgebra::BaseMatrix *"
},
{
"name": "",
"type": "int"
},
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "correctionFactor",
"return_type": "SReal",
"params": [
{
"name": "solver",
"type": "const sofa::core::behavior::OdeSolver *"
},
{
"name": "constraintOrder",
"type": "const ConstraintOrder &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": true,
"access": "protected"
}
]
},
"desc": {
"component": {
"name": "BaseConstraintCorrection",
"description": "Component computing constraint forces within a simulated body using the compliance method.",
"namespace": "sofa::core::behavior",
"inherits_from": [
"objectmodel::BaseObject"
],
"abstract_class": true,
"methods": [
{
"name": "isActive",
"return_type": "bool",
"description": "Indicates whether the component is active within its context.",
"accessibility": "public"
},
{
"name": "addComplianceInConstraintSpace",
"parameters": [
{
"name": "cparams",
"type": "const ConstraintParams*"
},
{
"name": "W",
"type": "linearalgebra::BaseMatrix*"
}
],
"return_type": "void",
"description": "Computes the compliance matrix projected in the constraint space and accumulates it into W.",
"accessibility": "public"
},
{
"name": "getComplianceMatrix",
"parameters": [
{
"name": "m",
"type": "linearalgebra::BaseMatrix*"
}
],
"return_type": "void",
"description": "Fills the matrix m with the full Compliance Matrix.",
"accessibility": "public"
},
{
"name": "addConstraintSolver",
"parameters": [
{
"name": "s",
"type": "ConstraintSolver*"
}
],
"return_type": "void",
"description": "Keeps track of the constraint solver by adding it.",
"accessibility": "public"
},
{
"name": "removeConstraintSolver",
"parameters": [
{
"name": "s",
"type": "ConstraintSolver*"
}
],
"return_type": "void",
"description": "Removes reference to a previously added constraint solver.",
"accessibility": "public"
},
{
"name": "computeMotionCorrectionFromLambda",
"parameters": [
{
"name": "cparams",
"type": "const core::ConstraintParams*"
},
{
"name": "dx",
"type": "core::MultiVecDerivId"
},
{
"name": "lambda",
"type": "const linearalgebra::BaseVector*"
}
],
"return_type": "void",
"description": "Computes the corrective motion from the constraint space lambda.",
"accessibility": "public"
},
{
"name": "applyMotionCorrection",
"parameters": [
{
"name": "cparams",
"type": "const ConstraintParams*"
},
{
"name": "x",
"type": "MultiVecCoordId"
},
{
"name": "v",
"type": "MultiVecDerivId"
},
{
"name": "dx",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"return_type": "void",
"description": "Applies the motion correction based on a constraint resolution calculated force.",
"accessibility": "public"
},
{
"name": "applyPositionCorrection",
"parameters": [
{
"name": "cparams",
"type": "const ConstraintParams*"
},
{
"name": "x",
"type": "MultiVecCoordId"
},
{
"name": "dx",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"return_type": "void",
"description": "Applies the position correction based on a constraint resolution calculated force.",
"accessibility": "public"
},
{
"name": "applyVelocityCorrection",
"parameters": [
{
"name": "cparams",
"type": "const ConstraintParams*"
},
{
"name": "v",
"type": "MultiVecDerivId"
},
{
"name": "dv",
"type": "MultiVecDerivId"
},
{
"name": "correction",
"type": "ConstMultiVecDerivId"
}
],
"return_type": "void",
"description": "Applies the velocity correction based on a constraint resolution calculated force.",
"accessibility": "public"
},
{
"name": "applyPredictiveConstraintForce",
"parameters": [
{
"name": "cparams",
"type": "const ConstraintParams*"
},
{
"name": "f",
"type": "MultiVecDerivId"
},
{
"name": "lambda",
"type": "const linearalgebra::BaseVector*"
}
],
"return_type": "void",
"description": "Applies the predictive constraint force based on given parameters and lambda.",
"accessibility": "public"
},
{
"name": "rebuildSystem",
"parameters": [
{
"name": "massFactor",
"type": "SReal"
},
{
"name": "forceFactor",
"type": "SReal"
}
],
"return_type": "void",
"description": "Rebuilds the system using a mass and force factor.",
"accessibility": "public"
},
{
"name": "computeResidual",
"parameters": [
{
"name": "params",
"type": "const core::ExecParams*"
},
{
"name": "lambda",
"type": "linearalgebra::BaseVector*"
}
],
"return_type": "void",
"description": "Computes the residual in Newton iterations due to constraint forces.",
"accessibility": "public"
},
{
"name": "applyContactForce",
"parameters": [
{
"name": "f",
"type": "const linearalgebra::BaseVector*"
}
],
"return_type": "void",
"description": "Applies a contact force based on given lambda vector.",
"accessibility": "public"
},
{
"name": "resetContactForce",
"parameters": [],
"return_type": "void",
"description": "Resets the contact forces to their default state.",
"accessibility": "public"
}
]
}
},
"maths": {
"maths": "# Mathematical and Physical Description of BaseConstraintCorrection Component\n\n## Overview\nThe `BaseConstraintCorrection` class in the SOFA (Simulation Open-Framework Architecture) framework is an abstract base class used to compute constraint forces within a simulated body using the compliance method. The goal is to ensure that constraints are satisfied by adjusting the motion of bodies involved in interactions, such as contacts or joints. This component plays a crucial role in the simulation of constrained dynamical systems.\n\n## Constraint Satisfaction via Compliance Method\nThe compliance method relies on computing corrective forces and motions based on the system's mechanical properties (mass matrix, stiffness) and constraint equations. The following sections detail the mathematical formulation used to achieve this.\n\n### Constraints and Jacobian Matrix\nConstraints in a simulation are represented by a set of equations that relate the degrees of freedom (DOFs) of bodies within the simulation environment. Mathematically, these constraints can be expressed as:\n\\[\nJ(q) Δq = 0,\n\\]\nwhere \\( q \\) is the vector of DOFs, and \\( J(q) \\) is the constraint Jacobian matrix. The Jacobian matrix \\( J(q) \\) provides a linearization of constraints around the current configuration \\( q \\).\n\n### Compliance Matrix\nThe compliance method involves computing the compliance matrix, which represents how much the system can deform in response to external forces due to its mechanical properties. Mathematically, this is given by:\n\\[\nC = J(q) A^{-1} J(q)^T,\n\\]\nwhere \\( A \\) is the mechanical matrix (a function of mass and stiffness), which relates applied forces to resulting motions in the absence of constraints.\n\n### Correction from Constraint Forces\nThe corrective motion or force derived from constraint resolution can be computed using the compliance matrix. Given a vector of Lagrange multipliers (constraint forces) \\( λ \\), the correction \\( Δx \\) is given by:\n\\[\nΔx = A^{-1} J(q)^T λ.\n\\]\nThe method `computeMotionCorrectionFromLambda` in the class computes this corrective motion from the constraint space force vector \\( λ \\).\n\n### Application of Corrections\nThe corrections computed are applied to adjust the position, velocity, and/or forces within the simulation to satisfy constraints. This involves applying these corrections to the system's states (position, velocity) in a way that minimizes deviations from the desired constraint conditions.\n\nFor example, `applyMotionCorrection` applies corrective motion derived from solving the LCP (Linear Complementarity Problem), which results from formulating and solving constraint satisfaction problems. The method adjusts the position \\( x \\), velocity \\( v \\) and additional motions \\( dx \\) to ensure constraints are satisfied.\n\n### Rebuilding the System\nThe `rebuildSystem` method is used in experimental setups to investigate convergence issues by reconstructing the system with different mass and force factors. This can be useful for tuning the simulation's stability and performance under various conditions.\n\n## Conclusion\nThe `BaseConstraintCorrection` class provides a framework for ensuring that constraints are satisfied within SOFA simulations through compliance-based methods. The mathematical formulation involves linear algebra and systems of equations, which enable precise control over constraint satisfaction in complex dynamical systems."
},
"summary": {
"abstract": "The BaseConstraintCorrection component computes constraint forces within a simulated body using the compliance method, ensuring constraints are satisfied by adjusting the system's states.",
"sheet": "# BaseConstraintCorrection\n\n## Overview\nBaseConstraintCorrection is an abstract class that handles the computation of constraint forces within a simulated body using the compliance method. It ensures constraints are satisfied by adjusting the position, velocity, and additional motions in the simulation.\n\n## Mathematical Model\nThe compliance method relies on computing corrective forces based on the system's mechanical properties (mass matrix, stiffness) and constraint equations. The Jacobian matrix $J(q)$ linearizes constraints around the current configuration $q$. The compliance matrix $C$ is given by:\n\\[\nC = J(q) A^{-1} J(q)^T,\n\\]\nwhere $A$ is the mechanical matrix (a function of mass and stiffness). Given a vector of Lagrange multipliers $λ$, the corrective motion $Δx$ is computed as:\n\\[\nΔx = A^{-1} J(q)^T λ.\n\\]\nThe method `computeMotionCorrectionFromLambda` computes this corrective motion from the constraint space force vector $λ$. The corrections are then applied using methods like `applyMotionCorrection`, which adjusts the position, velocity, and additional motions to ensure constraints are satisfied."
}
}