Methods

{
  "name": "MechanicalBuildConstraintMatrix",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalBuildConstraintMatrix.h",
  "doc": "Call each BaseConstraintSet to build the Jacobian matrices",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "constraintParams",
      "return_type": "const sofa::core::ConstraintParams *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdConstraintSet",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "c",
          "type": "sofa::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": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "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 `MechanicalBuildConstraintMatrix` is a component in the SOFA framework responsible for building Jacobian matrices by calling each `BaseConstraintSet`. It inherits from `BaseMechanicalVisitor`, indicating its role in visiting and processing mechanical elements within the simulation scene. The main purpose of this visitor is to construct constraint matrices required for solving constrained dynamics problems, particularly relevant for handling constraints such as contacts or joints between different parts of a simulated system.\n\n### Interactions with Other Components:\n- **BaseConstraintSet:** It interacts with `BaseConstraintSet` components through the `fwdConstraintSet` method, which calls the `buildConstraintMatrix` function on each constraint set. This ensures that the Jacobian matrices are correctly built for constraints within the scene.\n- **Node and BaseMapping:** The component also interacts with nodes (`simulation::Node`) and mappings (`sofa::core::BaseMapping`). For instance, it overrides the `stopAtMechanicalMapping` method to ensure all mechanical mappings are processed regardless of the `isMechanical` flag.\n\n### Usage Guidance:\n- **Thread Safety:** The component is not thread-safe as indicated by the overridden `isThreadSafe` method returning `false`. This suggests that care must be taken when using this visitor in a multi-threaded environment to avoid race conditions or other concurrency issues.\n- **Constraint Parameters and Results Storage:** It uses constraint parameters (`sofa::core::ConstraintParams`) provided during initialization. The resulting Jacobian matrices are stored in the specified `res` field, with contact IDs managed through the `contactId` reference parameter.\n\n### Data Fields:\n- `constraintParams`: Provides access to the constraint parameters used for building the matrices.\n- `fwdConstraintSet`: Visits and processes each `BaseConstraintSet`, calling its `buildConstraintMatrix` method.",
  "maths": "<p>The `MechanicalBuildConstraintMatrix` component is responsible for building the Jacobian matrices, which are essential in handling constrained dynamics problems. It interacts with various mechanical components within the simulation scene to ensure that the constraints (such as contacts or joints) are correctly represented.</p>\n\n<h3>Governing Equations and Operators</h3>\n\n<p>The component contributes to the construction of Jacobian matrices, denoted as $J$, which describe how constraints affect the system's dynamics. These Jacobian matrices are crucial for formulating constraint equations:</p>\n\n\begin{equation}\n  J(x) \\lambda = r(x)\n\\end{equation}\n\n<p>where $x$ represents the nodal displacements, $\\lambda$ denotes Lagrange multipliers associated with the constraints, and $r(x)$ is the residual vector.</p>\n\n<h3>Constitutive or Kinematic Laws</h3>\n\n<p>The component itself does not directly involve constitutive laws (such as strain measures or stress tensors). Instead, it focuses on assembling the constraint matrices. The Jacobian matrix $J$ encodes kinematic constraints that may arise from:</p>\n<ul>\n  <li>Positional constraints: where $J(x)$ is derived from position-based constraints.</li>\n  <li>Velocity-based non-holonomic constraints: where $J(x, \\dot{x})$ includes velocity terms.</li>\n</ul>\n\n<h3>Role in the Global FEM Pipeline</h3>\n\n<p>In the context of the global FEM pipeline:</p>\n<ul>\n  <li><strong>Assembly Phase:</strong> The component assembles Jacobian matrices for each `BaseConstraintSet`. This assembly ensures that all constraints are accounted for in the system of equations.</li>\n  <li><strong>Time Integration and Nonlinear Solve:</strong> These assembled matrices play a critical role in the nonlinear solution phase, particularly when solving constrained dynamics problems using methods like Newton-Raphson iteration.</li>\n</ul>\n\n<h3>Numerical Methods or Discretization Choices</h3>\n\n<p>The component uses an operator-driven approach to build Jacobian matrices:</p>\n<ul>\n  <li>Each `BaseConstraintSet` is visited and its `buildConstraintMatrix` method is called.</li>\n  <li>This ensures that the assembled Jacobians are consistent with the variational formulation of constraints within the system.</li>\n</ul>\n\n<h3>Fitting into Variational / Lagrangian Mechanics Framework</h3>\n\n<p>The component fits into the broader variational framework by contributing to the assembly of constraint matrices, which are essential for formulating and solving constrained dynamics problems:</p>\n<ul>\n  <li>From a variational perspective, these constraints ensure that the action principle (or the Lagrangian mechanics formulation) is respected.</li>\n  <li>The resulting system of equations must be solved to ensure both dynamic consistency and constraint satisfaction.</li>\n</ul>",
  "abstract": "The `MechanicalBuildConstraintMatrix` builds Jacobian matrices by visiting each `BaseConstraintSet`, enabling the solution of constrained dynamics problems in SOFA simulations.",
  "sheet": "# MechanicalBuildConstraintMatrix\n\n## Overview\n\nThe `MechanicalBuildConstraintMatrix` is a visitor component that assembles Jacobian matrices for constraints within the simulation scene. It inherits from `BaseMechanicalVisitor` and interacts with `BaseConstraintSet` components to ensure all constraints are correctly represented in the system of equations.\n\n## Mathematical Model\n\nThe component constructs Jacobian matrices, denoted as $J$, which describe how constraints affect the system's dynamics. These matrices are essential for formulating constraint equations:\n\n\\[ J(x) \\lambda = r(x) \\]\n\nwhere $x$ represents nodal displacements, $\\lambda$ denotes Lagrange multipliers associated with the constraints, and $r(x)$ is the residual vector.\n\n## Parameters and Data\n\n- **constraintParams**: Provides access to the constraint parameters used for building the matrices.\n- **fwdConstraintSet**: Visits and processes each `BaseConstraintSet`, calling its `buildConstraintMatrix` method.\n\n## Dependencies and Connections\n\nThe component interacts with:\n- `BaseConstraintSet`: Through the `fwdConstraintSet` method, it calls the `buildConstraintMatrix` function on each constraint set to build Jacobian matrices.\n- `Node` and `BaseMapping`: It processes mechanical mappings within nodes using the `stopAtMechanicalMapping` method.\n\n## Practical Notes\n\nThe component is not thread-safe as indicated by the overridden `isThreadSafe` method returning `false`. Care must be taken when using this visitor in a multi-threaded environment to avoid race conditions or other concurrency issues."
}