Data Fields

Methods

{
  "name": "PairInteractionConstraint",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/PairInteractionConstraint.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": "getConstraintViolation",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "v",
          "type": "linearalgebra::BaseVector *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getConstraintViolation",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "v",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "v2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildConstraintMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "cId",
          "type": "MultiMatrixDerivId"
        },
        {
          "name": "cIndex",
          "type": "unsigned int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildConstraintMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "c1",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "c2",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "cIndex",
          "type": "unsigned int &"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "storeLambda",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "res",
          "type": "MultiVecDerivId"
        },
        {
          "name": "lambda",
          "type": "const sofa::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": "getInteractionIdentifiers",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getPairInteractionIdentifiers",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "storeLambda",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "res1",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "res2",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "j1",
          "type": "const Data<MatrixDeriv> &"
        },
        {
          "name": "j2",
          "type": "const Data<MatrixDeriv> &"
        },
        {
          "name": "lambda",
          "type": "const sofa::linearalgebra::BaseVector *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `PairInteractionConstraint` is an abstract component in the Sofa framework that defines an interface for computing constraints between pairs of simulated bodies with specific types of degrees-of-freedom (DOFs). It serves as a base class and template for creating interaction constraint components that operate on two sets of DOFs, such as those representing different parts of a deformable object or separate objects in contact.\n\n### Key Features:\n- **Abstract Class**: This component is abstract, meaning it cannot be instantiated directly. Instead, it must be subclassed by concrete implementations that provide the specific functionality for computing constraint violations and Jacobian matrices based on particular physical interactions or conditions.\n- **Template-Based Design**: It uses a template-based design allowing it to work with various types of DOFs such as vectors (Vec1Types, Vec2Types, Vec3Types) and rigid bodies (Rigid2Types, Rigid3Types).\n- **Interaction Identifiers**: Provides a method `getPairInteractionIdentifiers()` that can be overridden by derived classes to define unique identifiers for different interaction types.\n\n### Core Methods:\n- `isActive()`: A virtual function returning a boolean indicating whether the constraint is active or not. Inactive constraints do not contribute to the simulation.\n- `getConstraintViolation(...)`: Abstract methods which must be implemented in subclasses to compute the vector of constraint violations for each constraint equation based on provided position and velocity data.\n- `buildConstraintMatrix(...)`: Abstract methods that need to be overridden by derived classes to construct the Jacobian matrix, representing how constraints change with respect to changes in DOFs. This method takes into account positions (and optionally velocities) to compute the linearization of the constraints.\n- `storeLambda(...)`: A function for storing Lagrange multipliers after a constraint-solving process, ensuring that forces are applied correctly during the next simulation step.\n\n### Construction and Initialization:\n- The component includes a static method `canCreate()` for pre-construction validation, checking if the provided MechanicalStates match the expected DataTypes. This ensures proper setup before actual object creation using the `create(...)` static method.\n- Template instantiation is handled explicitly in source files to support various DOF types.\n\n### Inheritance and Accessors:\n- Inherits from `BaseInteractionConstraint` and `PairStateAccessor<DataTypes>` providing access to common constraint functionalities and state management for a pair of bodies.\n- Provides accessors (`getMechModel1()` and `getMechModel2()`) inherited from `PairStateAccessor`, facilitating easy retrieval of the MechanicalStates associated with each body in the interaction.\n\n### Usage:\nTo use this component, developers need to create concrete subclasses implementing the abstract methods for computing constraint violations and Jacobian matrices according to specific physical interactions or conditions. These subclasses can then be integrated into Sofa simulations to enforce constraints between pairs of bodies.",
  "summary": "The `PairInteractionConstraint` is an abstract template-based class in the Sofa framework used for defining interaction constraints between two simulated bodies with specified degrees-of-freedom (DOFs). It acts as a base class that must be subclassed, providing methods and structures necessary to compute constraint violations and Jacobian matrices.",
  "parameters": [],
  "returns": [],
  "maths": "The `PairInteractionConstraint` is an abstract component in the Sofa framework that provides a foundational interface for computing constraints between pairs of simulated bodies with specific types of degrees-of-freedom (DOFs). This component plays a crucial role in ensuring mechanical consistency and enforcing interactions within the FEM simulation pipeline. Below, we detail its mathematical and physical aspects.\n\n### Governing Equations and Operators:\n- **Constraint Violation**: The `PairInteractionConstraint` computes constraint violations which represent how much the current state of the system violates the defined constraints. This is done via abstract methods that must be implemented by derived classes. Mathematically, if we denote \\( c_i(x) = 0 \\) as a constraint equation where \\( x \\) represents the DOFs, then the violation vector \\( \textbf{v} \\) can be written as:\n    \n    \\[ v_i = c_i(x(t)) \\]\n\n- **Jacobian Matrix**: The Jacobian matrix \\( J \\), which captures how constraints change with respect to changes in DOFs, is computed by derived classes implementing the `buildConstraintMatrix` method. This matrix has entries:\n    \n    \\[ J_{ij} = \\frac{\\partial c_i}{\\partial x_j} \\]\n\n- **Lagrange Multipliers**: The Lagrange multipliers \\( \boldsymbol{\nu} \\) are stored using the `storeLambda` method. These multipliers represent the forces required to enforce constraints and ensure mechanical equilibrium.\n    \n### Constitutive or Kinematic Laws:\nThis component does not directly specify any constitutive or kinematic laws but serves as a framework for enforcing interaction constraints between pairs of bodies. The actual computation of constraint violations and Jacobian matrices must be defined by derived classes based on specific physical interactions such as contacts, attachments, or multi-resolution coupling.\n\n### Role in the Global FEM Pipeline:\n- **Assembly Phase**: The `PairInteractionConstraint` contributes to the assembly phase by computing and storing contributions from constraints. This involves computing constraint violations \\( \textbf{v} \\) and Jacobian matrices \\( J \\).\n    \n    - Constraint Violations: These are assembled into a global vector of constraints.\n    - Jacobian Matrices: These are used to form the global tangent stiffness matrix.\n\n- **Time Integration**: Constraints affect time integration by modifying the dynamic equations. The Lagrange multipliers ensure that the constraints are satisfied at each timestep.\n    \n### Numerical Methods and Discretization Choices:\nThe `PairInteractionConstraint` does not directly define numerical methods or discretization schemes but relies on derived classes to implement these based on specific interactions. Typically, this involves finite difference approximations for Jacobians in nonlinear problems.\n\n### Variational / Lagrangian Mechanics Framework Fit:\n- **Variational Principles**: The constraint equations and their enforcement through Lagrange multipliers fit naturally into the variational framework of FEM. Constraints are enforced by augmenting the system’s Lagrangian with penalty terms involving Lagrange multipliers.\n    \n    \\[ L = T - V + \\sum_i \\lambda_i c_i(x) \\]\n\n- **Lagrangian Mechanics**: The constraints can be viewed as modifications to the generalized coordinates, leading to a modified set of equations of motion that include constraint forces.\n\nIn summary, `PairInteractionConstraint` serves as an abstract interface for defining and enforcing interaction constraints between pairs of bodies within the FEM simulation framework. It does not specify concrete physics but instead provides a mechanism for derived classes to implement specific interactions.",
  "abstract": "`PairInteractionConstraint` is an abstract component defining the API for interaction constraints between pairs of simulated bodies with specific degrees-of-freedom (DOFs). It must be subclassed to provide concrete implementations of constraint violations and Jacobian matrices.",
  "sheet": "# PairInteractionConstraint\n\n## Overview\n`PairInteractionConstraint` is an abstract class in the Sofa framework that defines the interface for computing constraints between pairs of simulated bodies with specific types of degrees-of-freedom (DOFs). It serves as a base class for creating interaction constraint components and must be subclassed to provide concrete implementations.\n\n## Parameters and Data\n- **endTime**: The time at which the constraint stops acting. Use a negative value for infinite constraints.\n  - Type: `SReal`\n  - Default: Not specified\n\n## Dependencies and Connections\nThis component typically requires or exchanges data with other components that provide specific implementations of interaction constraints, such as positions and velocities of DOFs. It fits into the scene graph by being a base class for derived constraint components.\n\n## Practical Notes\nDevelopers must create concrete subclasses implementing abstract methods like `getConstraintViolation` and `buildConstraintMatrix`. These subclasses should handle specific physical interactions or conditions to enforce constraints between pairs of bodies."
}