{
  "name": "ForceField",
  "main": {
    "name": "ForceField",
    "namespace": "sofa::core::behavior",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/behavior/ForceField.h",
    "doc": "Component computing forces within a simulated body.\n This class defines the abstract API common to force fields using a\n given type of DOFs.\n A force field computes forces applied to one simulated body\n given its current position and velocity.\n For implicit integration schemes, it must also compute the derivative\n ( df, given a displacement dx ).",
    "inherits": [
      "BaseForceField",
      "SingleStateAccessor"
    ],
    "templates": [
      "sofa::defaulttype::Rigid2Types",
      "sofa::defaulttype::Rigid3Types",
      "sofa::defaulttype::Vec3Types"
    ],
    "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": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          },
          {
            "name": "f",
            "type": "DataVecDeriv &"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          },
          {
            "name": "v",
            "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": "df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dx",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addClambda",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "lambda",
            "type": "const DataVecDeriv &"
          },
          {
            "name": "cFactor",
            "type": "SReal"
          }
        ],
        "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": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "matrix",
            "type": "const sofa::core::behavior::MultiMatrixAccessor *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "kFact",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addBToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "matrix",
            "type": "const sofa::core::behavior::MultiMatrixAccessor *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "bm",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "offset",
            "type": "unsigned int"
          },
          {
            "name": "nodeIndex",
            "type": "const IndexArray &"
          },
          {
            "name": "em",
            "type": "const ElementMat &"
          },
          {
            "name": "scale",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addBToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "bFact",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "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"
      }
    ]
  },
  "desc": {
    "description": "The `ForceField` is an abstract class in the SOFA framework, designed to compute forces acting on simulated bodies using given degrees of freedom (DOFs). It inherits from `BaseForceField` and `SingleStateAccessor`, providing a common API for force computation across different DOF types. The role of `ForceField` includes calculating forces based on current position and velocity states, contributing to stiffness and damping matrices, and computing potential energy associated with the system.\n\n**Interactions:**\n- **Mechanical State Interaction**: It interacts with the mechanical state through methods like `addForce`, `addDForce`, and `getPotentialEnergy`, which utilize MechanicalParams to retrieve position, velocity, and displacement data from the mechanical state.\n- **Matrix Operations**: Methods such as `addKToMatrix` and `addBToMatrix` contribute to stiffness and damping matrices used in implicit time integration schemes.\n\n**Usage Guidance:**\n- Implementations must provide specific functionality for computing forces through overridden methods like `addForce`, `addDForce`, and `getPotentialEnergy`. These are called by SOFA's main simulation loop to update the mechanical state at each step. For implicit integration, force derivatives (stiffness contributions) must be provided as well.\n- The component supports different data types via template instantiation, including Vec3Types, Rigid2Types, and others."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the ForceField Component in SOFA\n\n## Overview\nThe `ForceField` class is an abstract template-based class within the Simulation Open-Framework Architecture (SOFA). It serves as a foundational interface for force computation in simulations involving various degrees-of-freedom (DOFs) types. The primary role of this class is to provide methods and mechanisms that enable the calculation, application, and integration of forces acting on simulated bodies.\n\n## Key Components and Methods\n### 1. **Force Calculation**\nThe core functionality involves computing forces based on the current state of a mechanical system, specifically its position and velocity. This is achieved through methods such as `addForce`, which takes into account the MechanicalParams (a structure holding parameters like damping factors) to compute the force contributions.\n\n#### Mathematical Formulation:\n- **Position** (\textbf{x}): Current position vector of the body in the simulation space.\n- **Velocity** (\textbf{v}): Velocity vector indicating how the position changes over time.\n- **Force** (\textbf{F}): Force acting on the body, derived from a potential energy function or dynamic interactions.\n\nThe `addForce` method can be represented as:\n\\[\textbf{F} = f(\\textbf{x}, \\textbf{v})\n\\]\nwhere \\(f\\) is some functional form that depends on the specific implementation of force fields like spring forces, gravity, or user-defined forces.\n\n### 2. **Derivative Calculation (Stiffness and Damping Contributions)**\nThe `ForceField` class also supports the computation of derivatives for implicit time integration schemes. This includes:\n- **addDForce**: Computes the derivative of force with respect to displacement (\textbf{dx}) to account for stiffness contributions.\n\n#### Mathematical Formulation:\n- **Stiffness Matrix** (\\mathbf{K}): Represents how forces change in response to small displacements.\n- **Displacement** (\textbf{dx}): Small perturbation or change in position.\n\nThe `addDForce` method can be represented as:\n\\[\frac{d\\textbf{F}}{d\\textbf{x}} = \\mathbf{K}\n\\]\nwhere the stiffness matrix \\(\\mathbf{K}\\) is assembled and used in implicit integration schemes to solve for the system state.\n\n### 3. **Matrix Contributions**\nThe class supports contributions to matrices used in solving differential equations governing the mechanical behavior of systems, such as stiffness (\\(\\mathbf{K}\\)) and damping (\\(\\mathbf{B}\\)) matrices.\n- **addKToMatrix**: Assembles the stiffness matrix \\(\\mathbf{K}\\).\n- **addBToMatrix**: Assembles the damping matrix \\(\\mathbf{B}\\).\n\n#### Mathematical Formulation:\n- **Stiffness Matrix Assembly** (\\(\\mathbf{K}\\)): The `addKToMatrix` method contributes to the assembly of the global stiffness matrix used in solving linear systems.\n- **Damping Matrix Assembly** (\\(\\mathbf{B}\\)): The `addBToMatrix` method contributes to the damping matrix, representing viscous forces.\n\n### 4. **Potential Energy Calculation**\nThe class supports the calculation of potential energy associated with the system through methods like `getPotentialEnergy`, which is crucial for energy-based simulation techniques and stability analysis.\n\n#### Mathematical Formulation:\n- **Potential Energy** (\\(U\\)): A scalar function representing stored energy in the system, often derived from force fields.\n\nThe potential energy can be expressed as:\n\\[U = U(\\textbf{x})\n\\]\nwhere \\(\\textbf{x}\\) is the position vector.\n\n## Implementation Guidance\nImplementations of `ForceField` must provide specific methods for computing forces, derivatives (for stiffness and damping), and potential energy contributions. These implementations are then integrated into SOFA's simulation framework to update the mechanical state at each time step. The template-based design allows for flexibility in handling different DOF types such as vector types (`Vec3Types`, `Rigid2Types`) and others.\n\n## Conclusion\nThe `ForceField` class provides a robust interface for force computation within SOFA, enabling simulations to accurately model complex mechanical behaviors by integrating various forces, stiffness contributions, and potential energy calculations. This abstraction layer ensures that different force fields can be easily integrated into the simulation pipeline while maintaining computational efficiency and flexibility."
  },
  "summary": {
    "abstract": "The `ForceField` component computes forces acting on simulated bodies using given degrees of freedom (DOFs) and provides methods for force calculation, derivative computation, stiffness/damping matrix assembly, and potential energy evaluation.",
    "sheet": "# ForceField\n\n## Overview\nThe `ForceField` is an abstract class in the SOFA framework that defines a common API for computing forces within simulated bodies using given degrees of freedom (DOFs). It inherits from `BaseForceField` and `SingleStateAccessor`, providing methods to compute forces, derivatives (stiffness contributions), potential energy, and matrix assembly operations.\n\n## Mathematical Model\n### Force Calculation\nThe core functionality involves computing forces based on the current state of a mechanical system, specifically its position (\textbf{x}) and velocity (\textbf{v}). The `addForce` method can be represented as:\n\\[ \\textbf{F} = f(\\textbf{x}, \\textbf{v}) \\]\nwhere \\(f\\) is some functional form that depends on the specific implementation of force fields like spring forces, gravity, or user-defined forces.\n\n### Derivative Calculation (Stiffness and Damping Contributions)\nThe `ForceField` class supports the computation of derivatives for implicit time integration schemes. This includes:\n- **addDForce**: Computes the derivative of force with respect to displacement (\textbf{dx}) to account for stiffness contributions.\n\\[ \\frac{d\\textbf{F}}{d\\textbf{x}} = \\mathbf{K} \\]\nwhere the stiffness matrix \\(\\mathbf{K}\\) is assembled and used in implicit integration schemes to solve for the system state.\n\n### Matrix Contributions\nThe class supports contributions to matrices used in solving differential equations governing the mechanical behavior of systems, such as stiffness (\\(\\mathbf{K}\\)) and damping (\\(\\mathbf{B}\\)) matrices.\n- **addKToMatrix**: Assembles the stiffness matrix \\(\\mathbf{K}\\).\n- **addBToMatrix**: Assembles the damping matrix \\(\\mathbf{B}\\).\n\n### Potential Energy Calculation\nThe class supports the calculation of potential energy associated with the system through methods like `getPotentialEnergy`, which is crucial for energy-based simulation techniques and stability analysis.\n\\[ U = U(\\textbf{x}) \\]\nwhere \\(\\textbf{x}\\) is the position vector."
  }
}