Data Fields

Methods

{
  "name": "SlidingLagrangianConstraint",
  "namespace": "sofa::component::constraint::lagrangian::model",
  "module": "Sofa.Component.Constraint.Lagrangian.Model",
  "include": "sofa/component/constraint/lagrangian/model/SlidingLagrangianConstraint.h",
  "doc": "Lagrangian-based partial fixation of DOFs of the model, along an axis.",
  "inherits": [
    "PairInteractionConstraint"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_m1",
      "type": "int",
      "xmlname": "sliding_point",
      "help": "index of the spliding point on the first model"
    },
    {
      "name": "d_m2a",
      "type": "int",
      "xmlname": "axis_1",
      "help": "index of one end of the sliding axis"
    },
    {
      "name": "d_m2b",
      "type": "int",
      "xmlname": "axis_2",
      "help": "index of the other end of the sliding axis"
    },
    {
      "name": "d_force",
      "type": "Deriv",
      "xmlname": "force",
      "help": "force (impulse) used to solve the constraint"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "getSlidingIdentifiers",
      "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": "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": "c1",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "c2",
          "type": "DataMatrixDeriv &"
        },
        {
          "name": "cIndex",
          "type": "unsigned int &"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "x2",
          "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": "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": 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"
    },
    {
      "name": "storeLambda",
      "return_type": "void",
      "params": [
        {
          "name": "cParams",
          "type": "const ConstraintParams *"
        },
        {
          "name": "res",
          "type": "sofa::core::MultiVecDerivId"
        },
        {
          "name": "lambda",
          "type": "const sofa::linearalgebra::BaseVector *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "A constraint that allows partial fixation of degrees-of-freedom (DOFs) for one point along an axis defined by two other points in the model.",
  "parameters": [
    {
      "name": "m1",
      "description": "Index of the point to be constrained.",
      "type": "unsigned int"
    },
    {
      "name": "m2a",
      "description": "Index of the first end-point defining the sliding axis.",
      "type": "unsigned int"
    },
    {
      "name": "m2b",
      "description": "Index of the second end-point defining the sliding axis.",
      "type": "unsigned int"
    }
  ],
  "returns": [
    {
      "name": "d_force",
      "description": "The computed force applied to enforce the constraint, stored as a vector in 'force' Data field."
    }
  ],
  "dependencies": [
    {
      "name": "core::behavior::BaseMechanicalState",
      "type": "required",
      "description": "The mechanical state of the model containing points m1, m2a and m2b."
    },
    {
      "name": "BilateralConstraintResolution",
      "type": "optional",
      "description": "Used for constraint resolution if points defining the axis are coincident."
    },
    {
      "name": "UnilateralConstraintResolution",
      "type": "optional",
      "description": "Used for constraint resolution when sliding is allowed between two distinct points on the axis."
    }
  ],
  "details": {
    "behavior": "If m2a and m2b define the same point, this component acts as a bilateral constraint fixing all DOFs of m1 to that point. If they are different points, it allows sliding motion along the line connecting them while enforcing unilateral constraints to prevent movement outside the segment [m2a,m2b].",
    "visualization": "When visualization is enabled, point m1 is drawn in yellow if constrained to a single point or green if allowed to slide between two distinct points. The axis defined by m2a and m2b is visualized as a blue line.",
    "compatibility": [
      {
        "type": "Vec3Types",
        "description": "Supports 3D vector space."
      },
      {
        "type": "Rigid3Types",
        "description": "Supports rigid body transformations in 3D space."
      }
    ]
  },
  "maths": "The `SlidingLagrangianConstraint` in the SOFA framework implements partial fixation of degrees-of-freedom (DOFs) for a specified point along an axis defined by two other points in the model. This constraint is part of the Lagrangian-based simulation approach and contributes to the global system through its role in handling constraints within the FEM pipeline. Here's a detailed mathematical and physical description of the component:\n\n### Governing Equations and Operators\nThe primary operator involved here is the *constraint matrix* \\( C \\), which enforces partial fixation of DOFs along an axis defined by two points (\\( A \\) and \\( B \\)) in the model. The constraint matrix \\( C \\) contributes to the global system's residual vector \\( R \\) and Jacobian \\( J \\). Specifically, it ensures that motion is constrained along predefined directions while allowing sliding along an axis.\n\n### Constitutive or Kinematic Laws Involved\n- **Projection onto Axis:** The constraint projects a point \\( P \\) onto the line defined by points \\( A \\) and \\( B \\).\n  - If the axis vector \\( \\mathbf{AB} = \\mathbf{B} - \\mathbf{A} \\) is zero (i.e., \\( A \\) and \\( B \\) coincide), a full DOF constraint is applied, effectively fixing point \\( P \\)'s position to that of \\( A \\).\n  - If the axis vector is non-zero, projection onto the line is computed using barycentric coordinates.\n\n- **Directional Constraints:** The constraint matrix \\( C \\) is assembled such that it enforces constraints along directions perpendicular to the sliding axis and also handles constraints along the axis itself (when point \\( P \\)'s position is not allowed to slide beyond points \\( A \\) or \\( B \\)).\n\n### Role in the Global FEM Pipeline\n1. **Assembly Phase:** The constraint matrix \\( C \\) is built in the `buildConstraintMatrix` method, which populates the constraint matrix with appropriate directional vectors that enforce partial fixation of DOFs along specified directions.\n2. **Time Integration:** During time integration, the constraint matrix and related forces contribute to the global system's residual vector and Jacobian matrix.\n3. **Nonlinear Solution:** The nonlinear solve step involves solving for Lagrange multipliers associated with this constraint using implicit methods.\n4. **Linear Solve:** Once the constraint Jacobian is assembled, it contributes to the linear solve phase of the Newton-Raphson iteration process.\n5. **Constraint Handling and Mapping:** This component specifically handles constraints by enforcing partial fixation along an axis, thus preserving mechanical consistency within the simulation framework.\n\n### Numerical Methods or Discretization Choices\n- The `buildConstraintMatrix` method computes the necessary directional vectors for projection onto the sliding axis and enforces constraints using Lagrange multipliers. The projection direction is computed as \\( \\mathbf{dirProj} = (\\mathbf{P} - \\mathbf{proj}) / ||\\mathbf{P} - \\mathbf{proj}|| \\), where \\( \\mathbf{proj} \\) is the point on line segment \\( AB \\) closest to \\( P \\).\n- The constraint matrix entries are populated based on the computed directional vectors and barycentric coordinates.\n\n### Variational / Lagrangian Mechanics Framework Integration\nThe `SlidingLagrangianConstraint` fits into the broader variational mechanics framework by ensuring that the system's kinetic energy is minimized while satisfying the imposed constraints. The constraint matrix \\( C \\) contributes to the global system of equations through Lagrange multipliers, effectively enforcing partial fixation along specified directions without violating mechanical invariants.\n\nIn summary, `SlidingLagrangianConstraint` is a crucial component for implementing partial DOF fixation along an axis within the SOFA framework. It enforces directional constraints while allowing controlled sliding motion, thus ensuring that the simulation remains physically consistent and numerically stable.",
  "abstract": "The `SlidingLagrangianConstraint` enforces partial fixation of degrees-of-freedom (DOFs) along an axis defined by two points in the model. It contributes to the global system's residual vector and Jacobian matrix during time integration and nonlinear solution phases.",
  "sheet": "# SlidingLagrangianConstraint\n\n## Overview\nThe `SlidingLagrangianConstraint` is a Lagrangian-based constraint that allows partial fixation of degrees-of-freedom (DOFs) for one point along an axis defined by two other points in the model. It inherits from `PairInteractionConstraint`. This component enforces directional constraints while allowing controlled sliding motion, ensuring physical consistency and numerical stability within the simulation framework.\n\n## Mathematical Model\nThe primary operator involved is the *constraint matrix* \\( C \\), which enforces partial fixation of DOFs along an axis defined by two points (\\( A \\) and \\( B \\)) in the model. The constraint matrix \\( C \\) contributes to the global system's residual vector \\( R \\) and Jacobian \\( J \\). Specifically, it ensures that motion is constrained along predefined directions while allowing sliding along an axis.\n\n- **Projection onto Axis:** The constraint projects a point \\( P \\) onto the line defined by points \\( A \\) and \\( B \\).\n  - If the axis vector \\( \\mathbf{AB} = \\mathbf{B} - \\mathbf{A} \\) is zero (i.e., \\( A \\) and \\( B \\) coincide), a full DOF constraint is applied, effectively fixing point \\( P \\)'s position to that of \\( A \\).\n  - If the axis vector is non-zero, projection onto the line is computed using barycentric coordinates.\n\n- **Directional Constraints:** The constraint matrix \\( C \\) enforces constraints along directions perpendicular to the sliding axis and also handles constraints along the axis itself (when point \\( P \\)'s position is not allowed to slide beyond points \\( A \\) or \\( B \\)).\n\n## Parameters and Data\nThe significant Data fields exposed by the component are:\n- `sliding_point`: index of the sliding point on the first model.\n- `axis_1`: index of one end of the sliding axis.\n- `axis_2`: index of the other end of the sliding axis.\n- `force`: force (impulse) used to solve the constraint.\n\n## Dependencies and Connections\nThis component typically requires or exchanges data with other components that define the model's geometry, such as points and forces. It fits into the scene graph by interacting with mechanical models and solvers to enforce constraints during time integration."
}