Data Fields

Methods

{
  "name": "HexahedronFEMForceField",
  "namespace": "sofa::component::solidmechanics::fem::elastic",
  "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
  "include": "sofa/component/solidmechanics/fem/elastic/HexahedronFEMForceField.h",
  "doc": "Hexahedral finite elements.\n\nCompute Finite Element forces based on hexahedral elements.\nCorotational hexahedron from\n@Article{NMPCPF05,\n  author       = \"Nesme, Matthieu and Marchal, Maud and Promayon, Emmanuel and Chabanas, Matthieu and Payan, Yohan and Faure, Fran\\c{c}ois\",\n  title        = \"Physically Realistic Interactive Simulation for Biological Soft Tissues\",\n  journal      = \"Recent Research Developments in Biomechanics\",\n  volume       = \"2\",\n  year         = \"2005\",\n  keywords     = \"surgical simulation physical animation truth cube\",\n  url          = \"http://www-evasion.imag.fr/Publications/2005/NMPCPF05\"\n}\nWARNING: indices ordering is different than in topology node\n    Y  7---------6\n    ^ /         /|\n    |/    Z    / |\n    3----^----2  |\n    |   /     |  |\n    |  4------|--5\n    | /       | /\n    |/        |/\n    0---------1-->X",
  "inherits": [
    "BaseLinearElasticityFEMForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_updateStiffnessMatrix",
      "type": "bool",
      "xmlname": "updateStiffnessMatrix",
      "help": ""
    },
    {
      "name": "d_gatherPt",
      "type": "sofa::helper::OptionsGroup",
      "xmlname": "gatherPt",
      "help": "number of dof accumulated per threads during the gather operation (Only use in GPU version)"
    },
    {
      "name": "d_gatherBsize",
      "type": "sofa::helper::OptionsGroup",
      "xmlname": "gatherBsize",
      "help": "number of dof accumulated per threads during the gather operation (Only use in GPU version)"
    },
    {
      "name": "d_drawing",
      "type": "bool",
      "xmlname": "drawing",
      "help": "draw the forcefield if true"
    },
    {
      "name": "d_drawPercentageOffset",
      "type": "Real",
      "xmlname": "drawPercentageOffset",
      "help": "size of the hexa"
    },
    {
      "name": "d_elementStiffnesses",
      "type": "VecElementStiffness",
      "xmlname": "stiffnessMatrices",
      "help": "Stiffness matrices per element (K_i)"
    },
    {
      "name": "d_initialPoints",
      "type": "VecCoord",
      "xmlname": "initialPoints",
      "help": "Initial Position"
    },
    {
      "name": "data",
      "type": "DataTypes"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "setMethod",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setUpdateStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "bool"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "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": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getElementRotation",
      "return_type": "const Transformation &",
      "params": [
        {
          "name": "elemidx",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getNodeRotation",
      "return_type": "void",
      "params": [
        {
          "name": "R",
          "type": "Transformation &"
        },
        {
          "name": "nodeIdx",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRotations",
      "return_type": "void",
      "params": [
        {
          "name": "rotations",
          "type": "linearalgebra::BaseMatrix *"
        },
        {
          "name": "offset",
          "type": "int"
        }
      ],
      "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": 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": "computeBBox",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "onlyVisible",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleTopologyChange",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIndexedElements",
      "return_type": "const VecElement *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeElementStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "K",
          "type": "ElementStiffness &"
        },
        {
          "name": "M",
          "type": "const MaterialStiffness &"
        },
        {
          "name": "nodes",
          "type": "const type::Vec<8, Coord> &"
        },
        {
          "name": "elementIndice",
          "type": "const int"
        },
        {
          "name": "stiffnessFactor",
          "type": "double"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "integrateStiffness",
      "return_type": "Mat33",
      "params": [
        {
          "name": "signx0",
          "type": "int"
        },
        {
          "name": "signy0",
          "type": "int"
        },
        {
          "name": "signz0",
          "type": "int"
        },
        {
          "name": "signx1",
          "type": "int"
        },
        {
          "name": "signy1",
          "type": "int"
        },
        {
          "name": "signz1",
          "type": "int"
        },
        {
          "name": "u",
          "type": "const Real"
        },
        {
          "name": "v",
          "type": "const Real"
        },
        {
          "name": "w",
          "type": "const Real"
        },
        {
          "name": "J_1",
          "type": "const Mat33 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "computeMaterialStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeForce",
      "return_type": "void",
      "params": [
        {
          "name": "F",
          "type": "Displacement &"
        },
        {
          "name": "Depl",
          "type": "const Displacement &"
        },
        {
          "name": "K",
          "type": "const ElementStiffness &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "initLarge",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeRotationLarge",
      "return_type": "void",
      "params": [
        {
          "name": "r",
          "type": "Transformation &"
        },
        {
          "name": "edgex",
          "type": "Coord &"
        },
        {
          "name": "edgey",
          "type": "Coord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    },
    {
      "name": "accumulateForceLarge",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "WDataRefVecDeriv &"
        },
        {
          "name": "p",
          "type": "RDataRefVecCoord &"
        },
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initPolar",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeRotationPolar",
      "return_type": "void",
      "params": [
        {
          "name": "r",
          "type": "Transformation &"
        },
        {
          "name": "nodes",
          "type": "type::Vec<8, Coord> &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "accumulateForcePolar",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "WDataRefVecDeriv &"
        },
        {
          "name": "p",
          "type": "RDataRefVecCoord &"
        },
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initSmall",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "accumulateForceSmall",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "WDataRefVecDeriv &"
        },
        {
          "name": "p",
          "type": "RDataRefVecCoord &"
        },
        {
          "name": "i",
          "type": "int"
        },
        {
          "name": "elem",
          "type": "const Element &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The HexahedronFEMForceField component computes finite element forces based on hexahedral elements using the corotational formulation. It is commonly used in simulating deformable bodies with tetrahedral or hexahedral meshes.",
  "parameters": [
    {
      "name": "method",
      "type": "string",
      "description": "Specifies the displacement method to use for computing forces: 'large', 'polar', or 'small'. The default is 'polar'.\n- large: Uses mean edges for frame calculation.\n- polar: Uses polar decomposition for rotation calculation.\n- small: Assumes small deformations and no rotations.",
      "default": "'polar'"
    },
    {
      "name": "updateStiffnessMatrix",
      "type": "bool",
      "description": "Determines whether the stiffness matrix should be updated at each time step. Default is false (the stiffness matrix is not updated).",
      "default": "false"
    },
    {
      "name": "drawing",
      "type": "bool",
      "description": "Enables or disables visualization of the force field.",
      "default": "false"
    },
    {
      "name": "drawPercentageOffset",
      "type": "float",
      "description": "Controls the size of the hexahedra when visualizing the force field. The value represents a percentage offset from the original size.",
      "default": "1.0"
    }
  ],
  "inputs": [
    {
      "name": "positions",
      "type": "VecCoord",
      "description": "The current positions of the nodes in the simulation."
    },
    {
      "name": "velocities",
      "type": "VecDeriv",
      "description": "The velocities of the nodes in the simulation (not used for force computation but may be relevant for dynamic simulations)."
    }
  ],
  "outputs": [
    {
      "name": "forces",
      "type": "VecDeriv",
      "description": "The computed forces acting on each node due to deformation."
    }
  ],
  "maths": "The HexahedronFEMForceField component computes finite element forces based on hexahedral elements using the corotational formulation. It is commonly used in simulating deformable bodies with tetrahedral or hexahedral meshes. The force field contributes to a unified FEM simulation framework, grounded in variational mechanics and Lagrangian dynamics.\n\n### Governing Equations\nThe component computes forces and stiffness matrices for each hexahedron element based on the deformation of the structure. It supports different formulations for large displacements, polar decomposition, and small deformations.\n\n#### Element Stiffness Matrix (K)\nThe stiffness matrix K is derived from the material properties and geometric configuration of the hexahedral elements:\n\n\begin{align*}\n    & K = \\int_V B^T D B\\, dV \\\\\n    & B = DN \\\\\n    & DN = \\left[ \\frac{dN}{dx} \\quad 0 \\quad 0; 0 \\quad \\frac{dN}{dy} \\quad 0; 0 \\quad 0 \\quad \\frac{dN}{dz}; \\frac{dN}{dy} \\quad \\frac{dN}{dx} \\quad 0; 0 \\quad \\frac{dN}{dz} \\quad \\frac{dN}{dy}; \\frac{dN}{dz} \\quad 0 \\quad \\frac{dN}{dx} \\right]\n\\end{align*}\n\nWhere $B$ is the strain-displacement matrix, and $DN$ represents partial derivatives of shape functions with respect to spatial coordinates.\n\n#### Internal Force (f_int)\nThe internal force is calculated from the stiffness matrix and nodal displacements:\n\n\begin{align*}\n    f_{int} = -K \\delta u\n\\end{align*}\n\nWhere $\\delta u$ represents the displacement vector.\n\n### Constitutive Laws\nThe material properties are defined through the constitutive law, which is computed for each element:\n\n\begin{align*}\n    & U = \\frac{Y(1 - p)}{(1 + p)(1 - 2p)} \\\\\n    & V = \\frac{Y p}{(1 + p)(1 - 2p)} \\\\\n    & W = \\frac{Y}{2(1+p)}\n\\end{align*}\n\nWhere $U$, $V$, and $W$ are the stiffness components of the material, $Y$ is Young's modulus, and $p$ is Poisson's ratio.\n\n### Role in FEM Pipeline\nThis component plays a crucial role in assembling global stiffness matrices and internal forces for nonlinear dynamics. It integrates with the broader SOFA simulation pipeline to handle spatial discretization, time integration, nonlinear solution strategies, constraint handling, and mappings.\n\n#### Spatial Discretization\nThe hexahedral elements are used as basis functions in the FEM formulation:\n\n\begin{align*}\n    & X = T_e(\\xi) \\\\\n    & J_e = \\frac{dX}{d\\xi} \n\\end{align*}\n\nWhere $T_e$ is the interpolation function and $J_e$ is the Jacobian.\n\n#### Time Integration\nThe component supports implicit time integration schemes, such as Backward Euler. It computes the nonlinear residual at each time step:\n\n\begin{align*}\n    R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}=0 \n\\end{align*}\n\n#### Nonlinear Solution\nThe component uses the Newton-Raphson iteration to solve nonlinear systems:\n\n\begin{align*}\n    J(x_k)\\delta x_k=-R(x_k)\n\\end{align*}\n\nWhere $J$ is the Jacobian of the residual function.\n\n### Numerical Methods and Discretization Choices\nThe stiffness matrices are computed using numerical integration (Gauss quadrature), and rotation matrices are used to account for large displacements in the corotational formulation. The element stiffness matrix computation involves transforming derivatives from the local hexahedral basis to the global coordinate system.\n\n### Mapping and Constraint Handling\nRotation mappings are applied to ensure consistent transformations between different elements, preserving mechanical invariants such as constraints and contacts.\n\nIn summary, HexahedronFEMForceField is a critical component for simulating deformable bodies with hexahedral finite elements within the SOFA framework.",
  "abstract": "The HexahedronFEMForceField computes finite element forces and stiffness matrices for hexahedral elements using corotational formulations, supporting large displacements and polar decomposition in deformable body simulations.",
  "sheet": "# HexahedronFEMForceField\n\n## Overview\nHexahedronFEMForceField is a component that computes finite element forces and stiffness matrices based on hexahedral elements. It supports various formulations for large displacements, polar decomposition, and small deformations within the SOFA framework.\n\n## Mathematical Model\nThe HexahedronFEMForceField component computes forces and stiffness matrices for each hexahedron element based on the deformation of the structure using corotational formulations.\n\n### Element Stiffness Matrix (K)\nThe stiffness matrix $K$ is derived from material properties and geometric configuration:\n\\[ K = \\int_V B^T D B\\, dV \\]\nwhere $B$ is the strain-displacement matrix given by:\n\\[ B = DN \\quad \\text{and} \\quad DN = \\begin{bmatrix}\n    \\frac{dN}{dx} & 0 & 0 \\\\\n    0 & \\frac{dN}{dy} & 0 \\\\\n    0 & 0 & \\frac{dN}{dz} \\\\\n    \\frac{dN}{dy} & \\frac{dN}{dx} & 0 \\\\\n    0 & \\frac{dN}{dz} & \\frac{dN}{dy} \\\\\n    \\frac{dN}{dz} & 0 & \\frac{dN}{dx}\n\\end{bmatrix} \\]\n\n### Internal Force (f_int)\nThe internal force is calculated from the stiffness matrix and nodal displacements:\n\\[ f_{int} = -K \\delta u \\]\nwhere $\\delta u$ represents the displacement vector.\n\n### Constitutive Laws\nThe material properties are defined through the constitutive law, which is computed for each element:\n\\begin{align*}\n    & U = \\frac{Y(1 - p)}{(1 + p)(1 - 2p)} \\\\\n    & V = \\frac{Y p}{(1 + p)(1 - 2p)} \\\\\n    & W = \\frac{Y}{2(1+p)}\n\\end{align*}\nwhere $U$, $V$, and $W$ are the stiffness components of the material, $Y$ is Young's modulus, and $p$ is Poisson's ratio.\n\n## Parameters and Data\nThe significant data fields exposed by this component include:\n- `updateStiffnessMatrix`: A boolean flag to update the stiffness matrix.\n- `gatherPt` and `gatherBsize`: Options for controlling the number of degrees of freedom accumulated per thread during gather operations (GPU version).\n- `drawing`: A boolean flag to enable drawing the force field.\n- `drawPercentageOffset`: The size of the hexahedron for visualization purposes.\n- `stiffnessMatrices`: Stiffness matrices per element ($K_i$).\n- `initialPoints`: Initial positions of nodes."
}