Data Fields

Methods

{
  "name": "StopperLagrangianConstraint",
  "namespace": "sofa::component::constraint::lagrangian::model",
  "module": "Sofa.Component.Constraint.Lagrangian.Model",
  "include": "sofa/component/constraint/lagrangian/model/StopperLagrangianConstraint.h",
  "doc": "Lagrangian-based constraint forcing a 1D DoF to be  inside a given range.",
  "inherits": [
    "LagrangianConstraint"
  ],
  "templates": [
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "d_index",
      "type": "int",
      "xmlname": "index",
      "help": "index of the stop constraint"
    },
    {
      "name": "d_min",
      "type": "SReal",
      "xmlname": "min",
      "help": "minimum value accepted"
    },
    {
      "name": "d_max",
      "type": "SReal",
      "xmlname": "max",
      "help": "maximum value accepted"
    }
  ],
  "links": [],
  "methods": [
    {
      "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"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildConstraintMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "c_d",
          "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 core::ConstraintParams *"
        },
        {
          "name": "resV",
          "type": "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": "",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "resTab",
          "type": "int &"
        },
        {
          "name": "offset",
          "type": "unsigned int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `StopperLagrangianConstraint` is a component in the SOFA framework designed to enforce that a one-dimensional degree of freedom (DoF) remains within specified bounds, defined by minimum and maximum values. This constraint inherits from the `LagrangianConstraint` class and is part of the `Sofa.Component.Constraint.Lagrangian.Model` module.\n\n**Role in SOFA Ecosystem:**\n- The component ensures that a specific DoF does not exceed predefined limits, making it useful for enforcing physical or simulation-specific constraints.\n- It can be integrated into larger simulations where bounding one-dimensional variables is crucial.\n\n**Interactions with Other Components:*\n- Through the `buildConstraintMatrix`, `getConstraintViolation`, and `getConstraintResolution` methods, this component interacts with other SOFA components to enforce constraint conditions and maintain simulation consistency.\n- The `init` method initializes the mechanical state by ensuring that initial positions comply with the specified bounds.\n\n**Practical Usage Guidance:**\n- Users can configure the constraint by setting the `index`, `min`, and `max` data fields. These define which DoF is constrained and what its allowable range of values is.\n- The `getConstraintIdentifiers` method provides identifiers for this specific type of constraint, aiding in identifying and managing constraints within complex simulations.",
  "maths": "The `StopperLagrangianConstraint` is designed to enforce that a one-dimensional degree of freedom (DoF) remains within specified bounds. This constraint operates within the variational mechanics framework and is implemented in the context of the Finite Element Method (FEM). Below, we provide a rigorous mathematical and physical description of this component.\n\n### Governing Equations and Operators\n\nThe `StopperLagrangianConstraint` enforces that the displacement $u$ at a specific node remains within the bounds defined by $d_{\\text{min}}$ and $d_{\\text{max}}$. This constraint is mathematically represented as:\n\n\begin{align*}\n  d_{\\text{min}} \\\n  u(i) \\\n  d_{\\text{max}},\n\tag{1}\n\nd_{\text{min}} \\leq u(i) \\leq d_{\text{max}}.\n\tag{2}\n\nd_{\text{min}} \\\n\nu(i) = x_i, &\n&\n&d_{\text{min}} \\leq x_i \\leq d_{\text{max}},\n\nd_{\text{min}} < u(i) < d_{\text{max}}.\n\tag{3}\n\n### Role in the Global FEM Pipeline\n\n- **Initialization (`init` Method):** The `init` method ensures that the initial displacement $x_i$ is within the specified bounds. If the initial displacement violates these constraints, it is adjusted to the nearest bound value.\n\n\begin{align*}\n  x_i &= \\text{min}(d_{\\text{max}}, \\text{max}(d_{\\text{min}}, x_i)).\n\tag{4}\n\n- **Build Constraint Matrix (`buildConstraintMatrix` Method):** The `buildConstraintMatrix` method constructs the constraint matrix $c_d$ for the Lagrangian formulation. For a one-dimensional DoF, this matrix is simple and only involves setting the appropriate entry to 1.\n\n\begin{align*}\n  c_{d}[i] &= \\delta_{ij}, \\\n  i &= d_{\\text{index}}.\n\tag{5}\n\n- **Get Constraint Violation (`getConstraintViolation` Method):** The `getConstraintViolation` method evaluates the constraint violation, which is the displacement at the constrained node $x_i$.\n\n\begin{align*}\n  \\delta(x) &= x_i.\n\tag{6}\n\n- **Get Constraint Resolution (`getConstraintResolution` Method):** This method handles the resolution of constraints by ensuring that any violation (i.e., when $x_i > d_{\\text{max}}$ or $x_i < d_{\\text{min}}$) is corrected through an appropriate Lagrange multiplier.\n\n### Numerical Methods and Discretization Choices\n\nThe component enforces the constraint during each time step by adjusting the displacements to satisfy Equation (2). The `StopperLagrangianConstraintResolution1Dof` class handles the numerical resolution of these constraints. It ensures that if a displacement exceeds the bounds, an appropriate Lagrange multiplier is applied to enforce the constraint.\n\n### Constitutive and Kinematic Laws\n\nThe component does not introduce any additional constitutive or kinematic laws beyond enforcing the positional bounds on a single DoF. The stress-strain relationship and other material properties are handled by other components in the SOFA framework, while this component ensures that the displacement remains within specified limits.\n\n### Variational / Lagrangian Mechanics Framework\n\nWithin the broader variational mechanics framework, this constraint is an example of a holonomic position constraint. It modifies the system's energy functional to include penalty terms for violations of the bounds. The overall system dynamics are governed by the constrained Lagrangian:\n\n\begin{align*}\n  \\mathcal{L}(q,\\dot q) &= T(q,\\dot q) - V(q), \\\n  Q_i &= \\lambda_i,\n\tag{7}\n\nwhere $Q_i$ are the generalized forces due to the Lagrange multipliers $\\lambda_i$, ensuring that the constraint is satisfied.\n",
  "abstract": "The `StopperLagrangianConstraint` enforces a one-dimensional degree of freedom to remain within specified minimum and maximum bounds. It operates by adjusting displacements during each time step to ensure compliance with these limits.",
  "sheet": "# StopperLagrangianConstraint\n\n## Overview\nThe `StopperLagrangianConstraint` is a Lagrangian-based constraint component that enforces a one-dimensional degree of freedom (DoF) to remain within specified bounds. It inherits from the `LagrangianConstraint` class and ensures that the displacement at a specific node does not exceed predefined limits.\n\n## Mathematical Model\nThe `StopperLagrangianConstraint` enforces that the displacement $u$ at a specific node remains within the bounds defined by $d_{\\text{min}}$ and $d_{\\text{max}}$. This constraint is mathematically represented as:\n\n\begin{align*}\n  d_{\\text{min}} \\leq u(i) \\leq d_{\\text{max}},\n  \\tag{1}\n\nd_{\\text{min}} \\\n  u(i) = x_i, & &d_{\\text{min}} \\leq x_i \\leq d_{\\text{max}},\n  \\tag{2}\n\nd_{\\text{min}} < u(i) < d_{\\text{max}}.\n  \\tag{3}\n\begin{align*}\n  x_i &= \\text{min}(d_{\\text{max}}, \\text{max}(d_{\\text{min}}, x_i)).\n  \\tag{4}\n\nc_d[i] &= \\delta_{ij}, & i &= d_{\\text{index}}.\n  \\tag{5}\n\n## Parameters and Data\nThe significant data fields exposed by the component are:\n- `d_index`: Index of the stop constraint (type: int).\n- `d_min`: Minimum value accepted (type: SReal).\n- `d_max`: Maximum value accepted (type: SReal)."
}