Methods

{
  "name": "MechanicalApplyConstraintsVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalApplyConstraintsVisitor.h",
  "doc": "Apply the constraints as filters to the given vector.\nThis works for simple independent constraints, like maintaining a fixed point.",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMappedMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdProjectiveConstraintSet",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "c",
          "type": "sofa::core::behavior::BaseProjectiveConstraintSet *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getInfos",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isThreadSafe",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalApplyConstraintsVisitor` is a component in the SOFA framework that applies constraints as filters to a given vector. It primarily handles simple independent constraints, such as maintaining fixed points within the simulation. This visitor inherits from the `MechanicalVisitor` class and implements methods for forward and backward traversal through mechanical states and constraint sets.\n\n### Role and Purpose\n- **Role**: The primary role of this component is to enforce specified constraints on the simulation by modifying vectors that represent physical properties (e.g., positions, velocities) in the simulation. It ensures that these constraints are respected during the simulation process.\n- **Purpose**: To maintain the integrity of predefined constraints within the mechanical state of a SOFA simulation. This is crucial for ensuring accurate and physically meaningful results, especially when dealing with complex systems where certain points or regions need to remain fixed or constrained.\n\n### Interactions with Other Components\n- `fwdMechanicalState` and `fwdMappedMechanicalState`: These methods are called during the forward traversal of mechanical states. They interact with nodes and mechanical states (`BaseMechanicalState`) in the scene graph, ensuring that constraints are applied as part of the simulation loop.\n- `bwdProjectiveConstraintSet`: This method is used to apply projective constraint sets backward through the simulation process. It interacts with constraint sets (`BaseProjectiveConstraintSet`), projecting responses back into the system.\n\n### Practical Usage and Data Fields\n- **Data Fields**: The component contains fields such as `res`, which represents a multi-vector derivative identifier, and `W`, which is an array of doubles used for weighting or transformation. These fields are essential for specifying how constraints should be applied during simulation.\n- **Usage Guidance**: This visitor must traverse through all mechanical mappings to ensure that constraints are correctly enforced regardless of the mapping settings. Users can configure this component by setting the appropriate `res` and `W` parameters according to their specific constraint requirements.",
  "maths": "The `MechanicalApplyConstraintsVisitor` component in the SOFA framework is responsible for enforcing constraints within the simulation. It operates by modifying vectors that represent physical properties such as positions and velocities to ensure these constraints are respected during the simulation process.\n\n### Governing Equations and Operators\n- **Role**: This component primarily contributes to ensuring constraints are applied correctly, which involves filtering or projecting constraint conditions onto system states represented by vectors. The specific operations include:\n  - Applying simple independent constraints such as fixed points.\n  - Projecting responses from projective constraint sets back into the system state.\n\n### Constitutive and Kinematic Laws Involved\n- **Constraints**: The component handles holonomic (position-based) or non-holonomic (velocity-based) constraints. For example, maintaining a fixed point involves setting certain degrees of freedom to specific values or enforcing conditions like:\n  \\[ u_i = \\bar{u}_i \\]\n  where \\( u_i \\) is the displacement at node \\( i \\), and \\( \\bar{u}_i \\) is the prescribed value.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: This visitor ensures that constraints are correctly applied to the system state vectors, particularly during backward traversal through mechanical states (`bwdProjectiveConstraintSet`).\n  - Example: Applying projective constraint sets:\n    \\[ u_i = P_{ij} u_j + c_i \\]\n    where \\( P_{ij} \\) is a projection matrix and \\( c_i \\) are constant terms.\n- **Nonlinear Solve**: Constraints are enforced in the nonlinear solution phase by modifying residual vectors or Jacobians accordingly.\n  - Example: Modifying the residual vector:\n    \\[ R(x + \\delta x) = R(x) + J(x)\\delta x \\]\n    where constraints enforce specific conditions on \\( \\delta x \\).\n\n### Numerical Methods and Discretization Choices\n- **Numerical Integration**: This component does not directly implement numerical integration schemes but ensures that constraints are respected during the implicit time integration process.\n  - Example: Implicit Euler scheme with constraints:\n    \\[ M\\frac{x_{n+1} - x_n}{\\Delta t} = f_{ext}(t) - f_{int}(x_{n+1}) + C^T \\lambda \\]\n    where \\( C \\) is the constraint matrix and \\( \\lambda \\) are Lagrange multipliers.\n- **Constraint Handling**: The component handles constraints by projecting response vectors, ensuring that physical invariants (e.g., fixed points) are preserved.\n  - Example: Projection step:\n    \\[ u_i = P_{ij} u_j + c_i \\]\n\n### Integration into the Variational / Lagrangian Mechanics Framework\n- **Variational Formulation**: Constraints can be incorporated into variational principles via Lagrange multipliers or direct projection.\n  - Example: With Lagrange multipliers:\n    \\[ L(q,\\dot{q},\\lambda) = T(q,\\dot{q}) - V(q) + \\lambda^T C(q) \\]\n- **Mechanical State**: Constraints are enforced during mechanical state updates to maintain consistency with variational principles.\n  - Example: Constraint enforcement in weak form:\n    \\[ \\int_{\\Omega} \\rho \\ddot{u} \\cdot w \\, d\\Omega + \\sigma : \\varepsilon(w) = f_{ext}(w) + C^T \\lambda \\]\n\n### Conclusion\nThe `MechanicalApplyConstraintsVisitor` ensures that constraints are properly enforced during the simulation process by modifying vectors representing physical properties. It plays a critical role in maintaining the integrity and accuracy of the mechanical states within the SOFA framework.",
  "abstract": "The `MechanicalApplyConstraintsVisitor` applies constraints as filters to vectors representing physical properties in the simulation, ensuring that simple independent constraints such as maintaining fixed points are respected during the simulation process.",
  "sheet": "# MechanicalApplyConstraintsVisitor\n\n## Overview\nThe `MechanicalApplyConstraintsVisitor` is a component within the SOFA framework responsible for enforcing specified constraints on the simulation by modifying vectors representing physical properties (e.g., positions, velocities). It primarily handles simple independent constraints such as maintaining fixed points. This visitor inherits from the `MechanicalVisitor` class and interacts with mechanical states (`BaseMechanicalState`) and constraint sets (`BaseProjectiveConstraintSet`).\n\n## Dependencies and Connections\nThe component typically requires interactions with other SOFA components, particularly those related to mechanical states and constraints. It traverses through nodes and mappings in the scene graph to ensure that constraints are correctly enforced during forward and backward traversal.\n"
}