Data Fields

Methods

{
  "name": "ProjectiveConstraintSet",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/ProjectiveConstraintSet.h",
  "doc": "Component computing constraints within a simulated body.\n This class define the abstract API common to constraints using a given type\n of DOFs.\n A ProjectiveConstraintSet computes constraints applied to one simulated body given its\n current position and velocity.",
  "inherits": [
    "BaseProjectiveConstraintSet",
    "SingleStateAccessor"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec6Types"
  ],
  "data_fields": [
    {
      "name": "endTime",
      "type": "Real",
      "xmlname": "endTime",
      "help": "The constraint stops acting after the given value.\\nUse a negative value for infinite constraints"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "isActive",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "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": false,
      "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": false,
      "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": false,
      "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": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectResponse",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "dx",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectVelocity",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "v",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectPosition",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "x",
          "type": "DataVecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectJacobianMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "cData",
          "type": "DataMatrixDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "const sofa::core::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 sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "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"
    }
  ],
  "description": "The `ProjectiveConstraintSet` is a core behavior component in the SOFA framework, responsible for computing and applying constraints within a simulated body based on its current position and velocity. This class defines an abstract API common to various types of constraints that use different degrees-of-freedom (DOFs) such as rigid or vector types.\n\nThe `ProjectiveConstraintSet` inherits from `BaseProjectiveConstraintSet` and `SingleStateAccessor`, indicating it deals with mechanical states for a single simulated body. It provides methods to project the response, Jacobian matrix, velocity, and position to constrained spaces, ensuring that these properties adhere to defined constraints.\n\nThe component interacts with other SOFA components through its API, particularly via the `MechanicalParams` object which encapsulates parameters related to mechanical computations. The `projectResponse`, `projectJacobianMatrix`, `projectVelocity`, and `projectPosition` methods are used to project specific data types (acceleration, Jacobian matrix, velocity, position) according to constraints defined by the component.\n\nThe `ProjectiveConstraintSet` class also includes a `Data<Real>` field named `endTime` that specifies when the constraint should cease its effect. If `endTime` is negative, it signifies an infinite duration of the constraint's action.\n\nPractical usage involves ensuring that the mechanical state within the context matches the specified data types and that constraints are defined properly to interact with other simulation components effectively.",
  "maths": "<maths_description>\n\nThe `ProjectiveConstraintSet` is a core behavior component in the SOFA framework responsible for computing and applying constraints within a simulated body based on its current position and velocity. This class defines an abstract API common to various types of constraints that use different degrees-of-freedom (DOFs) such as rigid or vector types.\n\n### Governing Equations and Operators\n\nThe `ProjectiveConstraintSet` component deals with the projection of mechanical states onto constrained spaces. Specifically, it operates on the following quantities:\n- **Response/Force Projection** (\textbf{projectResponse})\n- **Jacobian Matrix Projection** (\textbf{projectJacobianMatrix})\n- **Velocity Projection** (\textbf{projectVelocity})\n- **Position Projection** (\textbf{projectPosition})\n\nMathematically, these projections can be expressed as:\n\n#### Response/Force Projection\nGiven a mechanical response vector \\\\( \\mathbf{F} \\\\), the projection onto constrained space can be written as:\n\\[\n    \\mathbf{P}_{c} \\mathbf{F}\n\\]\nwhere \\\\( \\mathbf{P}_{c} \\\\) is a projection operator that enforces the constraints.\n\n#### Jacobian Matrix Projection\nFor the Jacobian matrix \\\\( \\mathbf{J} \\\\), which relates the constraint forces to the Lagrange multipliers, the projection is given by:\n\\[\n    \\mathbf{P}_{c} \\mathbf{J}\n\\]\nThe matrix \\\\( \\mathbf{P}_{c} \\\\) ensures that the Jacobian respects the constraints.\n\n#### Velocity Projection\nGiven a velocity vector \\\\( \\mathbf{v} \\\\), the projection onto constrained space is:\n\\[\n    \\mathbf{P}_{c} \\mathbf{v}\n\\]\nThe operator \\\\( \\mathbf{P}_{c} \\\\) ensures that velocities are consistent with the constraints.\n\n#### Position Projection\nFor a position vector \\\\( \\mathbf{x} \\\\), the projection is:\n\\[\n    \\mathbf{P}_{c} \\mathbf{x}\n\\]\nThe operator \\\\( \\mathbf{P}_{c} \\\\) ensures that positions adhere to the constraints.\n\n### Constitutive or Kinematic Laws Involved\nThe `ProjectiveConstraintSet` component does not define specific constitutive laws. Instead, it relies on constraints defined elsewhere in the simulation pipeline. These constraints can involve various kinematic relations and constraint forces:\n- **Holonomic Constraints**: Position-based constraints that restrict certain degrees of freedom.\n- **Non-Holonomic Constraints**: Velocity-based constraints that impose restrictions on velocity vectors.\n\n### Role in the Global FEM Pipeline\nThe `ProjectiveConstraintSet` plays a critical role in enforcing constraints during the simulation. It fits into the following stages of the global FEM pipeline:\n1. **Assembly Phase**: The component contributes to the assembly of constraint matrices and forces within the global system.\n2. **Time Integration**: Constraints are enforced at each time step through projection operations, ensuring that the simulated body’s motion adheres to defined constraints during implicit time integration schemes such as Backward Euler.\n3. **Nonlinear Solution**: During nonlinear solves (e.g., Newton-Raphson iteration), the component ensures that solutions satisfy the imposed constraints by projecting residuals and Jacobians appropriately.\n4. **Linear Solve**: Constraints influence the linear system solution, potentially altering the stiffness matrix and residual vector to respect physical boundaries and restrictions.\n\n### Numerical Methods or Discretization Choices\nThe `ProjectiveConstraintSet` employs projection operators \\\\( \\mathbf{P}_{c} \\\\) that are typically derived from Lagrange multiplier methods. These projections can involve techniques such as:\n- **Lagrange Multiplier Methods**: Introducing additional variables (multipliers) to enforce constraints.\n- **Projection Matrices**: Constructing projection matrices based on constraint Jacobians to ensure consistency with the defined constraints during each simulation step.\n\n### Fit into Variational / Lagrangian Mechanics Framework\nThe `ProjectiveConstraintSet` fits within the broader variational framework by ensuring that the mechanical system’s state (position, velocity) remains consistent with physical constraints. This is achieved through the use of projection operators that modify the system state to respect the specified constraint equations. The component ensures that the simulation maintains physical consistency and stability by enforcing these constraints throughout the time integration process.\n\n</maths_description>",
  "abstract": "`ProjectiveConstraintSet` computes constraints within a simulated body based on its current position and velocity, projecting response, Jacobian matrix, velocity, and position onto constrained spaces.",
  "sheet": "\n# ProjectiveConstraintSet\n\n## Overview\nThe `ProjectiveConstraintSet` is an abstract base class in the SOFA framework responsible for computing and applying constraints within a simulated body based on its current position and velocity. It provides methods to project response, Jacobian matrix, velocity, and position onto constrained spaces.\n\n## Parameters and Data\n- **endTime**: Specifies when the constraint should cease acting. Use a negative value for infinite constraints (type: `Real`).\n\n## Mathematical Model\nThe `ProjectiveConstraintSet` component deals with the projection of mechanical states onto constrained spaces using projection operators \\(\\mathbf{P}_{c}\\). The projections are defined as follows:\n- **Response/Force Projection**: Given a mechanical response vector \\(\\mathbf{F}\\), the projection is written as:\n  \n  \\[ \\mathbf{P}_{c} \\mathbf{F} \\]\n\n- **Jacobian Matrix Projection**: For the Jacobian matrix \\(\\mathbf{J}\\), which relates constraint forces to Lagrange multipliers, the projection is given by:\n  \n  \\[ \\mathbf{P}_{c} \\mathbf{J} \\]\n\n- **Velocity Projection**: Given a velocity vector \\(\\mathbf{v}\\), the projection onto constrained space is:\n  \n  \\[ \\mathbf{P}_{c} \\mathbf{v} \\]\n\n- **Position Projection**: For a position vector \\(\\mathbf{x}\\), the projection is:\n  \n  \\[ \\mathbf{P}_{c} \\mathbf{x} \\]\n\n## Dependencies and Connections\nThe `ProjectiveConstraintSet` typically requires other SOFA components that define constraints, such as constraint forces or kinematic relations. It interacts with these components through the scene graph to enforce constraints during simulation."
}