Methods

{
  "name": "MechanicalGetConstraintViolationVisitor",
  "namespace": "sofa::component::constraint::lagrangian::solver",
  "module": "Sofa.Component.Constraint.Lagrangian.Solver",
  "include": "sofa/component/constraint/lagrangian/solver/visitors/MechanicalGetConstraintViolationVisitor.h",
  "doc": "Gets the vector of constraint violation values",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdConstraintSet",
      "return_type": "Result",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        },
        {
          "name": "c",
          "type": "core::behavior::BaseConstraintSet *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalGetConstraintViolationVisitor` is part of the SOFA framework and is designed to retrieve the vector of constraint violation values in Lagrangian constraint solvers. It inherits from the `BaseMechanicalVisitor`, which facilitates traversal through nodes and components in a mechanical scene graph.\n\nThis visitor's primary role is to interact with `core::behavior::BaseConstraintSet` instances, calling their `getConstraintViolation` method to obtain the violation values for each constraint set. These violations indicate how much constraints are not being met within the simulation, which can be useful for debugging or assessing solver accuracy.\n\nThe component does not stop at mechanical mappings (it continues through them) unless explicitly required by a flag, indicating its role in comprehensive traversal and evaluation of constraint sets across the scene graph.\n\nIn practical usage, this visitor is typically used during post-processing or analysis phases to gather diagnostic information about constraint satisfaction within the simulation. It operates on `sofa::core::ConstraintParams` and stores results in a `sofa::linearalgebra::BaseVector`, providing a flexible mechanism for storing and retrieving violation values.",
  "maths": "The `MechanicalGetConstraintViolationVisitor` is a specialized visitor in the SOFA framework designed to retrieve constraint violation values, which are critical for assessing the satisfaction of constraints within the simulation. This visitor does not directly contribute to the governing equations or operators such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, or residual $R$. Instead, it plays a role in post-processing and diagnostic evaluations by collecting constraint violation data.\n\n### Governing Equations and Operators\n- **Constraint Violation**: In the context of Lagrangian mechanics with constraints, the governing equations often include Lagrange multipliers to enforce constraints. The equation for the constraint force can be written as:\n\\[ C(x) = 0 \\]\nwhere $C$ represents the constraint function and $x$ are the generalized coordinates (displacements). The violation of these constraints is given by the residual of this constraint equation.\n\n### Constitutive or Kinematic Laws Involved\n- **Constraint Violation**: This component does not directly involve constitutive laws such as strain measures, stress tensors, hyperelastic potentials, or damping models. Instead, it evaluates how well the imposed constraints are being satisfied in terms of the current state $x$ and Lagrange multipliers.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: During the assembly phase, constraint forces due to Lagrange multipliers are added into the global residual equation. The visitor is not involved in this active part of the simulation pipeline but rather retrieves information about these constraints post-processing.\n- **Nonlinear Solve**: In the nonlinear solve stage, where the Jacobian and tangent stiffness matrix are computed, the visitor does not participate directly. However, it can be used to analyze the solution quality by evaluating constraint satisfaction after each iteration or time step.\n\n### Numerical Methods and Discretization Choices\n- The component uses a post-processing approach to collect constraint violation values without modifying the discretization methods or numerical integration schemes used in the simulation. It operates on `sofa::core::ConstraintParams` and stores results in a `sofa::linearalgebra::BaseVector`.\n\n### Fit into Variational / Lagrangian Mechanics Framework\n- **Post-processing**: The visitor is not part of the primary variational or Lagrangian mechanics framework, which includes weak formulations, FEM discretization, time integration, and nonlinear resolution. Instead, it provides diagnostics on constraint satisfaction, a crucial aspect for validating the numerical solution's consistency with physical constraints.\n\n### Summary\n- **Mathematical Content**: The `MechanicalGetConstraintViolationVisitor` is not involved in defining governing equations or operators but rather serves to gather diagnostic information about constraint satisfaction after the simulation has progressed. This makes it an essential tool for post-processing and validation purposes.",
  "abstract": "Retrieves the vector of constraint violation values for Lagrangian constraints, facilitating post-processing and validation diagnostics.",
  "sheet": "# MechanicalGetConstraintViolationVisitor\n\n## Overview\nThe `MechanicalGetConstraintViolationVisitor` retrieves the vector of constraint violation values in Lagrangian constraint solvers. It inherits from `BaseMechanicalVisitor`, enabling traversal through nodes and components within a mechanical scene graph to collect diagnostic information about constraint satisfaction.\n\n## Practical Notes\nThis visitor is typically used during post-processing or analysis phases to gather diagnostic information about constraint satisfaction within the simulation. It operates on `sofa::core::ConstraintParams` and stores results in a `sofa::linearalgebra::BaseVector`, providing a flexible mechanism for storing and retrieving violation values."
}