Data Fields

Links

Methods

{
  "name": "LinearSolverConstraintCorrection",
  "namespace": "sofa::component::constraint::lagrangian::correction",
  "module": "Sofa.Component.Constraint.Lagrangian.Correction",
  "include": "sofa/component/constraint/lagrangian/correction/LinearSolverConstraintCorrection.h",
  "doc": "Component computing constraint forces within a simulated body using the compliance method.\n\nComponent computing constrained forces within a simulated body using the compliance method.",
  "inherits": [
    "ConstraintCorrection"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "wire_optimization",
      "type": "bool",
      "xmlname": "wire_optimization",
      "help": "constraints are reordered along a wire-like topology (from tip to base)"
    },
    {
      "name": "d_regularizationTerm",
      "type": "SReal",
      "xmlname": "regularizationTerm",
      "help": "Add regularization factor times the identity matrix to the compliance W when solving constraints"
    }
  ],
  "links": [
    {
      "name": "l_linearSolver",
      "target": "LinearSolver",
      "kind": "single",
      "xmlname": "linearSolver",
      "help": "Link towards the linear solver used to compute the compliance matrix, requiring the inverse of the linear system matrix"
    },
    {
      "name": "l_ODESolver",
      "target": "OdeSolver",
      "kind": "single",
      "xmlname": "ODESolver",
      "help": "Link towards the ODE solver used to recover the integration factors"
    }
  ],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addRegularization",
      "return_type": "void",
      "params": [
        {
          "name": "W",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addComplianceInConstraintSpace",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "W",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getComplianceMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeMotionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "dx",
          "type": "core::MultiVecDerivId"
        },
        {
          "name": "f",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyMotionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const core::ConstraintParams *"
        },
        {
          "name": "x",
          "type": "Data<VecCoord> &"
        },
        {
          "name": "v",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "dx",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "f",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyPositionCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "x",
          "type": "Data<VecCoord> &"
        },
        {
          "name": "dx",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "f",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyVelocityCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "cparams",
          "type": "const sofa::core::ConstraintParams *"
        },
        {
          "name": "v",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "dv",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "f",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "rebuildSystem",
      "return_type": "void",
      "params": [
        {
          "name": "massFactor",
          "type": "SReal"
        },
        {
          "name": "forceFactor",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyContactForce",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "const linearalgebra::BaseVector *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resetContactForce",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "verify_constraints",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "hasConstraintNumber",
      "return_type": "bool",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resetForUnbuiltResolution",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "SReal *"
        },
        {
          "name": "renumbering",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addConstraintDisplacement",
      "return_type": "void",
      "params": [
        {
          "name": "d",
          "type": "SReal *"
        },
        {
          "name": "begin",
          "type": "int"
        },
        {
          "name": "end",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setConstraintDForce",
      "return_type": "void",
      "params": [
        {
          "name": "df",
          "type": "SReal *"
        },
        {
          "name": "begin",
          "type": "int"
        },
        {
          "name": "end",
          "type": "int"
        },
        {
          "name": "update",
          "type": "bool"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getBlockDiagonalCompliance",
      "return_type": "void",
      "params": [
        {
          "name": "W",
          "type": "linearalgebra::BaseMatrix *"
        },
        {
          "name": "begin",
          "type": "int"
        },
        {
          "name": "end",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "convertConstraintMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "numberOfConstraints",
          "type": "int"
        },
        {
          "name": "inputConstraintMatrix",
          "type": "const MatrixDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeJ",
      "return_type": "void",
      "params": [
        {
          "name": "W",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "j",
          "type": "const MatrixDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `LinearSolverConstraintCorrection` is a SOFA component that computes constrained forces within a simulated body using the compliance method, inheriting from `sofa::core::behavior::ConstraintCorrection`. It supports different data types like `Rigid3Types` and `Vec3Types`. This component links to both an ODE solver (`l_ODESolver`) and a linear solver (`l_linearSolver`), which are required for computing the compliance matrix and applying motion corrections, respectively. The component handles various operations such as adding regularization terms to matrices, converting constraint matrices, and applying contact forces. Additionally, it provides methods for rebuilding systems, applying position and velocity corrections, and managing the mechanical state during the simulation process.",
  "maths": "\n### Governing Equations and Operators\n\nThe `LinearSolverConstraintCorrection` component in the SOFA framework is primarily responsible for computing constraint forces within a simulated body using the compliance method. The key operators and equations involved include:\n\n- **Compliance Matrix (W)**: \n  This matrix represents the inverse of the stiffness associated with constraints, i.e., \\( W = J A^{-1} J^T \\), where \\(J\\) is the Jacobian matrix representing constraint forces, and \\(A\\) is the mechanical system matrix. It plays a crucial role in ensuring that the motion satisfies imposed constraints.\n\n- **Regularization**: \n  To stabilize the compliance matrix, regularization terms are added to it: \\( W_{regularized} = W + \\lambda I \\), where \\(I\\) is the identity matrix and \\(λ\\) is a scalar regularization factor. This ensures that the matrix remains positive definite.\n\n### Constitutive or Kinematic Laws Involved\n\n- **Constraint Jacobian (J)**: \n  The constraint forces are computed using the Jacobian matrix \\( J \\), which represents how constraints affect the system's state. Specifically, \\( J \\) maps nodal displacements to constraint violations.\n\n- **Internal Force Computation**: \n  The internal forces are computed via the compliance matrix: \\(Δ F = W Δ λ\\), where \\(Δ λ\\) is the Lagrange multiplier vector representing constraint forces. This ensures that the system satisfies constraints in a physically consistent manner.\n\n### Role in the Global FEM Pipeline\n\n- **Assembly**: The component assembles contributions to the compliance matrix by using the linked linear solver to compute \\( J A^{-1} J^T \\).\n\n- **Time Integration**: It uses the ODE solver to obtain integration factors for position and velocity updates.\n\n- **Nonlinear Solution**: During the nonlinear solve step, the component ensures that constraints are satisfied by applying motion corrections via \\(Δ x\\) and \\(Δ v\\), which are computed using the compliance matrix.\n\n- **Linear Solve**: The linear solver is used to solve for Lagrange multipliers ensuring constraint satisfaction.\n\n### Numerical Methods or Discretization Choices\n\n- **Regularization of Compliance Matrix**: \n  To handle numerical stability issues, a small regularization term \\(λ I\\) is added to the compliance matrix \\(W\\).\n\n- **Conversion and Manipulation of Constraint Matrices**: \n  The component converts constraint matrices from their initial form to a more manageable format suitable for solving.\n\n### Integration into Variational/Lagrangian Mechanics Framework\n\nThe `LinearSolverConstraintCorrection` fits into the broader variational mechanics framework by ensuring that constraints are satisfied via Lagrange multipliers and compliance methods. Specifically, it contributes to maintaining physical consistency in systems with holonomic or non-holonomic constraints.\n\nBy leveraging the linked linear solver, this component can efficiently compute constraint forces while preserving numerical stability through regularization techniques.",
  "abstract": "The `LinearSolverConstraintCorrection` computes constrained forces within a simulated body using the compliance method, linking to both an ODE solver and a linear solver for system integration and constraint satisfaction.",
  "sheet": "# LinearSolverConstraintCorrection\n\n## Overview\n\nThe `LinearSolverConstraintCorrection` component is responsible for computing constrained forces within a simulated body using the compliance method. It inherits from `sofa::core::behavior::ConstraintCorrection` and supports different data types like `Rigid3Types` and `Vec3Types`. This component links to both an ODE solver (`l_ODESolver`) and a linear solver (`l_linearSolver`), which are required for computing the compliance matrix and applying motion corrections, respectively.\n\n## Mathematical Model\n\nThe key operators and equations involved include:\n\n- **Compliance Matrix (W)**: This matrix represents the inverse of the stiffness associated with constraints, i.e., \\( W = J A^{-1} J^T \\), where \\(J\\) is the Jacobian matrix representing constraint forces, and \\(A\\) is the mechanical system matrix. It plays a crucial role in ensuring that the motion satisfies imposed constraints.\n\n- **Regularization**: To stabilize the compliance matrix, regularization terms are added to it: \\( W_{regularized} = W + \\lambda I \\), where \\(I\\) is the identity matrix and \\(λ\\) is a scalar regularization factor. This ensures that the matrix remains positive definite.\n\n- **Internal Force Computation**: The internal forces are computed via the compliance matrix: \\(Δ F = W Δ λ\\), where \\(Δ λ\\) is the Lagrange multiplier vector representing constraint forces. This ensures that the system satisfies constraints in a physically consistent manner.\n\n## Parameters and Data\n\n- **wire_optimization (bool)**: Constraints are reordered along a wire-like topology from tip to base.\n- **regularizationTerm (SReal)**: Adds a regularization factor times the identity matrix to the compliance \\(W\\) when solving constraints.\n\n## Dependencies and Connections\n\nThe component requires connections to both an ODE solver (`l_ODESolver`) and a linear solver (`l_linearSolver`). These links are essential for computing the compliance matrix and applying motion corrections, respectively.\n\n## Practical Notes\n\nNumerical stability is ensured through regularization techniques. The wire optimization parameter can be used to reorder constraints along a specific topology, which may improve computational efficiency or numerical stability in certain scenarios."
}