Methods

{
  "name": "MechanicalGetConstraintJacobianVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalGetConstraintJacobianVisitor.h",
  "doc": "",
  "inherits": [
    "BaseMechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "ms",
          "type": "core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalGetConstraintJacobianVisitor` is a component in the SOFA framework designed to retrieve the Jacobian matrix associated with constraints from mechanical states within a simulation. It inherits from `BaseMechanicalVisitor`, allowing it to traverse and interact with nodes and mechanical states in a scene graph.\n\nThis visitor initializes with parameters including constraint settings (`core::ConstraintParams`), a pointer to a base matrix where the Jacobian will be stored, and an optional `MultiMatrixAccessor`. The primary method is `fwdMechanicalState`, which visits each node's mechanical state and retrieves the constraint Jacobian matrix using the provided matrix accessor. This operation helps in solving constrained systems by extracting necessary information for iterative or direct solvers.\n\nThe component interacts with other SOFA components such as `Node`, `BaseMechanicalState`, and `ConstraintParams` to gather and process data required for mechanical simulations involving constraints.",
  "maths": "The `MechanicalGetConstraintJacobianVisitor` is a component in the SOFA framework designed to retrieve the Jacobian matrix associated with constraints from mechanical states within a simulation. This visitor plays a crucial role in handling constrained systems, where constraints restrict admissible motion and are typically handled using Lagrange multipliers.\n\n### Governing Equations or Operators\nThe primary mathematical object managed by this component is the constraint Jacobian matrix, denoted as $J$. The constraint Jacobian matrix captures how the constraints vary with respect to the generalized coordinates of the system. Specifically, if we consider a set of holonomic constraints $g(x) = 0$, where $x$ are the generalized coordinates, then the constraint Jacobian is defined as:\n\n\begin{equation}\nJ = \\frac{\\partial g}{\\partial x}.\n\\end{equation}\n\n### Constitutive or Kinematic Laws Involved\nThe constraints themselves can be of different types (holonomic or non-holonomic), and the Jacobian matrix $J$ is essential for solving the constrained system. The visitor retrieves this information from each mechanical state, which may include various types of mechanical components such as deformable solids, rigid bodies, and more.\n\n### Role in Global FEM Pipeline\nIn the context of the global Finite Element Method (FEM) pipeline:\n- **Assembly Phase**: This component is involved in assembling the Jacobian matrix for constraints. The `fwdMechanicalState` method visits each node's mechanical state to gather this information, which is then used by iterative or direct solvers.\n- **Nonlinear Resolution**: The retrieved Jacobian $J$ contributes to solving nonlinear systems of equations with constraints. The Lagrange multiplier system can be expressed in the form:\n\n\begin{equation}\n\\begin{bmatrix}\nM & J^T \\\\\nJ & 0\n\\end{bmatrix}\n\\begin{bmatrix}\n\\ddot{x} \\\\ \\lambda\n\\end{bmatrix}\n=\n\\begin{bmatrix}\nf \\\\ c\n\\end{bmatrix},\n\\end{equation}\n\nwhere $M$ is the mass matrix, $J$ is the constraint Jacobian, $\bar x$ are the generalized coordinates, and $\bar \rho$ are Lagrange multipliers. The constraints $g(x) = 0$ are included in the system to ensure that motion remains feasible.\n\n### Numerical Methods or Discretization Choices\nThe visitor retrieves the constraint Jacobian matrix at each mechanical state by calling `getConstraintJacobian` on the `BaseMechanicalState`. This method is part of a broader scene graph traversal mechanism, ensuring that all relevant components contribute their constraints to the global system.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nIn variational mechanics and Lagrangian formalism, constraints are incorporated through the principle of virtual work or the Lagrange multiplier approach. The retrieved Jacobian matrix $J$ ensures that these principles are enforced at the discrete level within the simulation pipeline. This component fits into a broader framework where mechanical states interact with constraint solvers to enforce physical consistency and numerical stability.",
  "abstract": "The `MechanicalGetConstraintJacobianVisitor` retrieves the Jacobian matrix associated with constraints from mechanical states within a simulation, facilitating the handling of constrained systems in the SOFA framework.",
  "sheet": "# MechanicalGetConstraintJacobianVisitor\n\n## Overview\n\nThe `MechanicalGetConstraintJacobianVisitor` is a visitor component that retrieves the Jacobian matrix associated with constraints from mechanical states within a simulation. It inherits from `BaseMechanicalVisitor`, allowing it to traverse and interact with nodes and mechanical states in a scene graph. This component plays a crucial role in handling constrained systems by assembling constraint information for iterative or direct solvers.\n\n## Mathematical Model\n\nThe primary mathematical object managed by this component is the constraint Jacobian matrix, denoted as $J$. The constraint Jacobian matrix captures how the constraints vary with respect to the generalized coordinates of the system. Specifically, if we consider a set of holonomic constraints $g(x) = 0$, where $x$ are the generalized coordinates, then the constraint Jacobian is defined as:\n\n\\[ J = \\frac{\\partial g}{\\partial x}. \\]\n\nIn the context of variational mechanics and Lagrangian formalism, constraints are incorporated through the principle of virtual work or the Lagrange multiplier approach. The retrieved Jacobian matrix $J$ ensures that these principles are enforced at the discrete level within the simulation pipeline.\n\n## Dependencies and Connections\n\nThis component interacts with other SOFA components such as `Node`, `BaseMechanicalState`, and `ConstraintParams` to gather and process data required for mechanical simulations involving constraints. The primary method, `fwdMechanicalState`, visits each node's mechanical state to retrieve the constraint Jacobian matrix using the provided matrix accessor."
}