Methods

{
  "name": "MechanicalApplyProjectiveConstraint_ToMatrixVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalApplyProjectiveConstraint_ToMatrixVisitor.h",
  "doc": "Apply projective constraints of the whole scene */",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdProjectiveConstraintSet",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "c",
          "type": "core::behavior::BaseProjectiveConstraintSet *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` is a visitor class in the SOFA framework designed to apply projective constraints across the entire scene. It inherits from `MechanicalVisitor`, which facilitates mechanical operations during simulation. This visitor is specifically responsible for applying constraints stored in `BaseProjectiveConstraintSet` objects, modifying matrices as necessary to enforce these constraints.\n\nThrough its public methods `fwdMechanicalState` and `fwdProjectiveConstraintSet`, it interacts with nodes and mechanical states of the scene graph. The method `fwdProjectiveConstraintSet` applies projective constraints stored in a given `BaseProjectiveConstraintSet`. If a non-null matrix accessor is provided, the visitor modifies this matrix to enforce the constraints.\n\nPractical usage involves initializing an instance of this visitor with appropriate mechanical parameters and a matrix accessor. This visitor then iterates through the scene graph, applying projective constraints as needed during simulation steps.",
  "maths": "The `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` is designed to enforce projective constraints within the context of a finite element simulation. It plays a crucial role in ensuring that the mechanical system adheres to specific geometric or kinematic restrictions, which are critical for maintaining physical consistency and achieving desired behaviors.\n\n### Governing Equations and Operators\n\nIn the context of FEM simulations, constraints can be expressed using Lagrange multipliers to enforce holonomic (position) or non-holonomic (velocity) constraints. The system is often represented by a saddle-point problem:\n\n\\[\n\\begin{bmatrix}\nM & J^T \\\\\\ J & 0\n\\end{bmatrix}\n\\begin{bmatrix}\n\\ddot{x} \\\\ \\lambda\n\\end{bmatrix}\n=\n\\begin{bmatrix}\nf_{ext}-f_{int}(x) \\\\ c(x,\\dot{x})\n\\end{bmatrix}\n\\]\n\nwhere:\n- $M$ is the mass matrix,\n- $J$ is the Jacobian of constraints,\n- $\\lambda$ are Lagrange multipliers associated with constraints,\n- $f_{ext}$ and $f_{int}(x)$ represent external and internal forces, respectively,\n- $c(x,\\dot{x}) = 0$ represents the constraint equations.\n\n### Constitutive or Kinematic Laws Involved\n\nConstraints can be position-based (holonomic) or velocity-based (non-holonomic). For instance, a typical holonomic constraint might enforce a fixed distance between two points in the system:\n\\[\nh(x) = 0 \\quad \text{or} \\quad h(\\dot{x}) = 0\n\\]\n\nwhere $h$ is a function defining the constraint condition.\n\n### Role in the Global FEM Pipeline\n\nThe `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` operates during the assembly phase of the simulation pipeline. Specifically, it modifies matrices (e.g., mass matrix $M$, Jacobian $J$) to incorporate projective constraints into the system equations. This ensures that the resulting linear or nonlinear systems respect the specified constraints.\n\n### Numerical Methods and Discretization Choices\n\nThe visitor operates within an implicit time integration scheme, where it applies constraints in a consistent manner during each time step. The method `fwdProjectiveConstraintSet` is responsible for enforcing these constraints by modifying the matrix structures as required.\n\n### Fit into Variational / Lagrangian Mechanics Framework\n\nWithin the variational mechanics framework, projective constraints are incorporated using Lagrange multipliers to modify the system of equations derived from the weak form. The visitor ensures that these modifications are consistently applied across the entire scene graph, thereby preserving the overall physical consistency and stability of the simulation.\n\n### Summary\n\nThe `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` is a key component in enforcing constraints within the SOFA framework. It modifies matrices to ensure that projective constraints are respected during each step of the simulation, contributing to the accurate and physically consistent modeling of deformable systems.",
  "abstract": "The `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` applies projective constraints across the entire scene by modifying matrices to enforce these constraints during simulation steps.",
  "sheet": "# MechanicalApplyProjectiveConstraint_ToMatrixVisitor\n\n## Overview\nThe `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` is a visitor component in SOFA that enforces projective constraints throughout the scene. It modifies matrices, such as the mass matrix and Jacobian, to ensure these constraints are respected during each simulation step.\n\n## Mathematical Model\nIn the context of FEM simulations, constraints can be expressed using Lagrange multipliers to enforce holonomic (position) or non-holonomic (velocity) constraints. The system is often represented by a saddle-point problem:\n\n\begin{bmatrix}\nM & J^T \\\\ J & 0\n\ndot{x} \\lambda\n\ndot{x} - f_{int}(x) \\\\ c(x,\\dot{x})\n\ndot{x} = 0 \\quad \\text{or} \\quad h(\\dot{x}) = 0\n\nwhere:\n- $M$ is the mass matrix,\n- $J$ is the Jacobian of constraints,\n- $\\lambda$ are Lagrange multipliers associated with constraints,\n- $f_{ext}$ and $f_{int}(x)$ represent external and internal forces, respectively,\n- $c(x,\\dot{x}) = 0$ represents the constraint equations.\n\n## Practical Notes\nThe `MechanicalApplyProjectiveConstraint_ToMatrixVisitor` operates within an implicit time integration scheme. It ensures that constraints are consistently applied during each simulation step by modifying matrix structures as required. This visitor is crucial for maintaining physical consistency and stability in simulations involving deformable systems."
}