Mathematical and Physical Description of ConstraintAnimationLoop

Data Fields

Methods

{
  "name": "ConstraintAnimationLoop",
  "namespace": "sofa::component::animationloop",
  "module": "Sofa.Component.AnimationLoop",
  "include": "sofa/component/animationloop/ConstraintAnimationLoop.h",
  "doc": "Constraint animation loop manager",
  "inherits": [
    "CollisionAnimationLoop"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_displayTime",
      "type": "bool",
      "xmlname": "displayTime",
      "help": "Display time for each important step of ConstraintAnimationLoop."
    },
    {
      "name": "d_tol",
      "type": "SReal",
      "xmlname": "tolerance",
      "help": "Tolerance of the Gauss-Seidel"
    },
    {
      "name": "d_maxIt",
      "type": "int",
      "xmlname": "maxIterations",
      "help": "Maximum number of iterations of the Gauss-Seidel"
    },
    {
      "name": "d_doCollisionsFirst",
      "type": "bool",
      "xmlname": "doCollisionsFirst",
      "help": "Compute the collisions first (to support penality-based contacts)"
    },
    {
      "name": "d_doubleBuffer",
      "type": "bool",
      "xmlname": "doubleBuffer",
      "help": "Double the buffer dedicated to the constraint problem to make it accessible to another thread"
    },
    {
      "name": "d_scaleTolerance",
      "type": "bool",
      "xmlname": "scaleTolerance",
      "help": "Scale the error tolerance with the number of constraints"
    },
    {
      "name": "d_allVerified",
      "type": "bool",
      "xmlname": "allVerified",
      "help": "All constraints must be verified (each constraint's error < tolerance)"
    },
    {
      "name": "d_sor",
      "type": "SReal",
      "xmlname": "sor",
      "help": "Successive Over Relaxation parameter (0-2)"
    },
    {
      "name": "d_schemeCorrection",
      "type": "bool",
      "xmlname": "schemeCorrection",
      "help": "Apply new scheme where compliance is progressively corrected"
    },
    {
      "name": "d_realTimeCompensation",
      "type": "bool",
      "xmlname": "realTimeCompensation",
      "help": "If the total computational time T < dt, sleep(dt-T)"
    },
    {
      "name": "d_activateSubGraph",
      "type": "bool"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "step",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "dt",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getConstraintProblem",
      "return_type": "ConstraintProblem *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "launchCollisionDetection",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "freeMotion",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        },
        {
          "name": "dt",
          "type": "SReal &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "setConstraintEquations",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "correctiveMotion",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "debugWithContact",
      "return_type": "void",
      "params": [
        {
          "name": "numConstraints",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "writeAndAccumulateAndCountConstraintDirections",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        },
        {
          "name": "numConstraints",
          "type": "unsigned int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getIndividualConstraintViolations",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getIndividualConstraintSolvingProcess",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "context",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeComplianceInConstraintSpace",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computePredictiveForce",
      "return_type": "void",
      "params": [
        {
          "name": "dim",
          "type": "int"
        },
        {
          "name": "force",
          "type": "SReal *"
        },
        {
          "name": "res",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "gaussSeidelConstraint",
      "return_type": "void",
      "params": [
        {
          "name": "dim",
          "type": "int"
        },
        {
          "name": "dfree",
          "type": "SReal *"
        },
        {
          "name": "w",
          "type": "SReal **"
        },
        {
          "name": "force",
          "type": "SReal *"
        },
        {
          "name": "d",
          "type": "SReal *"
        },
        {
          "name": "res",
          "type": "int &"
        },
        {
          "name": "df",
          "type": "SReal *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getCP",
      "return_type": "ConstraintProblem *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `ConstraintAnimationLoop` is an advanced simulation loop manager in the SOFA framework, designed to handle complex constraint resolution and collision detection efficiently. It inherits from `CollisionAnimationLoop`, providing comprehensive management over multiple steps including free motion, collision handling, and constraint solving using iterative methods like Gauss-Seidel.\n\nIt interacts with other components such as collision detection systems, constraint solvers, and mechanical visitors to ensure accurate and efficient simulation of constrained dynamics. The component supports various configurable parameters for tolerance settings (`tolerance`), iteration limits (`maxIterations`), and advanced options like double buffering (`doubleBuffer`) for parallel processing.\n\nThe `ConstraintAnimationLoop` manages the main steps of the simulation cycle, including:\n- **Free Motion**: Propagates free motion based on mechanical equations without constraints.\n- **Collision Detection**: Handles collision detection, either before or after free motion as specified by the user (`doCollisionsFirst`).\n- **Set Constraint Equations**: Builds constraint matrices and resolves individual constraints using specific solvers.\n- **Gauss-Seidel Iteration**: Solves the constraint problem iteratively, scaling tolerance if required (`scaleTolerance`), and verifying all constraints based on user-defined criteria (`allVerified`).\n- **Corrective Motion**: Applies corrective forces to ensure compliance with constraints after solving.\n\nUsers can control detailed behavior through data fields such as `displayTime`, `realTimeCompensation`, and various tolerance parameters. The component is designed for high-fidelity simulations in medical and biomechanical applications, where accurate constraint resolution is critical.",
  "maths": "# Mathematical and Physical Description of ConstraintAnimationLoop\n\n## Overview\nThe `ConstraintAnimationLoop` is an advanced simulation loop manager in the SOFA (Simulation Open Framework Architecture) framework. It is designed to handle complex constraint resolution and collision detection efficiently, providing a robust mechanism for simulating constrained dynamics.\n\n## Key Components\n### Simulation Steps\n1. **Free Motion**: The initial step involves propagating free motion based on mechanical equations without any constraints. This step utilizes mechanical visitors to propagate the state of objects according to their physical properties (mass, inertia, forces).\n2. **Collision Detection**: Detects potential collisions between objects and computes the contact points and normal vectors.\n3. **Set Constraint Equations**: Builds constraint matrices representing the interactions and dependencies among constrained degrees-of-freedom (DoFs). Each constraint is typically represented by a linear or nonlinear equation.\n4. **Gauss-Seidel Iteration**: Solves the system of constraints iteratively, ensuring that each object satisfies its physical constraints while maintaining overall stability and accuracy.\n5. **Corrective Motion**: Applies corrective forces to ensure compliance with constraints after solving.\n\n### Mathematical Formulation\n#### Free Motion Propagation\nThe free motion propagation is governed by the equations of motion for a system of rigid or deformable bodies:\n\\[ m_i \\ddot{\\mathbf{x}}_i = \\mathbf{F}_i^{ext} + \\mathbf{F}_i^{int}, \\]\nwhere $m_i$ is the mass, $\\mathbf{x}_i$ is the position vector of body $i$, and $\\mathbf{F}_i^{ext}$ and $\\mathbf{F}_i^{int}$ are external and internal forces acting on the body.\n\n#### Collision Detection\nCollision detection involves determining if two objects intersect or come into contact. This can be formulated as a geometric problem where the distance between objects is computed using methods such as bounding volume hierarchies (BVH) or GJK algorithm:\n\\[ d(\\mathbf{x}_1, \\mathbf{x}_2) = 0 \\implies \\text{Collision}. \\]\n\n#### Constraint Equations\nConstraints are formulated as linear or nonlinear equations that must be satisfied. For example, a point-to-point constraint can be written as:\n\\[ \\mathbf{c}(\\mathbf{q}) = \\mathbf{x}_i - \\mathbf{x}_j = 0, \\]\nwhere $\\mathbf{q}$ represents the generalized coordinates of the system.\n\n#### Gauss-Seidel Iteration\nThe Gauss-Seidel method is an iterative technique used to solve a system of linear equations. For a system represented by a matrix $W$ and vector $d$, the iteration can be written as:\n\\[ \\mathbf{d}^{k+1} = \\mathbf{dfree} + W^{-1} (\\mathbf{f} - W \\mathbf{d}^k), \\]\nwhere $\\mathbf{d}$ is a vector of displacements, $W$ is the constraint matrix, and $\\mathbf{f}$ represents forces.\n\n#### Corrective Motion\nThe corrective motion step involves applying corrective forces to ensure that all constraints are satisfied. This can be formulated as solving an optimization problem where the forces are minimized while satisfying constraints:\n\\[ \\min_{\\mathbf{f}} \\| \\mathbf{f} \\|^2 \\quad \\text{s.t.} \\quad W \\mathbf{d} = \\mathbf{dfree}. \\]\n\n### Configuration Parameters\n- **Tolerance (`tolerance`)**: Controls the maximum allowable error in constraint resolution.\n- **Max Iterations (`maxIterations`)**: Limits the number of iterations for solving constraints iteratively.\n- **Double Buffering (`doubleBuffer`)**: Enables parallel processing by using a double buffering technique, improving performance.\n- **Real-Time Compensation (`realTimeCompensation`)**: Adjusts simulation to real-time conditions if necessary.\n\n## Physical Interpretation\nThe `ConstraintAnimationLoop` is particularly useful for simulating complex interactions between objects in medical and biomechanical applications. It ensures that physical constraints such as contact, friction, and joint limits are accurately enforced during the simulation. By iteratively solving these constraints using methods like Gauss-Seidel, it provides a numerically stable solution while maintaining high fidelity to the underlying physics.\n\nOverall, this component is designed for simulations where accurate constraint resolution is critical, enabling realistic dynamics in environments with intricate interactions between objects.",
  "abstract": "The `ConstraintAnimationLoop` manages complex constraint resolution and collision detection in SOFA simulations, handling free motion propagation, iterative constraint solving using Gauss-Seidel, and applying corrective forces.",
  "sheet": "# ConstraintAnimationLoop\n\n## Overview\nThe `ConstraintAnimationLoop` is an advanced simulation loop manager that handles complex constraint resolution and collision detection efficiently. It inherits from `CollisionAnimationLoop`, providing comprehensive management over multiple steps including free motion propagation, collision handling, and iterative constraint solving using methods like Gauss-Seidel.\n\n## Parameters and Data\nThe significant data fields exposed by the component control various aspects of its behavior:\n- **displayTime**: Display time for each important step (`bool`)\n- **tolerance**: Tolerance of the Gauss-Seidel method (`SReal`)\n- **maxIterations**: Maximum number of iterations of the Gauss-Seidel method (`int`)\n- **doCollisionsFirst**: Compute collisions first to support penalty-based contacts (`bool`)\n- **doubleBuffer**: Double buffer for constraint problem to make it accessible to another thread (`bool`)\n- **scaleTolerance**: Scale error tolerance with the number of constraints (`bool`)\n- **allVerified**: All constraints must be verified (each constraint's error < tolerance) (`bool`)\n- **sor**: Successive Over Relaxation parameter (0-2) (`SReal`)\n- **schemeCorrection**: Apply new scheme where compliance is progressively corrected (`bool`)\n- **realTimeCompensation**: Adjust simulation to real-time conditions if necessary (`bool`)"
}