Mathematical and Physical Description of BaseProjectiveConstraintSet

Data Fields

Methods

{
  "name": "BaseProjectiveConstraintSet",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/BaseProjectiveConstraintSet.h",
  "doc": "Component computing projective constraints within a simulated body.\n This class define the abstract API common to all projective constraints.\n A BaseConstraint computes constraints applied to one or more simulated body\n given its current position and velocity.\n Constraints can be internal to a given body (attached to one MechanicalState,\n see the Constraint class), or link several bodies together (such as contacts,\n see the InteractionConstraint class).",
  "inherits": [],
  "templates": [],
  "data_fields": [
    {
      "name": "group",
      "type": "int"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "toBaseProjectiveConstraintSet",
      "return_type": "const BaseProjectiveConstraintSet *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getGroup",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setGroup",
      "return_type": "void",
      "params": [
        {
          "name": "g",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getModels",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponse",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "dxId",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectJacobianMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "cId",
          "type": "MultiMatrixDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectVelocity",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "vId",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectPosition",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "xId",
          "type": "MultiVecCoordId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponse",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "double **"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "const behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "",
          "type": "const behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "",
          "type": "unsigned int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::behavior::ZeroDirichletCondition *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "insertInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `BaseProjectiveConstraintSet` is an abstract base class in the SOFA framework responsible for computing projective constraints within simulated bodies. It provides a common interface for all types of projective constraints and defines methods to project various mechanical variables (position, velocity, acceleration) onto constrained spaces. Constraints can be internal to one body or involve multiple bodies.\n\nThe component interacts with other parts of the SOFA framework through its API:\n- The `projectResponse`, `projectJacobianMatrix`, `projectVelocity`, and `projectPosition` methods handle the projection of mechanical parameters into a constrained space, ensuring that constraints are correctly applied during simulation.\n- It uses `MechanicalParams` to provide context for these projections, allowing it to work with different types of physical properties.\n- The component can be added to or removed from a scene graph node (`BaseNode`) via the `insertInNode` and `removeInNode` methods.\n\nPractical usage involves setting up constraints within simulated bodies. The `group` data field specifies which group of constraints this set belongs to, enabling users to control solver configurations for specific constraint groups.",
  "maths": "# Mathematical and Physical Description of BaseProjectiveConstraintSet\n\n## Introduction\nThe `BaseProjectiveConstraintSet` class in the SOFA framework is designed to handle projective constraints within simulated bodies. Projective constraints are those that define a subspace of possible motions or configurations, often reducing the degrees of freedom (DOF) of the system. The constraints can be internal to a single body or involve interactions between multiple bodies.\n\n## Mathematical Formulation\nThe core functionality of `BaseProjectiveConstraintSet` is to project various mechanical quantities onto constrained subspaces. This projection is achieved through linear transformations that enforce the constraints on positions, velocities, and accelerations.\n\n### Projection Matrices\nLet's denote the projection matrix as \\(P\\), which projects a vector into the constrained subspace. The properties of \\(P\\) are such that:\n- \\(P^2 = P\\): This indicates that applying the projection twice does not change the result, i.e., it is idempotent.\n\n### Position Projection\nThe position \\(\boldsymbol{x}\\) of a point or body can be projected onto the constrained subspace as follows:\n$$\n\\boldsymbol{x}_{proj} = P \boldsymbol{x}\n$$\nThis ensures that \\(\boldsymbol{x}_{proj}\\) satisfies the constraints.\n\n### Velocity Projection\nSimilarly, for velocity \\(\boldsymbol{v}\\), the projection onto the constrained space is given by:\n$$\n\\boldsymbol{v}_{proj} = P \boldsymbol{v}\n$$\nThis ensures that any velocities are consistent with the imposed constraints.\n\n### Acceleration Projection (Response)\nThe response or acceleration \\(\boldsymbol{a}\\) can also be projected using a similar transformation:\n$$\n\\boldsymbol{a}_{proj} = P \boldsymbol{a}\n$$\nThis projection is crucial for enforcing constraints in dynamic simulations.\n\n### Jacobian Matrix Projection\nThe Lagrange multiplier method often involves projecting the Jacobian matrix \\(C\\) of constraint equations. The projected form is given by:\n$$\nP_{J} = P C P^T\n$$\nwhere \\(P_{J}\\) represents the projection onto the constrained space for the Jacobian matrix.\n\n### Compliance Matrix Projection\nIn certain cases, it might be necessary to project a compliance matrix (or its inverse, the stiffness matrix). The projection is given by:\n$$\nP_{comp} = P M^{-1} P^T\n$$\nwhere \\(M\\) is the mass matrix and \\(P_{comp}\\) ensures that the compliance matrix respects the constraints.\n\n## Constraint Groups\nThe `BaseProjectiveConstraintSet` supports grouping of constraints, which allows different sets of constraints to be handled by distinct solvers. This is controlled via a group identifier (`group`), enabling users to specify solver configurations for specific constraint groups.\n\n### Solver Integration\nWhen simulating systems with multiple constraints, solvers can handle each group separately. The `group` parameter helps in organizing and solving these subproblems efficiently.\n\n## Implementation Details\nIn the SOFA framework, the projection methods (`projectResponse`, `projectJacobianMatrix`, etc.) are abstract and must be implemented by derived classes to specify how specific constraints should be applied. This design allows for a flexible approach where different types of constraints can inherit from this base class and provide their own implementations.\n\n## Conclusion\nThe `BaseProjectiveConstraintSet` class provides the mathematical foundation for enforcing projective constraints in simulations within the SOFA framework. It ensures that all mechanical quantities are correctly projected onto constrained subspaces, thereby maintaining consistency with imposed physical constraints.",
  "abstract": "Computes projective constraints within simulated bodies by projecting mechanical variables onto constrained subspaces.",
  "sheet": "# BaseProjectiveConstraintSet\n\n## Overview\nThe `BaseProjectiveConstraintSet` is an abstract base class in the SOFA framework responsible for computing projective constraints within simulated bodies. It provides a common interface for all types of projective constraints and defines methods to project various mechanical variables (position, velocity, acceleration) onto constrained spaces.\n\n## Mathematical Model\nThe core functionality involves projecting mechanical quantities onto constrained subspaces using projection matrices. Let's denote the projection matrix as \\(P\\), which projects a vector into the constrained subspace. The properties of \\(P\\) are such that:\n- \\(P^2 = P\\): This indicates that applying the projection twice does not change the result, i.e., it is idempotent.\n\n### Position Projection\nThe position \\(\\boldsymbol{x}\\) can be projected onto the constrained subspace as follows:\n$$\n\\boldsymbol{x}_{proj} = P \\boldsymbol{x}\n$$\nThis ensures that \\(\\boldsymbol{x}_{proj}\\) satisfies the constraints.\n\n### Velocity Projection\nSimilarly, for velocity \\(\\boldsymbol{v}\\), the projection onto the constrained space is given by:\n$$\n\\boldsymbol{v}_{proj} = P \\boldsymbol{v}\n$$\nThis ensures that any velocities are consistent with the imposed constraints.\n\n### Acceleration Projection (Response)\nThe response or acceleration \\(\\boldsymbol{a}\\) can also be projected using a similar transformation:\n$$\n\\boldsymbol{a}_{proj} = P \\boldsymbol{a}\n$$\nThis projection is crucial for enforcing constraints in dynamic simulations.\n\n### Jacobian Matrix Projection\nThe Lagrange multiplier method often involves projecting the Jacobian matrix \\(C\\) of constraint equations. The projected form is given by:\n$$\nP_{J} = P C P^T\n$$\nwhere \\(P_{J}\\) represents the projection onto the constrained space for the Jacobian matrix.\n\n### Compliance Matrix Projection\nIn certain cases, it might be necessary to project a compliance matrix (or its inverse, the stiffness matrix). The projection is given by:\n$$\nP_{comp} = P M^{-1} P^T\n$$\nwhere \\(M\\) is the mass matrix and \\(P_{comp}\\) ensures that the compliance matrix respects the constraints.\n\n## Parameters and Data\n- **group**: Specifies which group of constraints this set belongs to. This allows users to control solver configurations for specific constraint groups.\n\n## Dependencies and Connections\nThe `BaseProjectiveConstraintSet` typically requires other SOFA components such as MechanicalStates, solvers, and mappings to function properly within the scene graph."
}