{
  "name": "BaseTetraForceField",
  "main": {
    "name": "BaseTetraForceField",
    "namespace": "sofa::component",
    "module": "SofaTestPlugin",
    "include": "forcefield/BaseTetraForceField.h",
    "doc": "General ForceField for tetrahedral meshes",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_fiberDirections",
        "type": "VecCoord",
        "xmlname": "fiberDirections",
        "help": "Fiber direction in each tetrahedron"
      }
    ],
    "links": [
      {
        "name": "l_topology",
        "target": "BaseMeshTopology",
        "kind": "single",
        "xmlname": "topology",
        "help": "Link to topology"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "f",
            "type": "DataVecDeriv &"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          },
          {
            "name": "v",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addDForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dx",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "core::behavior::StiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildDampingMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::behavior::DampingMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "createTetrahedronRestInformation",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "int"
          },
          {
            "name": "t",
            "type": "TetrahedronRestInformation &"
          },
          {
            "name": "",
            "type": "const Tetrahedron &"
          },
          {
            "name": "",
            "type": "const int &"
          },
          {
            "name": "",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeDeformationGradient",
        "return_type": "Matrix3",
        "params": [
          {
            "name": "positions",
            "type": "const VecCoord &"
          },
          {
            "name": "tetra",
            "type": "const Tetrahedron &"
          },
          {
            "name": "shapeVector",
            "type": "const Coord[4]"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeFiberDyadicProduct",
        "return_type": "Matrix3",
        "params": [
          {
            "name": "fiber",
            "type": "const Coord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BaseTetraForceField` component in SOFA (Simulation Open Framework Architecture) is designed to handle force computations for tetrahedral meshes, which are commonly used in simulations involving deformable objects. This component provides the foundational structure and methods necessary for implementing various types of forces specific to tetrahedron-based geometries.",
    "details": {
      "purpose": "This class serves as a base template for more specialized force fields that operate on tetrahedral meshes. It includes essential functionalities such as deformation gradient computation, potential energy calculation, and setup procedures for the rest state configurations.",
      "methods_and_attributes": {
        "computeDeformationGradient": "Calculates the deformation gradient (F = ∇x) of a tetrahedron given its vertices' positions and shape vectors. This is crucial for determining how much and in what way the tetrahedron has deformed from its rest state.",
        "addDForce": "This method would be used to add damping forces to nodes based on their velocities (dx). It's currently marked as unused but indicates potential for implementing velocity-dependent force calculations, such as Rayleigh damping.",
        "getPotentialEnergy": "Returns the potential energy associated with the tetrahedron. This function is placeholder and always returns 0. In derived classes, it can be implemented to compute actual potential energies based on specific force models.",
        "buildStiffnessMatrix": "Constructs the stiffness matrix for a given tetrahedron, which represents how forces are distributed within the structure due to deformations. This method was previously called 'addKToMatrix' and is used in finite element analysis frameworks.",
        "createTetrahedronRestInformation": "Sets up initial (rest) state information for a tetrahedron including volume, shape vectors, fiber directions, and contraction tensors. The rest configuration is critical for calculating deformations relative to an undeformed state."
      },
      "implementation_details": {
        "template_class": "The component is implemented as a template class `BaseTetraForceField<DataTypes>` which allows it to work with different types of data (e.g., Vec3, Real) making the implementation flexible and reusable.",
        "registration_function": "A registration function `registerBaseTetraForceField` is provided for integrating this component into SOFA's object factory system. This function registers a specialization of the template class with specific types (`Vec3Types`)."
      }
    }
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the BaseTetraForceField Component\n\n### Overview\nThe `BaseTetraForceField` is a general force field designed to handle tetrahedral meshes in simulations involving deformable objects. This component provides foundational structures and methods necessary for implementing various forces specific to tetrahedron-based geometries. It computes forces, potential energy, and stiffness matrices related to the deformation of these tetrahedral elements.\n\n### Key Components and Definitions\n#### Tetrahedron Shape Vectors\nThe shape vectors are critical in defining the deformation behavior of each tetrahedron. For a given rest configuration of vertices $\\mathbf{p}_0, \\mathbf{p}_1, \\mathbf{p}_2, \\mathbf{p}_3$, the shape vector $\\mathbf{n}_i$ at vertex $i$ is defined as:\n\n$$\n\\mathbf{n}_i = (-1)^i \\frac{\\mathbf{e}_{ij} \times \\mathbf{e}_{ik}}{|V|}\n$$\n\nwhere $\\mathbf{e}_{ij} = \\mathbf{p}_j - \\mathbf{p}_i$, and $|V|$ is the volume of the tetrahedron (six times the actual geometric volume).\n\n#### Rest Volume\nThe rest volume $V_0$ of a tetrahedron with vertices at positions $\\mathbf{p}_0, \\mathbf{p}_1, \\mathbf{p}_2, \\mathbf{p}_3$ is calculated as:\n\n$$\n|V| = (\\mathbf{p}_2 - \\mathbf{p}_0) \times (\\mathbf{p}_3 - \\mathbf{p}_0) \bullet (\\mathbf{p}_1 - \\mathbf{p}_0)\n$$\n\nThe normalized volume scale is then:\n\n$$\ntinfo.m_volScale = \\frac{1}{|V|}\n$$\n\n#### Deformation Gradient\nThe deformation gradient $F$ describes the local deformation at each tetrahedron. Given a current configuration of vertices $\\mathbf{x}_0, \\mathbf{x}_1, \\mathbf{x}_2, \\mathbf{x}_3$, and shape vectors $\\mathbf{n}_i$ from rest configuration, it is computed as:\n\n$$\nF = \\sum_{i=0}^{3} \\mathbf{x}_i \\otimes \\mathbf{n}_i\n$$\n\n#### Contraction Stress Tensor\nThe contraction stress tensor $\\sigma$ for a tetrahedron with fiber direction $\\mathbf{d}$ and given scalar stress magnitude $stressMag$, is defined as:\n\n$$\n\\sigma = stressMag \times (\\mathbf{d} \\otimes \\mathbf{d})\n$$\n\n#### Force Computation\nThe forces acting on the vertices of a tetrahedron are computed by applying the contraction stress tensor to shape vectors and multiplying with rest volume:\n\n$$\nf_i = -F \times (\\sigma \times \\mathbf{n}_i) \\times V_0\n$$\n\nwhere $f_i$ is the force acting on vertex $i$, and $V_0$ is the rest volume of the tetrahedron.\n\n#### Potential Energy\nThe potential energy of the system is currently defined as zero, indicating that this component does not include an explicit potential energy term for deformations. This might be handled by other components in the simulation framework:\n\n$$\nU = 0\n$$\n\n### Methods and Algorithms\n#### `addDForce`\nThe method `addDForce` is used to add damping forces or stiffness contributions to the system based on deformation gradients, shape vectors, fiber directions, and given scalar parameters.\n\n#### `computeDeformationGradient`\nThis function calculates the deformation gradient $F$ for a tetrahedron from its current vertex positions and rest configuration's shape vectors. This is fundamental in understanding how each tetrahedron deforms under applied forces or external influences.\n\n### Conclusion\nThe `BaseTetraForceField` provides a robust framework to handle deformations of tetrahedral meshes by defining shape vectors, computing deformation gradients, applying contraction stresses, and ensuring numerical stability. This component is crucial for accurate simulations involving deformable objects in SOFA."
  },
  "summary": {
    "abstract": "The `BaseTetraForceField` computes forces for tetrahedral meshes by defining shape vectors, computing deformation gradients, applying contraction stresses, and ensuring numerical stability. It is essential for accurate simulations involving deformable objects in SOFA.",
    "sheet": "# BaseTetraForceField\n\n## Overview\nThe `BaseTetraForceField` is a general force field designed to handle tetrahedral meshes in simulations involving deformable objects. This component provides foundational structures and methods necessary for implementing various forces specific to tetrahedron-based geometries.\n\n## Mathematical Model\n### Tetrahedron Shape Vectors\nThe shape vectors are critical in defining the deformation behavior of each tetrahedron. For a given rest configuration of vertices \\(\\mathbf{p}_0, \\mathbf{p}_1, \\mathbf{p}_2, \\mathbf{p}_3\\), the shape vector \\(\\mathbf{n}_i\\) at vertex \\(i\\) is defined as:\n\n$$\n\\mathbf{n}_i = (-1)^i \\frac{\\mathbf{e}_{ij}  \times \\mathbf{e}_{ik}}{|V|}\n$$\nwhere \\(\\mathbf{e}_{ij} = \\mathbf{p}_j - \\mathbf{p}_i\\), and \\(|V|\\) is the volume of the tetrahedron (six times the actual geometric volume).\n\n### Rest Volume\nThe rest volume \\(V_0\\) of a tetrahedron with vertices at positions \\(\\mathbf{p}_0, \\mathbf{p}_1, \\mathbf{p}_2, \\mathbf{p}_3\\) is calculated as:\n\n$$\n|V| = (\\mathbf{p}_2 - \\mathbf{p}_0)  \times (\\mathbf{p}_3 - \\mathbf{p}_0)  \bullet (\\mathbf{p}_1 - \\mathbf{p}_0)\n$$\nThe normalized volume scale is then:\n\n$$\ntinfo.m_volScale = \\frac{1}{|V|}\n$$\n\n### Deformation Gradient\nThe deformation gradient \\(F\\) describes the local deformation at each tetrahedron. Given a current configuration of vertices \\(\\mathbf{x}_0, \\mathbf{x}_1, \\mathbf{x}_2, \\mathbf{x}_3\\), and shape vectors \\(\\mathbf{n}_i\\) from rest configuration, it is computed as:\n\n$$\nF = \\sum_{i=0}^{3} \\mathbf{x}_i  \times \\mathbf{n}_i\n$$\n\n### Contraction Stress Tensor\nThe contraction stress tensor \\(\\sigma\\) for a tetrahedron with fiber direction \\(\\mathbf{d}\\) and given scalar stress magnitude \\(stressMag\\), is defined as:\n\n$$\n\\sigma = stressMag  \times (\\mathbf{d}  \times \\mathbf{d})\n$$\n\n### Force Computation\nThe forces acting on the vertices of a tetrahedron are computed by applying the contraction stress tensor to shape vectors and multiplying with rest volume:\n\n$$\nf_i = -F  \times (\\sigma  \times \\mathbf{n}_i)  \times V_0\n$$\nwhere \\(f_i\\) is the force acting on vertex \\(i\\), and \\(V_0\\) is the rest volume of the tetrahedron.\n\n### Potential Energy\nThe potential energy of the system is currently defined as zero, indicating that this component does not include an explicit potential energy term for deformations. This might be handled by other components in the simulation framework:\n\n$$\nU = 0\n$$\n\n## Parameters and Data\n- **fiberDirections (VecCoord)**: Fiber direction in each tetrahedron.\n\n## Dependencies and Connections\nThe `BaseTetraForceField` typically requires a link to a topology component (`BaseMeshTopology`) for defining the mesh structure. It fits into the scene graph by providing force computations necessary for deformable object simulations."
  }
}