Data Fields

Methods

{
  "name": "LagrangianConstraint",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/LagrangianConstraint.h",
  "doc": "Component computing constraints within a simulated body.\n This class defines the abstract API common to constraints using a given type\n of DOFs.\n A LagrangianConstraint computes constraints applied to one simulated body given its\n current position and velocity.",
  "inherits": [
    "BaseLagrangianConstraint",
    "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": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "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": "resV",
          "type": "linearalgebra::BaseVector *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "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": "c",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "cIndex",
          "type": "unsigned int &"
        },
        {
          "name": "x",
          "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": "getBaseConstraintIdentifiers",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getConstraintIdentifiers",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `LagrangianConstraint` is an abstract base class in the SOFA framework that defines constraints within a simulated body using specific types of degrees-of-freedom (DOFs). It computes and applies constraints to one simulated body based on its current position and velocity. The component interacts with other SOFA components such as mechanical states and solvers by defining interfaces for constraint violation computation, Jacobian matrix construction, and lambda storage.\n\nThe `LagrangianConstraint` class provides methods like `isActive`, `getConstraintViolation`, `buildConstraintMatrix`, and `storeLambda`, which are crucial for integrating constraints into the simulation. It inherits from `BaseLagrangianConstraint` and `SingleStateAccessor`, ensuring compatibility with various DOF types such as Rigid2Types, Rigid3Types, and Vec6Types.\n\nUsers can control when a constraint stops acting by setting the `endTime` field to a specific value; negative values indicate infinite constraints. This component is essential for implementing constrained dynamics within SOFA simulations.",
  "maths": "The `LagrangianConstraint` is an abstract base class in the SOFA framework that defines constraints within a simulated body using specific types of degrees-of-freedom (DOFs). The primary role of this component is to compute and apply constraints based on the current position and velocity of the system. These constraints are essential for enforcing physical consistency, such as maintaining contact between bodies or imposing kinematic restrictions.\n\n### Governing Equations and Operators\n\nThe LagrangianConstraint contributes to the global FEM pipeline by defining the constraint equations and their Jacobians. In a constrained dynamical system, the equations of motion can be extended with constraints using Lagrange multipliers. The overall system is given by:\n\n\begin{align*}\n  \\begin{bmatrix} M & J^T \\\\ J & 0 \\end{bmatrix}\\begin{bmatrix} \\ddot{x} \\\\ \\lambda \\end{bmatrix} &= \\begin{bmatrix} f_{ext} - f_{int}(x) \\\\ c(x, v) \\end{bmatrix},\n\\end{align*}\n\nwhere:\n- $M$ is the mass matrix,\n- $J$ is the Jacobian of the constraint equations with respect to displacements and velocities,\n- $\begin{bmatrix} x \\\\ v \\\\ \\\ndot{x} \\end{bmatrix}$ are the state variables (positions, velocities, and accelerations),\n- $f_{ext}$ are external forces,\n- $f_{int}(x)$ are internal forces due to material behavior,\n- $\begin{bmatrix} c(x,v) \\\\ \\lambda \\end{bmatrix}$ represent constraint violations and Lagrange multipliers.\n\n### Constitutive or Kinematic Laws Involved\n\nThe constraints can be holonomic (position-based) or non-holonomic (velocity-based). For example, a position-based constraint can be written as $c(x)=0$, where $x$ are the positions of points in the system. Similarly, velocity-based constraints can be expressed as $c(v)=0$, where $v$ are the velocities.\n\n### Role in the Global FEM Pipeline\n\nThe `LagrangianConstraint` participates in several stages of the global FEM pipeline:\n- **Assembly**: The constraint violations and Jacobians need to be assembled into the global system matrix and residual vector.\n- **Time Integration**: Constraints must be satisfied during time integration, ensuring that the solution respects physical constraints over time.\n- **Nonlinear Solve**: In nonlinear systems, the constraints contribute to the nonlinear residual $R(x)$ and the tangent stiffness matrix $J(x)$.\n\n### Numerical Methods or Discretization Choices\n\nThe `LagrangianConstraint` class does not define specific numerical methods for solving these equations. Instead, it provides an abstract interface that can be implemented by derived classes to handle specific types of constraints (e.g., position-based vs velocity-based).\n\n### Fitting into the Broader Variational/Lagrangian Mechanics Framework\n\nIn the context of variational mechanics and Lagrangian dynamics, the constraint equations are integrated into the action principle. The Euler-Lagrange equations derived from this principle include both internal forces and constraints via Lagrange multipliers. This ensures that the overall system remains physically consistent during simulation.\n\n### Summary\n\nThe `LagrangianConstraint` is a foundational component in SOFA for defining and enforcing constraints within a simulated body, ensuring physical consistency through variational formulations and implicit time integration.",
  "abstract": "The `LagrangianConstraint` defines the abstract API for computing and applying constraints within a simulated body based on position and velocity, ensuring physical consistency through Lagrange multipliers.",
  "sheet": "# LagrangianConstraint\n\n## Overview\n\nThe `LagrangianConstraint` is an abstract base class in the SOFA framework that defines the API for computing and applying constraints to one simulated body. It handles constraint violations, Jacobians, and Lagrange multipliers, ensuring physical consistency through variational formulations and implicit time integration.\n\n## Mathematical Model\n\nThe `LagrangianConstraint` contributes to the global FEM pipeline by defining the constraint equations and their Jacobians. In a constrained dynamical system, the equations of motion can be extended with constraints using Lagrange multipliers:\n\n\\begin{align*}\n  \\begin{bmatrix} M & J^T \\\\ J & 0 \\end{bmatrix}\\begin{bmatrix} \\ddot{x} \\\\ \\lambda \\end{bmatrix} &= \\begin{bmatrix} f_{ext} - f_{int}(x) \\\\ c(x, v) \\end{bmatrix},\n\\end{align*}\n\nwhere:\n- $M$ is the mass matrix,\n- $J$ is the Jacobian of the constraint equations with respect to displacements and velocities,\n- $\\begin{bmatrix} x \\\\ v \\\\ \\ddot{x} \\end{bmatrix}$ are the state variables (positions, velocities, and accelerations),\n- $f_{ext}$ are external forces,\n- $f_{int}(x)$ are internal forces due to material behavior,\n- $\\begin{bmatrix} c(x,v) \\\\ \\lambda \\end{bmatrix}$ represent constraint violations and Lagrange multipliers.\n\n## Parameters and Data\n\nThe `LagrangianConstraint` exposes the following significant parameter:\n\n- **endTime**: The constraint stops acting after the given value. Use a negative value for infinite constraints (type: Real).\n\n## Dependencies and Connections\n\nThe `LagrangianConstraint` typically requires or exchanges data with other SOFA components such as mechanical states, solvers, and mappings to integrate constraints into the simulation pipeline."
}