{
  "name": "BaseForceField",
  "main": {
    "name": "BaseForceField",
    "namespace": "sofa::core::behavior",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/behavior/BaseForceField.h",
    "doc": "Component computing forces within simulated bodies.\n This class define the abstract API common to all force fields.\n A force field computes forces applied to one or more simulated body\n given its current position and velocity.\n Forces can be internal to a given body (attached to one MechanicalState,\n see the ForceField class), or link several bodies together (such as contact\n forces, see the InteractionForceField class).\n For implicit integration schemes, it must also compute the derivative\n ( df, given a displacement dx ).",
    "inherits": [],
    "templates": [],
    "data_fields": [
      {
        "name": "rayleighStiffness",
        "type": "SReal",
        "xmlname": "rayleighStiffness",
        "help": "Rayleigh damping - stiffness matrix coefficient"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "toBaseForceField",
        "return_type": "const BaseForceField *",
        "params": [],
        "is_virtual": true,
        "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": 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": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addMBKdx",
        "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": 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": true,
        "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": "addMBKToMatrix",
        "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": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "StiffnessMatrix *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildDampingMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "DampingMatrix *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getComplianceMatrix",
        "return_type": "const sofa::linearalgebra::BaseMatrix *",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addClambda",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const MechanicalParams *"
          },
          {
            "name": "",
            "type": "MultiVecDerivId"
          },
          {
            "name": "",
            "type": "MultiVecDerivId"
          },
          {
            "name": "",
            "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"
      }
    ]
  },
  "desc": {
    "description": "The `BaseForceField` class in the SOFA framework is an abstract base class that defines the API common to all force fields. Its role is to compute forces applied to simulated bodies based on their current position and velocity states. Force fields can be internal to a single body or link multiple bodies together, such as contact forces.\n\nFor implicit integration schemes, `BaseForceField` must also compute the derivative of forces with respect to displacements. This class provides pure virtual methods for adding force contributions (`addForce`, `addDForce`) and potential energy computation (`getPotentialEnergy`). It also includes methods for building stiffness and damping matrices (`buildStiffnessMatrix`, `buildDampingMatrix`) and accumulating matrix contributions (`addKToMatrix`, `addBToMatrix`, `addMBKToMatrix`).\n\nThe class contains a data field `rayleighStiffness` which represents the Rayleigh damping coefficient for stiffness.\n\nInteractions with other components are achieved through mechanical parameters (e.g., mass, damping, and stiffness factors) passed to these methods. The component integrates seamlessly into SOFA's scene graph architecture by providing methods for insertion (`insertInNode`) and removal (`removeInNode`) from a `BaseNode` in the simulation hierarchy."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of BaseForceField in the SOFA Framework\n\n## Overview\nThe `BaseForceField` class is an abstract base class that defines methods to compute forces acting on simulated bodies in a physics-based simulation. These computations are based on principles from classical mechanics, including Newton's laws of motion, conservation of energy, and possibly more advanced models such as continuum mechanics.\n\n## Core Mathematical Concepts\n1. **Forces**: Forces are central to the `BaseForceField` class, representing interactions between bodies or internal forces within a body.\n   - In classical mechanics, force is described by Newton's second law: \\( F = m \frac{d^2x}{dt^2} \\), where \\(F\\) is the net force acting on an object of mass \\(m\\), and \\(\frac{d^2x}{dt^2}\\) is its acceleration.\n   - Forces can be conservative (potential energy-based, e.g., gravity) or non-conservative (e.g., friction).\n\n2. **Potential Energy**: The `BaseForceField` class includes methods to compute potential energy, which is a scalar function that represents the stored mechanical energy of a system due to its configuration.\n   - For conservative forces, the force can be derived from the gradient of the potential energy: \\( F = -\nabla U \\).\n\n3. **Stiffness and Damping**: These are material properties that define how bodies respond to external forces and their own deformation.\n   - Stiffness is related to Hooke's law for springs, where force is proportional to the displacement: \\( F = kx \\), with \\(k\\) as the stiffness constant.\n   - Damping represents energy dissipation, often modeled by a damping coefficient \\(c\\): \\(F_d = c \frac{dx}{dt}\\).\n\n4. **Matrix Representations**: The class includes methods to build and accumulate contributions to matrices that represent linear systems (e.g., stiffness matrix, damping matrix).\n   - Stiffness Matrix: Represents the relationship between displacements and forces in a system of equations: \\( K \boldsymbol{u} = \boldsymbol{f} \\), where \\(K\\) is the stiffness matrix, \\(\boldsymbol{u}\\) are displacements, and \\(\boldsymbol{f}\\) are applied forces.\n   - Damping Matrix: Represents energy dissipation in a similar linear system form.\n\n## Methods\n1. **addForce**: Adds force contributions to the simulation based on current states (position, velocity).\n2. **addDForce**: Computes the derivative of forces with respect to displacements for implicit integration schemes.\n3. **getPotentialEnergy**: Computes the potential energy stored in the system due to its configuration.\n4. **buildStiffnessMatrix**: Constructs a stiffness matrix representing the mechanical properties and interactions within the simulated bodies.\n5. **buildDampingMatrix**: Constructs a damping matrix representing the dissipative forces in the system.\n6. **addKToMatrix**: Accumulates contributions to the stiffness matrix from individual force fields.\n7. **addBToMatrix**: Accumulates contributions to the damping matrix from individual force fields.\n\n## Parameters and Data Fields\n- `rayleighStiffness`: Represents the Rayleigh damping coefficient, which is a linear combination of mass and stiffness matrices to model viscoelastic materials: \\( C = \beta M + \frac{\beta}{\rho} K \\).\n  - Here, \\(\beta\\) is the Rayleigh damping coefficient, \\(M\\) is the mass matrix, and \\(K\\) is the stiffness matrix.\n\n## Physical Interpretation\n- The `BaseForceField` class models a wide range of physical phenomena including elastic deformation (through stiffness), energy dissipation (damping), and various types of forces like gravity or contact forces.\n- In simulations, these components are crucial for realistic behavior, ensuring that the simulated bodies move and interact in ways consistent with physical laws.\n\n## Conclusion\nThe `BaseForceField` class is foundational to physics-based simulation within SOFA, leveraging classical mechanics principles and linear algebra concepts to accurately model mechanical systems. Its methods and data fields enable the integration of diverse force models into a unified simulation framework."
  },
  "summary": {
    "abstract": "`BaseForceField` defines an abstract API for computing forces within simulated bodies in SOFA, including methods to compute force derivatives, potential energy, and matrix contributions (stiffness and damping).",
    "sheet": "\n# BaseForceField\n\n## Overview\nThe `BaseForceField` class is an abstract base class that defines the API common to all force fields in SOFA. It computes forces applied to simulated bodies based on their current position and velocity states, and it supports both internal and inter-body forces. The class includes methods for computing derivatives of forces (for implicit integration schemes), potential energy, and matrix contributions such as stiffness and damping.\n\n## Mathematical Model\nThe `BaseForceField` class is grounded in classical mechanics principles:\n- **Forces**: Forces are computed based on Newton's second law: \\( F = m \frac{d^2x}{dt^2} \\), where \\(F\\) is the net force, and \\(\frac{d^2x}{dt^2}\\) is acceleration.\n- **Potential Energy**: Potential energy \\(U\\) can be derived from conservative forces: \\( F = -\nabla U \\).\n- **Stiffness Matrix**: Represents the relationship between displacements and forces: \\( K \boldsymbol{u} = \boldsymbol{f} \\), where \\(K\\) is the stiffness matrix, \\(\boldsymbol{u}\\) are displacements, and \\(\boldsymbol{f}\\) are applied forces.\n- **Damping Matrix**: Represents energy dissipation: \\( C = \beta M + \frac{\beta}{\rho} K \\), where \\(\beta\\) is the Rayleigh damping coefficient, \\(M\\) is the mass matrix, and \\(K\\) is the stiffness matrix.\n\n## Parameters and Data\n- **rayleighStiffness**: Represents the Rayleigh damping coefficient (type: `SReal`).\n\n## Dependencies and Connections\n`BaseForceField` typically requires mechanical parameters such as position, velocity, mass, and stiffness factors. It fits into SOFA's scene graph by providing methods for insertion (`insertInNode`) and removal (`removeInNode`) from a `BaseNode`. The class interacts with other components through the API to accumulate force contributions and matrix entries."
  }
}