Data Fields

Links

Methods

{
  "name": "StandardTetrahedralFEMForceField",
  "namespace": "sofa::component::solidmechanics::fem::hyperelastic",
  "module": "Sofa.Component.SolidMechanics.FEM.HyperElastic",
  "include": "sofa/component/solidmechanics/fem/hyperelastic/StandardTetrahedralFEMForceField.h",
  "doc": "Generic Tetrahedral finite elements.\n\nCompute Finite Element forces based on tetrahedral elements.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_parameterSet",
      "type": "SetParameterArray",
      "xmlname": "ParameterSet",
      "help": "The global parameters specifying the material"
    },
    {
      "name": "f_anisotropySet",
      "type": "SetAnisotropyDirectionArray",
      "xmlname": "AnisotropyDirections",
      "help": "The global directions of anisotropy of the material"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "setMaterialName",
      "return_type": "void",
      "params": [
        {
          "name": "name",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setparameter",
      "return_type": "void",
      "params": [
        {
          "name": "param",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setdirection",
      "return_type": "void",
      "params": [
        {
          "name": "direction",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initNeighbourhoodPoints",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "initNeighbourhoodEdges",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "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": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "d_f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "d_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": "d_df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_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": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "createTetrahedronRestInformation",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "Index"
        },
        {
          "name": "t",
          "type": "TetrahedronRestInformation &"
        },
        {
          "name": "",
          "type": "const core::topology::BaseMeshTopology::Tetrahedron &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "testDerivatives",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "saveMesh",
      "return_type": "void",
      "params": [
        {
          "name": "filename",
          "type": "const char *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `StandardTetrahedralFEMForceField` is a component in the SOFA framework used for simulating tetrahedral finite elements, particularly in solid mechanics and hyperelastic materials. It computes forces based on tetrahedral elements to model deformable objects with nonlinear elasticity. This component inherits from the `core::behavior::ForceField` class and operates on vector types, such as `Vec3Types`, commonly used for 3D simulations.\n\nThe main purpose of this component is to enable accurate force computation in finite element-based simulations by leveraging various material models (e.g., NeoHookean, Arruda-Boyce) specified via parameters. It integrates seamlessly with the SOFA scene graph architecture and interacts primarily with a topology container (`BaseMeshTopology`) linked through `l_topology`. The component uses this topology to define tetrahedral elements and compute forces acting on them.\n\nThe component provides several public methods for interaction, including setting material names (`setMaterialName`), parameters (`setparameter`), anisotropy directions (`setdirection`), and initializing the tetrahedron information. It supports key simulation functionalities such as `addForce`, `addDForce`, stiffness matrix assembly (`buildStiffnessMatrix`), and drawing for visualization.\n\nData fields of interest include:\n- `f_parameterSet`: Global parameters specifying the material properties.\n- `f_anisotropySet`: Directions of anisotropy in the material.\n- `l_topology`: Link to the topology container that defines tetrahedral elements.\n\nThe component also supports initialization routines for neighborhood points and edges (`initNeighbourhoodPoints`, `initNeighbourhoodEdges`) which can be useful for certain computational requirements, such as CUDA implementations.",
  "maths": "The `StandardTetrahedralFEMForceField` in the SOFA framework is designed to simulate tetrahedral finite elements, particularly for deformable objects with nonlinear elasticity. This component inherits from the `core::behavior::ForceField` class and operates on vector types such as `Vec3Types`, which are commonly used for 3D simulations.\n\n### Governing Equations and Operators\n\nThis component computes forces based on tetrahedral elements, contributing to the internal force field of deformable objects. The governing equations involve the computation of strain energy and its derivatives with respect to the deformation gradient. The key operators include:\n\n- **Mass Matrix (M)**: Not directly computed by this component but may be assembled separately for time integration schemes.\n- **Stiffness Matrix (K)**: Computed during implicit time integration, representing the tangent stiffness of the material.\n- **Internal Force Vector (\\(f_{int}\\))**: Calculated in the `addForce` method using the strain-displacement matrix \\(B_i\\) and the second Piola-Kirchhoff stress tensor \\(S\\).\n\nThe component also computes the stiffness matrix contributions for each edge of the tetrahedron during implicit time integration.\n\n### Constitutive or Kinematic Laws Involved\n\nThis component supports various hyperelastic material models, including:\n- **Neo-Hookean**\n- **Arruda-Boyce**\n- **Saint-Venant-Kirchhoff**\n- **Mooney-Rivlin**\n- **Veronda-Westman**\n- **Costa**\n- **Ogden**\n\nEach of these models defines the strain energy function \\(W\\) and its derivatives with respect to the deformation gradient. For instance, for the Neo-Hookean material:\n\\[ W = \\frac{1}{2} (I_1 - 3) + \\frac{1}{2 \\mu} J^2 \\]\nwhere \\(I_1\\) is the first strain invariant and \\(μ\\) is the shear modulus.\n\n### Role in the Global FEM Pipeline\n\nIn the broader FEM simulation pipeline, this component plays a critical role in the following stages:\n- **Spatial Discretization**: Defines tetrahedral elements based on the input mesh topology (`l_topology`).\n- **Assembly Phase**: Computes strain-displacement matrices \\(B_i\\), deformation gradients, and internal forces for each tetrahedron.\n- **Time Integration**: Supports implicit time integration schemes by assembling the stiffness matrix contributions during the `addForce` method.\n- **Nonlinear Resolution**: Implicit schemes require solving nonlinear residual equations, which are handled within the broader SOFA framework.\n\n### Numerical Methods and Discretization Choices\n\nThis component employs the following numerical methods:\n- **Shape Functions**: Linear tetrahedral elements with linear shape functions for displacement interpolation.\n- **Strain-Displacement Matrix (\\(B_i\\))**: Derived based on the shape functions and used to compute strain from nodal displacements.\n- **Second Piola-Kirchhoff Stress Tensor (\\(S\\))**: Computed using the material model's energy function derivatives.\n\n### Variational / Lagrangian Mechanics Framework\n\nThis component fits into the broader variational framework by contributing to the weak form of the equilibrium equation. The internal forces are derived from the strain energy density, and the stiffness matrix represents the tangent stiffness of the material at each step. The `addForce` method computes the internal force contribution \\(f_{int}\\) as:\n\\[ f_i = -B_i^T S V \\]\nwhere \\(V\\) is the volume of the tetrahedron.\n\n### Detailed Mathematical Description\n\n1. **Deformation Gradient (F)**: Computed from nodal displacements and shape functions.\n   \\[ F_{i} = B_i u \\]\n2. **Right Cauchy-Green Deformation Tensor (C)**:\n   \\[ C = F^T F \\]\n3. **Strain-Displacement Matrix (\\(B_i\\))**: Derived from shape functions and used to map nodal displacements to strains.\n4. **Second Piola-Kirchhoff Stress Tensor (S)**: Computed using the material's strain energy function derivatives.\n5. **Internal Force Calculation**:\n   \\[ f_{int} = -\\sum_i B_i^T S V \\]\n6. **Stiffness Matrix Assembly**: For implicit time integration, stiffness contributions are assembled edge-wise.\n\n### Constraints and Mappings\n\nThis component does not directly handle constraints or mappings; these functionalities are typically managed by other components in the SOFA framework.\n\nIn summary, `StandardTetrahedralFEMForceField` is a comprehensive component for simulating nonlinear elasticity using tetrahedral finite elements within the SOFA framework. It supports various material models and fits seamlessly into the broader variational mechanics simulation pipeline.",
  "abstract": "The `StandardTetrahedralFEMForceField` computes finite element forces based on tetrahedral elements for solid mechanics simulations in SOFA, supporting various hyperelastic material models.",
  "sheet": "# StandardTetrahedralFEMForceField\n\n## Overview\nThe `StandardTetrahedralFEMForceField` is a component that computes finite element forces based on tetrahedral elements. It supports nonlinear elasticity and various hyperelastic material models such as Neo-Hookean, Arruda-Boyce, Saint-Venant-Kirchhoff, Mooney-Rivlin, Veronda-Westman, Costa, and Ogden. This component interacts with the topology container (`BaseMeshTopology`) to define tetrahedral elements and compute internal forces.\n\n## Mathematical Model\nThe `StandardTetrahedralFEMForceField` computes internal forces based on the deformation of tetrahedral elements using hyperelastic material models. The governing equations involve computing strain energy and its derivatives with respect to the deformation gradient. Key operators include:\n- **Mass Matrix (M)**: Not directly computed by this component but may be assembled separately for time integration schemes.\n- **Stiffness Matrix (K)**: Computed during implicit time integration, representing the tangent stiffness of the material.\n- **Internal Force Vector ( f_{int} )**: Calculated using the strain-displacement matrix  B_i  and the second Piola-Kirchhoff stress tensor  S .\n\nFor example, in a Neo-Hookean material model:\n\\[ W = \\frac{1}{2} (I_1 - 3) + \\frac{1}{2 \\mu} J^2 \\]\nwhere  I_1  is the first strain invariant and  μ  is the shear modulus.\n\nThe internal forces are derived from the strain energy density, and the stiffness matrix represents the tangent stiffness of the material at each step. The `addForce` method computes the internal force contribution as:\n\\[ f_i = -B_i^T S V \\]\nwhere  V  is the volume of the tetrahedron.\n\n## Parameters and Data\n- **f_parameterSet**: Global parameters specifying the material properties (type: `SetParameterArray`, default not specified).\n- **f_anisotropySet**: Directions of anisotropy in the material (type: `SetAnisotropyDirectionArray`, default not specified).\n- **l_topology**: Link to the topology container that defines tetrahedral elements (type: `BaseMeshTopology`).\n\n## Dependencies and Connections\nThis component requires a linked topology container (`BaseMeshTopology`) to define tetrahedral elements. It fits into the SOFA scene graph architecture by interacting with other components for force computation, stiffness matrix assembly, and visualization."
}