{
  "name": "BaseLagrangianConstraint",
  "main": {
    "name": "BaseLagrangianConstraint",
    "namespace": "sofa::core::behavior",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/behavior/BaseLagrangianConstraint.h",
    "doc": "Component computing constraints within a simulated body.\n This class defines the abstract API common to all 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 LagrangianConstraint class), or link several bodies together (such as contacts,\n see the InteractionConstraint class).",
    "inherits": [
      "BaseConstraintSet"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "toBaseLagrangianConstraint",
        "return_type": "const BaseLagrangianConstraint *",
        "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": "getConstraintInfo",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const ConstraintParams *"
          },
          {
            "name": "blocks",
            "type": "VecConstraintBlockInfo &"
          },
          {
            "name": "ids",
            "type": "VecPersistentID &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintInfo",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "blocks",
            "type": "VecConstraintBlockInfo &"
          },
          {
            "name": "ids",
            "type": "VecPersistentID &"
          },
          {
            "name": "positions",
            "type": "VecConstCoord &"
          },
          {
            "name": "directions",
            "type": "VecConstDeriv &"
          },
          {
            "name": "areas",
            "type": "VecConstArea &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintResolution",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const ConstraintParams *"
          },
          {
            "name": "resTab",
            "type": "int &"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getConstraintResolution",
        "return_type": "void",
        "params": [
          {
            "name": "resTab",
            "type": "int &"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getIdentifiers",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getBaseConstraintIdentifiers",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "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": true,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `BaseLagrangianConstraint` is an abstract class in the SOFA framework that serves as the foundation for all constraints applied to simulated bodies, whether internal or linking multiple bodies together (such as contacts). This component defines the API required for computing and handling these constraints. It inherits from `BaseConstraintSet`, providing a structure for managing constraint groups and their resolution within solvers.\n\n### Interactions with Other Components:\n- **Inheritance:** Inherits from `BaseConstraintSet` to manage constraint sets.\n- **Group Management:** The methods `getGroup()` and `setGroup(int g)` allow constraints to be categorized into different groups, which can then be solved by specific solvers based on these group IDs.\n- **Information Retrieval:** Abstract method `getConstraintInfo` provides information about the constraints, including positions and identifiers. This is crucial for solver algorithms that require detailed constraint data.\n- **Resolution Handling:** The methods `getConstraintResolution` manage the resolution of constraints within a simulation step, determining how constraints are solved given current state vectors and parameters.\n\n### Practical Usage Guidance:\n- Use this component as an abstract base class when implementing specific types of constraints (e.g., Lagrangian or interaction-based).\n- Implement the pure virtual methods `storeLambda` and `getBaseConstraintIdentifiers` to customize constraint resolution behavior for derived classes.\n- Utilize group management functions (`setGroup`, `getGroup`) to organize and control which solver handles specific constraint groups."
  },
  "maths": {
    "maths": "<maths_md_description>\n\n## Mathematical and Physical Description of `BaseLagrangianConstraint`\n\n### Overview\nThe `BaseLagrangianConstraint` class serves as an abstract base for all constraints in the SOFA framework. Constraints are critical components that enforce specific conditions on the simulated bodies, ensuring they behave according to physical laws or predefined rules. This class inherits from `BaseConstraintSet`, providing a structure and interface for managing constraint sets.\n\n### Key Concepts\n#### Constraint Groups\nConstraints within the SOFA framework can be categorized into different groups using the methods:\n- `getGroup()`: Retrieves the group ID of the constraint.\n- `setGroup(int g)`: Sets the group ID of the constraint.\nThese group IDs are essential for specifying which solver handles which constraints, allowing for efficient and modular solving strategies.\n\n#### Constraint Information Retrieval\nThe method `getConstraintInfo` provides detailed information about each constraint. This includes:\n- **Parent Pointer**: A pointer to the parent `BaseConstraint`, indicating the origin of the constraint.\n- **Persistent IDs**: Unique identifiers for constraints, which are useful in tracking and resolving constraints across multiple simulation steps.\n- **Positions**: 3D positions associated with the constraints (e.g., contact points).\n\n#### Constraint Resolution\nThe methods `getConstraintResolution` manage how constraints are resolved within a simulation step:\n- These methods handle the addition of constraint resolution algorithms to a vector (`resTab`).\n- The offset parameter is used to specify the position in this vector where new resolution algorithms should be added.\n\n### Mathematical Formulation\nConstraints can mathematically be represented as equations that need to hold true at all times. For example, if a constraint requires a distance between two points to remain constant (distance constraint), it can be written as:\n$$\n\\mathbf{d}(t) = \\| \\mathbf{p}_1(t) - \\mathbf{p}_2(t) \\| - d_0 = 0\n$$\nwhere $\\mathbf{p}_1$ and $\\mathbf{p}_2$ are the positions of two points, and $d_0$ is the desired distance.\n\n#### Constraint Jacobian\nThe constraint Jacobian matrix $J$ contains partial derivatives of these constraints with respect to the generalized coordinates (positions and velocities). For example, for a position-based constraint:\n$$\nJ = \\frac{\\partial g(\\mathbf{x})}{\\partial \\mathbf{x}}\n$$\nwhere $g(\\mathbf{x})$ is the vector of constraints.\n\n#### Constraint Impulse Calculation\nThe method `storeLambda` stores the constraint lambda (impulses), which are computed as:\n$$\n\\lambda = J^T \\cdot f_c\n$$\nwhere $f_c$ represents the forces required to satisfy the constraints. The matrix $J^T$ is the transpose of the Jacobian.\n\n### Conclusion\nThe `BaseLagrangianConstraint` class provides a foundational structure for implementing and managing various types of constraints within SOFA simulations. It ensures that these constraints can be effectively categorized, retrieved, and resolved to maintain the physical integrity and behavior of simulated bodies.</maths_md_description>"
  },
  "summary": {
    "abstract": "`BaseLagrangianConstraint` is an abstract class defining the API for all constraints in SOFA simulations, managing constraint groups and information retrieval.",
    "sheet": "# BaseLagrangianConstraint\n\n## Overview\nThe `BaseLagrangianConstraint` serves as an abstract base class for all constraints within the SOFA framework. It inherits from `BaseConstraintSet`, providing a structure for managing constraint sets and defining methods to handle group management, information retrieval, and resolution.\n\n## Parameters and Data\n- **Group Management**: The methods `getGroup()` and `setGroup(int g)` allow constraints to be categorized into different groups, which can then be solved by specific solvers based on these group IDs.\n- **Constraint Information Retrieval**: Abstract method `getConstraintInfo` provides detailed information about the constraints, including positions and identifiers. This is crucial for solver algorithms that require detailed constraint data.\n- **Resolution Handling**: The methods `getConstraintResolution` manage how constraints are resolved within a simulation step, determining how constraints are solved given current state vectors and parameters."
  }
}