Data Fields

Methods

{
  "name": "UniformLagrangianConstraint",
  "namespace": "sofa::component::constraint::lagrangian::model",
  "module": "Sofa.Component.Constraint.Lagrangian.Model",
  "include": "sofa/component/constraint/lagrangian/model/UniformLagrangianConstraint.h",
  "doc": "A constraint equation applied on all dofs.",
  "inherits": [
    "LagrangianConstraint"
  ],
  "templates": [
    "sofa::sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "d_iterative",
      "type": "bool",
      "xmlname": "iterative",
      "help": "Iterate over the bilateral constraints, otherwise a block factorisation is computed."
    },
    {
      "name": "d_constraintRestPos",
      "type": "bool",
      "xmlname": "constrainToRestPos",
      "help": "if false, constrains the pos to be zero / if true constraint the current position to stay at rest position"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "buildConstraintMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "c",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "cIndex",
          "type": "unsigned int &"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getConstraintViolation",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "resV",
          "type": "sofa::linearalgebra::BaseVector *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getConstraintResolution",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "crVector",
          "type": "int &"
        },
        {
          "name": "offset",
          "type": "unsigned int &"
        }
      ],
      "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"
    },
    {
      "name": "getStopperIdentifiers",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `UniformLagrangianConstraint` is a SOFA component designed to enforce uniform constraint equations on all degrees-of-freedom (DOFs) within a simulation model. This component inherits from the `LagrangianConstraint`, which signifies its role in defining and solving constraints within the Lagrangian framework of SOFA.\n\n### Role and Purpose:\nThe primary function of this constraint is to apply uniform constraints, meaning that it treats all DOFs equally by enforcing similar constraint conditions across them. The `UniformLagrangianConstraint` can be used in scenarios where global behavior needs to be controlled or maintained throughout the simulation domain.\n\n### Interactions with Other Components:\nThe component interacts with other SOFA components through its API, particularly via methods that are part of the Lagrangian constraint interface. It implements the `buildConstraintMatrix`, `getConstraintViolation`, and `getConstraintResolution` methods to contribute to the overall solution process of constrained dynamics problems in SOFA.\n\n- **`buildConstraintMatrix`**: This method constructs the Jacobian matrix for the constraints, which is essential for solving the constrained system of equations.\n- **`getConstraintViolation`**: Computes how much the current configuration violates the constraint conditions. It provides a way to measure and correct deviations from the desired constraint states.\n- **`getConstraintResolution`**: Determines how the constraints should be resolved. This includes setting up the appropriate resolution strategy (e.g., iterative or block factorization).\n\n### Practical Usage Guidance:\nThe component has two key data fields that control its behavior:\n- `d_iterative`: A boolean flag indicating whether to iterate over bilateral constraints or use a block factorization approach.\n- `d_constraintRestPos`: Another boolean field determining if the constraint should be applied relative to rest positions or absolute zero positions.\n\nThese fields allow users to customize how the uniform constraints are enforced, adapting them to different simulation scenarios and requirements.",
  "maths": "The `UniformLagrangianConstraint` in the SOFA framework enforces uniform constraints on all degrees-of-freedom (DOFs) within a simulation. It ensures that these constraints are applied consistently across all DOFs, which is particularly useful for maintaining global behavior or enforcing specific conditions throughout the entire model. This component inherits from `LagrangianConstraint`, indicating its role in defining and solving Lagrangian constraints within the simulation framework.\n\n### Governing Equations:\nThe primary mathematical operation of this constraint involves building a Jacobian matrix that represents the derivative of the constraint equations with respect to the DOFs. The constraint equations can be described as follows:\n\n- **Jacobian Matrix Construction (buildConstraintMatrix):**\n  - For each degree-of-freedom, a unit vector is added to the Jacobian matrix, ensuring uniformity across all DOFs.\n  \n    Let \\( x_i \\) represent the position of the i-th node and \\( u_i \\) its displacement. The Jacobian element for the i-th node can be represented as:\n\n    \\[ J_{ij} = \\begin{cases}\n      1 & \\text{if } j = i \\\\\n      0 & \\text{otherwise}\n    \\end{cases} \\]\n\n- **Constraint Violation (getConstraintViolation):**\n  - The violation of the constraint is computed based on the current position and velocity.\n  \n    If the `d_constraintRestPos` flag is set to true, the constraint is defined relative to rest positions:\n\n    \\[ g_i = x_i - x_{rest} + dt^{-1}(v_i + dt^{-1}(x_i - x_{rest})) \\]\n\n    If the `d_constraintRestPos` flag is false, the constraint is applied relative to zero positions:\n\n    \\[ g_i = x_i + dt^{-1} v_i \\]\n\n### Constitutive and Kinematic Laws Involved:\nThe component does not involve specific constitutive laws (like stress-strain relationships) or kinematic measures other than basic position and velocity. The primary role is to ensure that the DOFs adhere to a uniform constraint condition.\n\n### Role in the FEM Pipeline:\n- **Assembly:** This component contributes to assembling the global Jacobian matrix, which includes its own contributions for each degree-of-freedom.\n- **Time Integration:** During time integration, this constraint affects the system of equations by adding constraints that must be satisfied at each time step.\n- **Nonlinear Solve:** The `UniformLagrangianConstraint` participates in solving nonlinear systems of equations by enforcing its uniform constraints through the Jacobian matrix and constraint violation calculations.\n\n### Numerical Methods and Discretization Choices:\nThe component uses a straightforward approach to discretize the constraints, ensuring that each degree-of-freedom is treated uniformly. The `buildConstraintMatrix` method constructs the Jacobian matrix by setting appropriate unit vectors for each DOF. The `getConstraintResolution` method determines whether an iterative or block factorization strategy should be used based on the `d_iterative` flag.\n\n### Fit into Variational/Lagrangian Mechanics Framework:\nThe `UniformLagrangianConstraint` fits well within the variational and Lagrangian mechanics framework by providing a way to enforce global constraints that maintain consistency across all DOFs. It ensures that the system remains physically consistent under the applied constraints, contributing to the overall stability and accuracy of the simulation.\n\n### Conclusion:\nThe `UniformLagrangianConstraint` is an essential component for enforcing uniform constraints in SOFA simulations. Its straightforward implementation allows it to effectively contribute to maintaining global behavior across all degrees-of-freedom within a model.",
  "abstract": "The `UniformLagrangianConstraint` enforces uniform constraints across all degrees-of-freedom (DOFs) in a simulation model by constructing a Jacobian matrix and computing constraint violations based on rest positions or absolute zero positions.",
  "sheet": "# UniformLagrangianConstraint\n\n## Overview\n\nThe `UniformLagrangianConstraint` is a component that enforces uniform constraints across all degrees-of-freedom (DOFs) in a simulation model. It inherits from the `LagrangianConstraint` class and implements methods to build the Jacobian matrix, compute constraint violations, and determine resolution strategies.\n\n## Mathematical Model\n\nThe primary mathematical operation of this constraint involves building a Jacobian matrix that represents the derivative of the constraint equations with respect to the DOFs. The constraint equations can be described as follows:\n\n- **Jacobian Matrix Construction (buildConstraintMatrix):**\n  - For each degree-of-freedom, a unit vector is added to the Jacobian matrix, ensuring uniformity across all DOFs.\n    \n    Let \\( x_i \\) represent the position of the i-th node and \\( u_i \\) its displacement. The Jacobian element for the i-th node can be represented as:\n\n    \\[ J_{ij} = \\begin{cases}\n      1 & \\text{if } j = i \\\\\n      0 & \\text{otherwise}\n    \\end{cases} \\]\n\n- **Constraint Violation (getConstraintViolation):**\n  - The violation of the constraint is computed based on the current position and velocity.\n    \n    If the `d_constraintRestPos` flag is set to true, the constraint is defined relative to rest positions:\n\n    \\[ g_i = x_i - x_{rest} + dt^{-1}(v_i + dt^{-1}(x_i - x_{rest})) \\]\n\n    If the `d_constraintRestPos` flag is false, the constraint is applied relative to zero positions:\n\n    \\[ g_i = x_i + dt^{-1} v_i \\]\n\n## Parameters and Data\n\nThe significant data fields exposed by this component are as follows:\n\n- **`iterative`:** A boolean flag indicating whether to iterate over bilateral constraints or use a block factorization approach.\n  - Type: `bool`\n  - Default: Not specified\n\n- **`constrainToRestPos`:** Another boolean field determining if the constraint should be applied relative to rest positions or absolute zero positions.\n  - Type: `bool`\n  - Default: Not specified\n\n## Practical Notes\n\nThe component allows users to customize how uniform constraints are enforced through its parameters. The `iterative` flag controls whether an iterative approach is used for solving the constraints, while the `constrainToRestPos` flag determines if the constraint should be applied relative to rest positions or absolute zero positions."
}