Methods

{
  "name": "MixedInteractionForceField",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/MixedInteractionForceField.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::Rigid2Types",
    "sofa::defaulttype::Rigid2Types, sofa::defaulttype::Vec2Types",
    "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Rigid3Types, sofa::defaulttype::Vec3Types",
    "sofa::defaulttype::Vec1Types, sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec1Types, sofa::defaulttype::Vec3Types",
    "sofa::defaulttype::Vec2Types, sofa::defaulttype::Rigid2Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "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": "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": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        }
      ],
      "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": "DataVecDeriv1 &"
        },
        {
          "name": "f2",
          "type": "DataVecDeriv2 &"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord1 &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord2 &"
        },
        {
          "name": "v1",
          "type": "const DataVecDeriv1 &"
        },
        {
          "name": "v2",
          "type": "const DataVecDeriv2 &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "df1",
          "type": "DataVecDeriv1 &"
        },
        {
          "name": "df2",
          "type": "DataVecDeriv2 &"
        },
        {
          "name": "dx1",
          "type": "const DataVecDeriv1 &"
        },
        {
          "name": "dx2",
          "type": "const DataVecDeriv2 &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const MechanicalParams *"
        },
        {
          "name": "x1",
          "type": "const DataVecCoord1 &"
        },
        {
          "name": "x2",
          "type": "const DataVecCoord2 &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "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"
    }
  ],
  "description": "The `MixedInteractionForceField` is an abstract base class in the SOFA (Simulation Open Framework Architecture) framework that serves as a template for implementing force fields interacting between two different types of mechanical models, each potentially using distinct vector types.",
  "parameters": [],
  "description_details": [
    "This component acts as an interface for defining interactions where one model might use 3D vectors while another uses rigid body representations or other custom vector types."
  ],
  "key_functions": [
    {
      "name": "addForce",
      "description": "Adds the computed force to a given force vector based on current position and velocity states. Abstract method that must be implemented by derived classes."
    },
    {
      "name": "addDForce",
      "description": "Computes and adds the derivative of the forces with respect to small displacements in position and velocity. Also an abstract method requiring implementation in derived classes."
    },
    {
      "name": "getPotentialEnergy",
      "description": "Calculates the potential energy associated with this force field, used for estimating system's total energy in some stabilization techniques. Like previous methods, it is abstract and must be defined by subclasses."
    }
  ],
  "use_cases": [
    "Implementing complex interaction dynamics between different mechanical models.",
    "Creating custom force fields where one model represents deformable objects and another represents rigid bodies."
  ],
  "notes": [
    "This class extends from `ForceField` and provides a mechanism for mixed interactions between diverse types of mechanical models in SOFA simulations.",
    "The template parameters allow customization based on the specific vector types used by the interacting models, enabling flexibility across various simulation scenarios."
  ],
  "maths": "The `MixedInteractionForceField` is an abstract base class in the SOFA framework designed for computing forces between two different types of mechanical models. This class provides a common API for force fields that interact with two bodies using potentially different types of degrees-of-freedom (DOFs).\n\n### Governing Equations and Operators:\n\n#### Force Computation\nThe primary function `addForce` computes the internal force contributions between two interacting bodies, updating their respective force vectors. The generalized form can be expressed as:\n\\[ f_i = B_i v + K_i x \\]\nwhere $f_i$ is the force vector for body $i$, $B_i$ and $K_i$ are matrices representing damping and stiffness contributions respectively, $v$ represents velocities, and $x$ denotes displacements.\n\nThe method `addForce` retrieves the necessary states from the associated mechanical models (position, velocity) and calls an internal implementation to compute these forces.\n\n#### Derivative of Force\nFor time integration schemes requiring derivatives of force with respect to displacement, `addDForce` computes:\n\\[ df_i = K_{i} dx \\]\nThe derivative $df$ is computed by providing small displacements $dx$ as input. This method ensures consistency in the numerical differentiation step during implicit integration.\n\n#### Potential Energy\nThe potential energy associated with the interaction force field can be retrieved using `getPotentialEnergy`. The potential energy $V(x_1, x_2)$ represents the stored mechanical energy due to deformations and interactions between bodies 1 and 2. This is expressed as:\n\\[ V(x_1, x_2) \\]\nThe method retrieves the necessary position vectors from the associated mechanical models and calls an internal implementation to compute this potential.\n\n### Constitutive or Kinematic Laws Involved:\nThis component abstracts over various specific constitutive laws and kinematics. The actual computation of forces, derivatives, and potential energy depends on derived classes that implement these methods according to specific material properties (e.g., elastic, viscoelastic) and deformation measures.\n\n### Role in the Global FEM Pipeline:\nThe `MixedInteractionForceField` plays a crucial role during assembly by contributing internal force terms $f_{int}$, which are essential for constructing the nonlinear residual $R$ in implicit time integration schemes. It also participates in computing derivatives of forces, necessary for Jacobian formation and linearization within Newton-Raphson iterations.\n\n### Numerical Methods or Discretization Choices:\nThe numerical methods used by derived classes implementing `MixedInteractionForceField` can vary based on the specific force field type (e.g., linear elastic, corotational). The interaction forces are typically discretized using FEM principles and assembled into global system matrices and vectors.\n\n### Broad Variational/Lagrangian Mechanics Framework:\nThe abstract class aligns with variational mechanics by defining operations that contribute to the weak form of governing equations. Derived classes must ensure consistency with Lagrangian formulations, where internal forces arise from potential energy gradients or constitutive laws defined in a consistent manner.",
  "abstract": "`MixedInteractionForceField` is an abstract base class in SOFA that defines the API for computing forces between two different types of mechanical models using potentially distinct vector types.",
  "sheet": "# MixedInteractionForceField\n\n## Overview\nThe `MixedInteractionForceField` is an abstract base class in the SOFA framework designed to compute forces between two interacting bodies with potentially different degrees-of-freedom (DOFs). It provides a common API for force fields that interact with two distinct mechanical models.\n\n## Mathematical Model\n### Force Computation\nThe primary function `addForce` computes the internal force contributions between two interacting bodies, updating their respective force vectors. The generalized form can be expressed as:\n\\[ f_i = B_i v + K_i x \\]\nwhere $f_i$ is the force vector for body $i$, $B_i$ and $K_i$ are matrices representing damping and stiffness contributions respectively, $v$ represents velocities, and $x$ denotes displacements.\n\n### Derivative of Force\nFor time integration schemes requiring derivatives of force with respect to displacement, `addDForce` computes:\n\\[ df_i = K_{i} dx \\]\nThe derivative $df$ is computed by providing small displacements $dx$ as input. This method ensures consistency in the numerical differentiation step during implicit integration.\n\n### Potential Energy\nThe potential energy associated with the interaction force field can be retrieved using `getPotentialEnergy`. The potential energy $V(x_1, x_2)$ represents the stored mechanical energy due to deformations and interactions between bodies 1 and 2. This is expressed as:\n\\[ V(x_1, x_2) \\]\nThe method retrieves the necessary position vectors from the associated mechanical models and calls an internal implementation to compute this potential.\n\n## Practical Notes\nDerived classes implementing `MixedInteractionForceField` must ensure consistency with Lagrangian formulations and provide specific implementations for force computation, derivatives of forces, and potential energy. The numerical methods used can vary based on the specific force field type (e.g., linear elastic, corotational)."
}