Data Fields

Methods

{
  "name": "PairInteractionProjectiveConstraintSet",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/PairInteractionProjectiveConstraintSet.h",
  "doc": "Component computing constraints between a pair of simulated body.\n This class define the abstract API common to interaction constraints\n between a pair of bodies using a given type of DOFs.",
  "inherits": [],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "endTime",
      "type": "SReal",
      "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": "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": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "dx1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx2",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectVelocity",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "v1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "v2",
          "type": "DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "projectPosition",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "x1",
          "type": "DataVecCoord &"
        },
        {
          "name": "x2",
          "type": "DataVecCoord &"
        }
      ],
      "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 `PairInteractionProjectiveConstraintSet` is a component in the SOFA framework designed to compute constraints between a pair of simulated bodies using a specific type of degrees of freedom (DOFs). This class defines an abstract API common for interaction constraints between two bodies.\n\n**Role and Purpose**: It enables the definition of projective constraints that act on pairs of mechanical states, allowing for the projection of response, velocity, and position to constrained spaces. The component can be instantiated with different data types such as `Rigid2Types`, `Rigid3Types`, or `Vec3Types`.\n\n**Interactions**: It interacts with other SOFA components through methods like `projectResponse`, `projectVelocity`, and `projectPosition`. These methods are pure virtual, meaning that concrete subclasses must implement these to define how specific constraints act on the simulation. The component also interacts with the MechanicalState of each body to retrieve and modify state vectors (position, velocity, response).\n\n**Data Fields**: It contains an attribute `endTime` which specifies when the constraint should stop acting. A negative value indicates that the constraint acts indefinitely.\n\n**Practical Usage Guidance**: This component is intended for developers creating specific interaction constraints between two bodies in a simulation scenario. Proper implementation of its methods ensures correct projection of mechanical states onto constrained spaces, facilitating the enforcement of predefined interactions such as contact or coupling forces.",
  "maths": "The `PairInteractionProjectiveConstraintSet` is a component in the SOFA framework that enforces projective constraints between two simulated bodies, using specific types of degrees of freedom (DOFs). This class defines an abstract API common to interaction constraints between pairs of bodies and provides methods for projecting various mechanical quantities into constrained spaces. The primary role of this component is to ensure that the interactions between these bodies are physically consistent with imposed constraints.\n\n### Governing Equations or Operators\n- **Projective Constraints**: These constraints enforce specific conditions on the positions, velocities, and responses (accelerations) of the two interacting bodies. The exact form of these constraints depends on the particular implementation by subclasses, but they generally involve linear or nonlinear equations that relate the DOFs of the two bodies.\n\n### Constitutive or Kinematic Laws Involved\n- **Constraints**: The constraints themselves are defined in terms of the generalized coordinates (positions), velocities, and accelerations of the interacting bodies. For example, a constraint may enforce that two points on different bodies remain at a fixed distance apart or that their relative velocity satisfies certain conditions.\n- **Projection Operations**: The projection operations (`projectResponse`, `projectVelocity`, `projectPosition`) ensure that any changes to these quantities are consistent with the constraints. This involves solving linear systems of equations to find the appropriate adjustments to the state vectors.\n\n### Role in Global FEM Pipeline\n1. **Assembly Phase**:\n   - The component contributes to enforcing constraints during assembly by projecting response, velocity, and position vectors into constrained spaces. This ensures that any external forces or internal responses are consistent with predefined constraints.\n2. **Nonlinear Resolution**:\n   - During the nonlinear solve phase, this component ensures that constraints are enforced at each iteration of the Newton-Raphson method or other iterative solver methods used to find the solution of the system of nonlinear equations.\n3. **Constraint Handling**:\n   - The `PairInteractionProjectiveConstraintSet` plays a critical role in handling constraints by projecting the response, velocity, and position vectors into constrained subspaces. This is achieved through virtual functions that must be implemented by subclasses to define specific constraint behaviors.\n\n### Numerical Methods or Discretization Choices\n- **Time Integration**: Although this component does not directly handle time integration, its methods are called during each time step to project mechanical state changes into the constrained space.\n- **Projection Operations**: The projection operations involve solving systems of linear equations. For example, projecting a response vector `dx` may involve solving for adjustments that satisfy constraint conditions.\n\n### Integration in Variational / Lagrangian Mechanics Framework\nThe `PairInteractionProjectiveConstraintSet` fits into the broader variational mechanics framework by ensuring that the constraints imposed on the system are consistent with the underlying physical laws governing the motion of deformable continua. By projecting mechanical state changes (positions, velocities, accelerations) into constrained spaces, this component ensures that the simulation remains physically realistic and numerically stable.\n\n### Summary\nThe `PairInteractionProjectiveConstraintSet` provides a mechanism for enforcing projective constraints between pairs of simulated bodies in SOFA simulations. It defines abstract methods for projecting response, velocity, and position vectors into constrained subspaces, ensuring that interactions are consistent with predefined constraints. The exact nature of these constraints is determined by subclasses implementing the virtual functions provided by this component.",
  "abstract": "The `PairInteractionProjectiveConstraintSet` defines projective constraints between pairs of simulated bodies in SOFA, ensuring interactions are consistent with predefined constraints through projection methods.",
  "sheet": "# PairInteractionProjectiveConstraintSet\n\n## Overview\nThe `PairInteractionProjectiveConstraintSet` is an abstract component that defines and enforces projective constraints between pairs of simulated bodies using specific degrees of freedom (DOFs). It provides a common API for interaction constraints, with pure virtual methods that must be implemented by concrete subclasses to define the behavior of these constraints.\n\n## Mathematical Model\nThe `PairInteractionProjectiveConstraintSet` enforces projective constraints on the mechanical states (positions, velocities, responses) of two interacting bodies. These constraints are defined in terms of generalized coordinates and involve linear or nonlinear equations that relate the DOFs of the two bodies. The projection operations (`projectResponse`, `projectVelocity`, `projectPosition`) ensure consistency with these constraints by solving systems of linear equations to adjust state vectors.\n\n## Parameters and Data\n- **endTime**: Type: SReal, XML Name: endTime, Default: Negative value (infinite constraint). Specifies the time after which the constraint stops acting. Use a negative value for infinite constraints.\n\n## Practical Notes\nThis component is intended for developers creating specific interaction constraints between two bodies in SOFA simulations. Proper implementation of its methods ensures correct projection of mechanical states onto constrained spaces, facilitating the enforcement of predefined interactions such as contact or coupling forces."
}