Methods

{
  "name": "BaseInteractionForceField",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/BaseInteractionForceField.h",
  "doc": "BaseInteractionForceField is a force field linking several bodies (MechanicalState) together.\n An interaction force field computes forces applied to several simulated\n bodies given their current positions and velocities.\n For implicit integration schemes, it must also compute the derivative\n ( df, given a displacement dx ).",
  "inherits": [
    "BaseForceField"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "toBaseInteractionForceField",
      "return_type": "const BaseInteractionForceField *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechModel1",
      "return_type": "BaseMechanicalState *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMechModel2",
      "return_type": "BaseMechanicalState *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const MechanicalParams *"
        },
        {
          "name": "",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initGnuplot",
      "return_type": "void",
      "params": [
        {
          "name": "path",
          "type": "const int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "exportGnuplot",
      "return_type": "void",
      "params": [
        {
          "name": "time",
          "type": "SReal"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "insertInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeInNode",
      "return_type": "bool",
      "params": [
        {
          "name": "node",
          "type": "objectmodel::BaseNode *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `BaseInteractionForceField` is a fundamental class in the SOFA framework, derived from `BaseForceField`. It serves as an abstract base for interaction force fields that link multiple bodies (MechanicalStates) together. Its primary role is to compute forces acting on these simulated bodies based on their current positions and velocities. Additionally, it provides methods for computing derivatives of forces necessary for implicit integration schemes.\n\nThe `BaseInteractionForceField` interacts with other components by providing virtual functions like `getMechModel1()` and `getMechModel2()`, which retrieve the mechanical states associated with the bodies involved in the interaction. It also includes methods to integrate into a SOFA scene graph (`insertInNode`) and remove from it (`removeInNode`). The class has placeholders for initializing gnuplot file exports (`initGnuplot`) and exporting energy state data (`exportGnuplot`), though these are not fully implemented in the base class.\n\nPractically, users extend `BaseInteractionForceField` to create specific interaction force fields that define how forces should be computed between different bodies. This component is essential for modeling interactions such as contacts or coupling forces in multi-body simulations.",
  "maths": "<maths_md_description>\n\n## Mathematical and Physical Description\n\nThe `BaseInteractionForceField` is an abstract base class in the SOFA framework that serves as a foundation for force fields linking multiple mechanical bodies (MechanicalStates). Its primary role is to compute interaction forces between these bodies based on their current positions and velocities. The class provides essential interfaces for integration into the SOFA scene graph, initialization of gnuplot file exports, and removal from the node structure.\n\n### Force Computation\nThe `BaseInteractionForceField` computes interaction forces between two MechanicalStates, denoted as \\(\\mathbf{q}_1\\) and \\(\\mathbf{q}_2\\), which represent the configurations (positions and velocities) of the respective bodies. These forces are generally expressed as a function of the relative positions and/or velocities:\n\n\begin{equation}\n    \\mathbf{F}(\\mathbf{q}_1, \\mathbf{q}_2) = f(\\mathbf{r}_{12}, \\dot{\\mathbf{r}}_{12})\n\\end{equation}\n\nwhere \\(\\mathbf{r}_{12} = \\mathbf{q}_2 - \\mathbf{q}_1\\) is the relative position vector and \\(\\dot{\\mathbf{r}}_{12}\\) is the relative velocity.\n\n### Derivatives for Implicit Integration\nIn implicit integration schemes, it is necessary to compute the derivatives of these interaction forces with respect to the configuration variables. This derivative can be expressed as a Jacobian matrix:\n\n\begin{equation}\n    \\mathbf{K} = \\frac{\\partial \\mathbf{F}}{\\partial \\mathbf{q}}\n\\end{equation}\n\nThis Jacobian is used to linearize the force model, facilitating the solution of implicit equations during integration.\n\n### Integration into SOFA Scene Graph\nThe `BaseInteractionForceField` class provides methods for integrating into the SOFA scene graph:\n- **insertInNode**: Adds the interaction force field to a specific node in the scene graph.\n- **removeInNode**: Removes the interaction force field from a specified node.\n\n### Initialization and Exporting Data\nThe class includes placeholders for initializing gnuplot file exports (`initGnuplot`) and exporting energy state data (`exportGnuplot`), though these methods are not fully implemented in the base class. These methods can be overridden by derived classes to provide specific implementations.\n\n### Virtual Functions\n- **getMechModel1**: Retrieves the first MechanicalState involved in the interaction force computation.\n- **getMechModel2**: Retrieves the second MechanicalState involved in the interaction force computation.\n\n## Conclusion\nThe `BaseInteractionForceField` class is crucial for defining and computing forces between multiple mechanical bodies within the SOFA framework. It provides essential interfaces for integration into the scene graph, initialization of data exports, and retrieval of MechanicalStates. Derived classes extend this base to define specific interaction models, enabling multi-body simulations with diverse force interactions.",
  "abstract": "The `BaseInteractionForceField` computes interaction forces between multiple mechanical bodies (MechanicalStates) based on their positions and velocities, providing essential interfaces for scene graph integration and gnuplot file exports.",
  "sheet": "# BaseInteractionForceField\n\n## Overview\n\nThe `BaseInteractionForceField` is an abstract base class in the SOFA framework that serves as a foundation for force fields linking multiple mechanical bodies (MechanicalStates). Its primary role is to compute interaction forces between these bodies based on their current positions and velocities. The class provides essential interfaces for integration into the SOFA scene graph, initialization of gnuplot file exports, and removal from the node structure.\n\n## Mathematical Model\n\nThe `BaseInteractionForceField` computes interaction forces between two MechanicalStates, denoted as \\(\\mathbf{q}_1\\) and \\(\\mathbf{q}_2\\), which represent the configurations (positions and velocities) of the respective bodies. These forces are generally expressed as a function of the relative positions and/or velocities:\n\n\\[ \n    \\mathbf{F}(\\mathbf{q}_1, \\mathbf{q}_2) = f(\\mathbf{r}_{12}, \\dot{\\mathbf{r}}_{12})\n\\]\n\nwhere \\(\\mathbf{r}_{12} = \\mathbf{q}_2 - \\mathbf{q}_1\\) is the relative position vector and \\(\\dot{\\mathbf{r}}_{12}\\) is the relative velocity.\n\nIn implicit integration schemes, it is necessary to compute the derivatives of these interaction forces with respect to the configuration variables. This derivative can be expressed as a Jacobian matrix:\n\n\\[ \n    \\mathbf{K} = \\frac{\\partial \\mathbf{F}}{\\partial \\mathbf{q}}\n\\]\n\nThis Jacobian is used to linearize the force model, facilitating the solution of implicit equations during integration.\n\n## Dependencies and Connections\n\nThe `BaseInteractionForceField` interacts with other components by providing virtual functions like `getMechModel1()` and `getMechModel2()`, which retrieve the mechanical states associated with the bodies involved in the interaction. It also includes methods to integrate into a SOFA scene graph (`insertInNode`) and remove from it (`removeInNode`). The class has placeholders for initializing gnuplot file exports (`initGnuplot`) and exporting energy state data (`exportGnuplot`), though these are not fully implemented in the base class."
}