Mathematical Description of PairInteractionForceField

Methods

{
  "name": "PairInteractionForceField",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/PairInteractionForceField.h",
  "doc": "Component computing forces between a pair of simulated body.\n This class define the abstract API common to interaction force fields\n between a pair of bodies using a given type of DOFs.",
  "inherits": [
    "BaseInteractionForceField"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec6Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setPathObject1",
      "return_type": "void",
      "params": [
        {
          "name": "path",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPathObject2",
      "return_type": "void",
      "params": [
        {
          "name": "path",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPathObject1",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPathObject2",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "fId",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "f1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "f2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "v2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "dfId",
          "type": "MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "df1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "df2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "dx2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *"
        },
        {
          "name": "context",
          "type": "objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "shortName",
      "return_type": "int",
      "params": [
        {
          "name": "ptr",
          "type": "const T *"
        },
        {
          "name": "arg",
          "type": "objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    }
  ],
  "component": {
    "name": "PairInteractionForceField",
    "description": "The `PairInteractionForceField` is an abstract base class in the SOFA (Simulation Open Framework Architecture) framework, used to define force fields that act between two mechanical states or objects. This class provides a template for creating specific interaction force fields that can be applied to pairs of bodies in simulations.",
    "key_features": [
      "The `PairInteractionForceField` inherits from base classes and integrates with SOFA's mechanical modeling system.",
      "It defines methods for computing forces, damping (velocity-related forces), and potential energy between two interacting objects or states.",
      "The class template is designed to handle various data types (`Vec3`, `Rigid`, etc.) used in the simulation of different physical properties.",
      "Methods such as `addForce` and `addDForce` are implemented to calculate force interactions and their derivatives, respectively, based on the current state and velocity of the objects involved.",
      "The method `getPotentialEnergy` calculates the potential energy associated with the interaction between the two states or objects.",
      "Included static methods like `canCreate`, `create`, and `shortName` facilitate component creation and naming conventions within the SOFA framework."
    ],
    "usage_context": [
      "This class is typically extended by concrete implementations that define specific interactions, such as spring forces, collision responses, or other physical phenomena between pairs of objects in a simulation.",
      "It can be used in a wide range of applications including biomechanics, robotics, and general-purpose physics simulations where detailed interaction dynamics are required."
    ],
    "implementation_details": [
      "The class is implemented using C++ templates to support various data types relevant to SOFA's modeling capabilities.",
      "It relies on the SOFA framework's `MechanicalParams` structure to manage parameters related to mechanical computations.",
      "Inheritance from multiple base classes (`Inherit1`, `Inherit2`) allows it to integrate seamlessly with other components of the SOFA framework.",
      "Error handling is included in methods like `addForce` and `addDForce` to ensure that both interacting states are properly initialized before computation."
    ],
    "example": [
      "To create a specific interaction force field, you would typically subclass `PairInteractionForceField`, for example:\n```cpp\n#include <sofa/core/behavior/PairInteractionForceField.h>\nclass MySpringForceField : public sofa::core::behavior::PairInteractionForceField<defaulttype::Vec3Types> {\npublic:\n    MySpringForceField(...) {...}\n};\n```\nThe subclass would then define the actual force computation logic in methods like `addForce` and `getPotentialEnergy`, tailored to its specific interaction model."
    ],
    "limitations": [
      "The abstract nature of this class means it must be specialized for particular interactions before use.",
      "It assumes the existence of two distinct mechanical states or objects that interact, which may not always fit complex multi-body scenarios.",
      "As an SOFA-specific component, its utility is primarily within simulations built using this framework."
    ]
  },
  "maths": "<maths_md_description>\n\n# Mathematical Description of PairInteractionForceField\n\n## Governing Equations and Operators\nThe `PairInteractionForceField` component in the SOFA framework is responsible for computing forces between a pair of simulated bodies. It contributes to the force computation by adding the internal force vector $f$ as well as its derivative $df$. The forces computed can be represented as:\n$$\nf += B v + K x\n$$\nwhere,\n- $B$: damping matrix\n- $K$: stiffness matrix\n- $v$: velocity vector\n- $x$: position vector\n\nAdditionally, the force derivative is computed using the following equation:\n$$\ndf += kFactor \\cdot K dx + bFactor \\cdot B dx\n$$\nwhere,\n- $kFactor$ and $bFactor$ are scalar coefficients\n- $dx$: displacement vector\n\n## Constitutive or Kinematic Laws Involved\nThe `PairInteractionForceField` does not specify any particular constitutive or kinematic laws by itself. Instead, it is an abstract base class that defines the API for specific interaction force fields between pairs of bodies using a given type of degrees-of-freedom (DOFs). The actual constitutive models would be implemented in derived classes.\n\n## Role in the Global FEM Pipeline\n- **Assembly Phase**: `PairInteractionForceField` contributes to assembling internal forces $f$ and its derivatives $df$ between two bodies based on their current position, velocity, and displacement states. These contributions are added to the global force vector during the assembly phase.\n- **Nonlinear Resolution**: The component participates in nonlinear resolution by providing necessary force values required for solving the nonlinear system of equations.\n\n## Numerical Methods or Discretization Choices Encoded\nThe numerical methods and discretizations are not explicitly defined within `PairInteractionForceField`, as it serves more as an abstract base class. Specific implementations would define their own methods, such as how to compute forces based on different constitutive laws (e.g., linear elasticity, hyperelasticity).\n\n## Fit into the Broader Variational / Lagrangian Mechanics Framework\nWithin the broader variational and Lagrangian mechanics framework, `PairInteractionForceField` plays a role in computing the internal forces that contribute to the equations of motion. It does this by providing necessary force computations which are incorporated into the overall simulation pipeline.\n\n</maths_md_description>",
  "abstract": "`PairInteractionForceField` computes forces between pairs of simulated bodies in SOFA, defining the API for force computation without specifying particular constitutive laws or numerical methods.",
  "sheet": "# PairInteractionForceField\n\n## Overview\nThe `PairInteractionForceField` is an abstract base class that defines the API for computing forces between a pair of simulated bodies using a given type of degrees-of-freedom (DOFs). It does not specify particular constitutive laws or numerical methods, leaving these details to derived classes.\n\n## Mathematical Model\nThe component contributes to force computation by adding internal forces and their derivatives. The governing equations for the internal forces $f$ and their derivatives $df$ are given by:\n$$\nf += B v + K x\n$$\nwhere,\n- $B$: damping matrix\n- $K$: stiffness matrix\n- $v$: velocity vector\n- $x$: position vector\n\nThe derivative of the force is computed as follows:\n$$\ndf += kFactor \\cdot K dx + bFactor \\cdot B dx\n$$\nwhere,\n- $kFactor$ and $bFactor$ are scalar coefficients\n- $dx$: displacement vector"
}