Data Fields

Links

Methods

{
  "name": "UncoupledConstraintCorrection",
  "namespace": "sofa::component::constraint::lagrangian::correction",
  "module": "Sofa.Component.Constraint.Lagrangian.Correction",
  "include": "sofa/component/constraint/lagrangian/correction/UncoupledConstraintCorrection.h",
  "doc": "Component computing constraint forces within a simulated body using the compliance method, approximating the compliance matrix by a diagonal matrix.\n\nComponent computing constraint forces within a simulated body using the compliance method.",
  "inherits": [
    "ConstraintCorrection"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "d_defaultCompliance",
      "type": "Real",
      "xmlname": "defaultCompliance",
      "help": "Default compliance value for new dof or if all should have the same (in which case compliance vector should be empty)"
    },
    {
      "name": "d_verbose",
      "type": "bool",
      "xmlname": "verbose",
      "help": "Dump the constraint matrix at each iteration"
    },
    {
      "name": "d_correctionVelocityFactor",
      "type": "Real",
      "xmlname": "correctionVelocityFactor",
      "help": "Factor applied to the constraint forces when correcting the velocities"
    },
    {
      "name": "d_correctionPositionFactor",
      "type": "Real",
      "xmlname": "correctionPositionFactor",
      "help": "Factor applied to the constraint forces when correcting the positions"
    },
    {
      "name": "d_useOdeSolverIntegrationFactors",
      "type": "bool",
      "xmlname": "useOdeSolverIntegrationFactors",
      "help": "Use odeSolver integration factors instead of correctionVelocityFactor and correctionPositionFactor"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "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": "sofa::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": "getComplianceWithConstraintMerge",
      "return_type": "void",
      "params": [
        {
          "name": "Wmerged",
          "type": "linearalgebra::BaseMatrix *"
        },
        {
          "name": "constraint_merge",
          "type": "int &"
        }
      ],
      "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 sofa::core::ConstraintParams *"
        },
        {
          "name": "x",
          "type": "Data<VecCoord> &"
        },
        {
          "name": "v",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "dx",
          "type": "Data<VecDeriv> &"
        },
        {
          "name": "correction",
          "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": "correction",
          "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": "correction",
          "type": "const Data<VecDeriv> &"
        }
      ],
      "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": "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": "",
          "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": "computeDx",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "const Data<VecDeriv> &"
        },
        {
          "name": "x",
          "type": "VecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `UncoupledConstraintCorrection` is a SOFA component designed to compute constraint forces within a simulated body using the compliance method, approximating the compliance matrix by a diagonal matrix. This class inherits from `sofa::core::behavior::ConstraintCorrection<TDataTypes>` and operates on various types like `Rigid3Types` and `Vec1Types`. Its primary role is to handle constraint correction based on compliance values provided or computed for each degree of freedom (DOF). The component supports both verbose output and customizable correction factors for velocity and position adjustments. It also interacts with the topology container through a link, enabling synchronization and management of the DOFs' compliance values.\n\n**Interactions:**\nThe `UncoupledConstraintCorrection` class is designed to work closely with other SOFA components like `MechanicalState`, `OdeSolver`, and `BaseMeshTopology`. It reads constraints from the mechanical state and applies corrections based on force data, updating positions and velocities according to specified integration factors or default compliance values. This interaction facilitates constraint resolution in multi-body dynamics simulations.\n\n**Usage Guidance:**\nThe component requires setting a link (`topology`) to the topology container for accurate behavior. It supports customizing compliance via `defaultCompliance` or a vector of specific compliance values per DOF, with warnings and error messages provided for invalid settings. The correction factors (`correctionVelocityFactor`, `correctionPositionFactor`) can be adjusted to control how corrections are applied based on the constraint forces. For rigid bodies, additional checks ensure non-zero compliance values to prevent numerical issues.",
  "maths": "### Governing Equations and Operators\n\nThe `UncoupledConstraintCorrection` component in the SOFA framework computes constraint forces within a simulated body using the compliance method, approximating the compliance matrix by a diagonal matrix. This approach is rooted in Lagrangian mechanics and variational principles, particularly in how constraints are handled to ensure physical consistency.\n\n#### Compliance Matrix\nThe compliance matrix $W$ represents the inverse of the stiffness matrix for each degree of freedom (DOF). For a given DOF $i$, the compliance can be represented as:\n\\[ w_{ii} = \\frac{1}{k_i}, \\]\nwhere $k_i$ is the stiffness at DOF $i$. The component approximates this by using diagonal values, either from a `defaultCompliance` value or a vector of specific compliance values per DOF.\n\n#### Constraint Force and Compliance\nThe constraint force $f_c$ is computed based on the compliance matrix $W$ and the deviation from the constraints. If $\\lambda$ denotes the Lagrange multiplier (constraint force), then:\n\\[ \\lambda = W \times f, \\]\nwhere $f$ represents the forces acting within the system.\n\n#### Correction API Methods\n- **computeMotionCorrection**: Computes motion correction based on the applied constraint forces. Given a force vector $f$, it calculates the displacement correction vector $dx$ as follows:\n\\[ dx = W \times f. \\]\n\n- **applyMotionCorrection**: Applies the computed corrections to position and velocity, using factors for each (position correction factor $x_f$ and velocity correction factor $v_f$):\n\\[ x[i] = x_{free}[i] + dx[i] \\times x_f, \\]\n\\[ v[i] = v_{free}[i] + dx[i] \\times v_f. \\]\n\n- **applyPositionCorrection**: Adjusts positions based on the constraint forces and a position factor $x_f$:\n\\[ x[i] = x_{free}[i] + correction[i] \\times x_f. \\]\n\n- **applyVelocityCorrection**: Updates velocities using a velocity factor $v_f$:\n\\[ v[i] = v_{free}[i] + correction[i] \\times v_f. \\]\n\n#### Role in the Global FEM Pipeline\n1. **Assembly Phase**:\n   - The component is responsible for assembling and handling compliance matrices, which are diagonal approximations of the full stiffness matrix. It interacts with other components such as `MechanicalState` to access constraint Jacobians.\n2. **Time Integration**:\n   - During time integration, it computes corrections based on the forces applied at each DOF using the compliance method.\n3. **Nonlinear Resolution**:\n   - The component contributes to solving nonlinear systems by ensuring that constraints are satisfied within the simulation loop.\n4. **Linear Solution**:\n   - It facilitates matrix-free operations and iterative solvers by providing the necessary correction factors and compliance values for each DOF.\n5. **Update Phase**:\n   - State updates occur after applying motion corrections, which include both position and velocity adjustments based on computed displacements and velocities.\n\n#### Numerical Methods and Discretization Choices\n- The component utilizes a diagonal approximation of the compliance matrix, simplifying the numerical solution process by reducing computational complexity.\n- It supports integration factors from an ODE solver or custom factors provided through parameters like `correctionPositionFactor` and `correctionVelocityFactor`, ensuring stability and accuracy in time integration schemes such as implicit Euler.\n\n#### Variational / Lagrangian Mechanics Framework\nThe component fits into the broader variational framework by implementing constraints through the compliance method, where the compliance matrix $W$ ensures that forces are distributed consistently across DOFs. This is consistent with the variational formulation of mechanics, where the system's energy and constraints are minimized to derive the equations of motion.\n\n### Summary\nThe `UncoupledConstraintCorrection` component in SOFA handles constraint resolution by approximating the compliance matrix as a diagonal matrix. It provides methods for computing corrections based on applied forces and updating positions and velocities accordingly, ensuring that constraints are consistently satisfied throughout the simulation process.",
  "abstract": "The UncoupledConstraintCorrection component computes constraint forces within a simulated body using the compliance method with a diagonal approximation of the compliance matrix.",
  "sheet": "# UncoupledConstraintCorrection\n\n## Overview\nThe `UncoupledConstraintCorrection` is a SOFA component that computes constraint forces within a simulated body using the compliance method, approximating the compliance matrix by a diagonal matrix. It inherits from `sofa::core::behavior::ConstraintCorrection<TDataTypes>` and operates on various types like `Rigid3Types` and `Vec1Types`. This component handles constraint correction based on compliance values provided or computed for each degree of freedom (DOF).\n\n## Mathematical Model\nThe compliance matrix $W$ represents the inverse of the stiffness matrix for each DOF. For a given DOF $i$, the compliance can be represented as:\n\\[ w_{ii} = \\frac{1}{k_i}, \\]\nwhere $k_i$ is the stiffness at DOF $i$. The component approximates this by using diagonal values, either from a `defaultCompliance` value or a vector of specific compliance values per DOF.\n\nThe constraint force $f_c$ is computed based on the compliance matrix $W$ and the deviation from the constraints. If $\\lambda$ denotes the Lagrange multiplier (constraint force), then:\n\\[ \\lambda = W f, \\]\nwhere $f$ represents the forces acting within the system.\n\nThe component provides methods for computing motion correction based on applied constraint forces. Given a force vector $f$, it calculates the displacement correction vector $dx$ as follows:\n\\[ dx = W f. \\]\n\nIt also applies these corrections to position and velocity using factors for each (position correction factor $x_f$ and velocity correction factor $v_f$):\n\\[ x[i] = x_{free}[i] + dx[i] \\times x_f, \\]\n\\[ v[i] = v_{free}[i] + dx[i] \\times v_f. \\]\n\n## Parameters and Data\n- **defaultCompliance**: Default compliance value for new DOF or if all should have the same (in which case compliance vector should be empty). Type: `Real`.\n- **verbose**: Dump the constraint matrix at each iteration. Type: `bool`, default: `false`.\n- **correctionVelocityFactor**: Factor applied to the constraint forces when correcting the velocities. Type: `Real`, default: `1.0`.\n- **correctionPositionFactor**: Factor applied to the constraint forces when correcting the positions. Type: `Real`, default: `1.0`.\n- **useOdeSolverIntegrationFactors**: Use ODE solver integration factors instead of correctionVelocityFactor and correctionPositionFactor. Type: `bool`, default: `false`."
}