Data Fields

Methods

{
  "name": "NonUniformHexahedronFEMForceFieldAndMass",
  "namespace": "sofa::component::solidmechanics::fem::nonuniform",
  "module": "Sofa.Component.SolidMechanics.FEM.NonUniform",
  "include": "sofa/component/solidmechanics/fem/nonuniform/NonUniformHexahedronFEMForceFieldAndMass.h",
  "doc": "Non uniform Hexahedral finite elements.\n\nNeed a SparseGridTopology with _sparseGrid->d_nbVirtualFinerLevels >= this->d_nbVirtualFinerLevels\n@InProceedings{NPF06,\nauthor       = \"Nesme, Matthieu and Payan, Yohan and Faure, Fran\\c{c}ois\",\ntitle        = \"Animating Shapes at Arbitrary Resolution with Non-Uniform Stiffness\",\nbooktitle    = \"Eurographics Workshop in Virtual Reality Interaction and Physical Simulation (VRIPHYS)\",\nmonth        = \"nov\",\nyear         = \"2006\",\norganization = \"Eurographics\",\naddress      = \"Madrid\",\nurl          = \"http://www-evasion.imag.fr/Publications/2006/NPF06\"\n}",
  "inherits": [
    "HexahedronFEMForceFieldAndMass"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_nbVirtualFinerLevels",
      "type": "int",
      "xmlname": "nbVirtualFinerLevels",
      "help": "use virtual finer levels, in order to compte non-uniform stiffness"
    },
    {
      "name": "d_useMass",
      "type": "bool",
      "xmlname": "useMass",
      "help": "Using this ForceField like a Mass? (rather than using a separated Mass)"
    },
    {
      "name": "d_totalMass",
      "type": "Real",
      "xmlname": "totalMass",
      "help": ""
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "description": "Initialization method called by SOFA framework. Prepares data structures for simulation."
    },
    {
      "name": "reinit",
      "description": "Reinitialization method that warns users changes to mechanical properties are not taken into account in this component."
    },
    {
      "name": "addMDx",
      "description": "Overridden method from base class to add mass times derivative of displacement to force vector with possible scaling factor."
    },
    {
      "name": "addGravityToV",
      "description": "Overridden method from base class to apply gravity to velocity vector based on mechanical parameters."
    },
    {
      "name": "addForce",
      "description": "Overridden method from base class to add forces computed from position and velocity vectors with possible scaling factor."
    }
  ],
  "description": "This component implements non-uniform hexahedral finite elements for solid mechanics simulations in SOFA.",
  "parameters": [
    {
      "name": "d_nbVirtualFinerLevels",
      "type": "int",
      "description": "Number of virtual finer levels used to compute the non-uniform stiffness."
    },
    {
      "name": "d_useMass",
      "type": "bool",
      "description": "Whether this force field should be used as a mass (rather than using a separate Mass component)."
    },
    {
      "name": "d_totalMass",
      "type": "Real",
      "description": "Total mass of the object."
    }
  ],
  "protected_methods": [
    {
      "name": "computeClassicalMechanicalMatrices",
      "description": "Computes classical stiffness and mass matrices for a given element at specified level."
    },
    {
      "name": "addFineToCoarse",
      "description": "Adds fine element matrix to its enclosing coarser element matrix."
    },
    {
      "name": "computeMaterialStiffness",
      "description": "Computes Hookean material stiffness matrix based on Young's modulus and Poisson's ratio."
    }
  ],
  "maths": "The `NonUniformHexahedronFEMForceFieldAndMass` component in the SOFA framework implements non-uniform hexahedral finite elements, which are particularly useful for simulating deformable bodies with varying material properties across different regions. The component is designed to work with a `SparseGridTopology`, enabling it to handle non-uniform stiffness through virtual finer levels of refinement within each element.\n\n### Governing Equations and Operators\n\nThe governing equations include the mass matrix $M$ and the stiffness matrix $K$, as well as the internal forces $f_{int}$, which are computed by condensation from finer elements to coarser ones. The component implements:\n\n1. **Mass Matrix**: $M$\n2. **Stiffness Matrix**: $K$\n3. **Internal Force Vector**: $f_{int} = M \frac{d^2 x}{dt^2} + K x$\n4. **Residual Vector**: $R(x) = M \frac{x_{n+1}-x_n}{\triangle t} - \triangle t f_{int}(x_{n+1}) - \triangle t f_{ext}$\n\n### Constitutive or Kinematic Laws Involved\n\n- **Material Stiffness Matrix**: The material stiffness matrix $\\mathcal{C}$ is computed based on Young's modulus ($E$) and Poisson’s ratio ($\\nu$):\n  \\[ \\mathcal{C} = \\frac{E(1 - \\nu)}{(1 + \\nu)(1 - 2\\nu)} \\begin{bmatrix}\n    1 & \\nu & \\nu & 0 & 0 & 0 \\\\\n    \\nu & 1 & \\nu & 0 & 0 & 0 \\\\\n    \\nu & \\nu & 1 & 0 & 0 & 0 \\\\\n    0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)} & 0 & 0 \\\\\n    0 & 0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)} & 0 \\\\\n    0 & 0 & 0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)}\n   \\end{bmatrix} \\]\n\n### Role in the Global FEM Pipeline\n\nThis component fits into the global FEM pipeline as follows:\n\n1. **Discretization Phase**\n   - The `NonUniformHexahedronFEMForceFieldAndMass` uses a SparseGridTopology, which supports non-uniform refinement through virtual finer levels.\n   - It computes stiffness and mass matrices by condensation from the finest level to the current mechanical level.\n\n2. **Assembly Phase**\n   - The element-wise contributions of $M$ and $K$ are assembled into global matrices.\n   - Internal forces and residuals are computed for each hexahedral element, considering the stiffness and mass properties at different levels.\n\n3. **Time Integration**\n   - Implicit Euler or similar schemes handle time integration to update nodal displacements.\n   - The component supports large deformation formulations by computing corotational deformations.\n\n4. **Nonlinear Resolution**\n   - Newton-Raphson iterations are used for solving the nonlinear system resulting from the internal forces and constraints.\n\n5. **Linear Solution**\n   - Linear systems arising from the stiffness matrix $K$ and mass matrix $M$ are solved iteratively or directly, depending on the chosen solver.\n\n### Numerical Methods or Discretization Choices\n\n- The component employs a hierarchical approach to compute element-wise properties at different levels of refinement. This allows for non-uniform material distributions within the mesh.\n- Condensation techniques ensure that finer level matrices are appropriately added to coarser ones, preserving accuracy while maintaining computational efficiency.\n\n### Variational / Lagrangian Mechanics Framework\n\nThe component adheres to a variational framework where the discretization process begins with the weak form of the governing equations. By using non-uniform hexahedral elements and virtual finer levels, it provides flexibility in modeling materials with varying properties. This approach aligns well with the variational principles that underlie Lagrangian mechanics, ensuring consistency between analytical formulations and numerical implementations.\n\n### Summary\n\nThe `NonUniformHexahedronFEMForceFieldAndMass` component is designed to efficiently simulate solid mechanics problems where material properties vary spatially. It leverages non-uniform hexahedral elements and sparse grid topologies for accurate representation of complex geometries with varying stiffness, making it particularly useful in applications such as soft tissue modeling.",
  "abstract": "The `NonUniformHexahedronFEMForceFieldAndMass` computes non-uniform hexahedral finite elements with varying material properties using a SparseGridTopology, supporting mass and stiffness matrix computations, internal forces, and residuals.",
  "sheet": "<h1>NonUniformHexahedronFEMForceFieldAndMass</h1>\n\n<h2>Overview</h2>\n<p>The `NonUniformHexahedronFEMForceFieldAndMass` component is designed for solid mechanics simulations with non-uniform hexahedral finite elements. It supports varying material properties across different regions using a SparseGridTopology, and handles the computation of mass and stiffness matrices, internal forces, and residuals.</p>\n\n<h2>Mathematical Model</h2>\n<p>The governing equations include:</p>\n<ul>\n<li><strong>Mass Matrix</strong>: $M$</li>\n<li><strong>Stiffness Matrix</strong>: $K$</li>\n<li><strong>Internal Force Vector</strong>: $f_{int} = M \\frac{d^2 x}{dt^2} + K x$</li>\n<li><strong>Residual Vector</strong>: $R(x) = M \\frac{x_{n+1}-x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}$</li>\n</ul>\n<p>The material stiffness matrix $\\mathcal{C}$ is computed based on Young's modulus ($E$) and Poisson’s ratio ($\\nu$):</p>\n<p>$$\n\\mathcal{C} = \\frac{E(1 - \\nu)}{(1 + \\nu)(1 - 2\\nu)} \n\\begin{bmatrix}\n    1 & \\nu & \\nu & 0 & 0 & 0 \\\\\n    \\nu & 1 & \\nu & 0 & 0 & 0 \\\\\n    \\nu & \\nu & 1 & 0 & 0 & 0 \\\\\n    0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)} & 0 & 0 \\\\\n    0 & 0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)} & 0 \\\\\n    0 & 0 & 0 & 0 & 0 & \\frac{1-2\\nu}{2(1 - \\nu)}\n   \\end{bmatrix}\n$$</p>\n\n<h2>Parameters and Data</h2>\n<ul>\n<li><strong>nbVirtualFinerLevels (int)</strong>: Number of virtual finer levels to compute non-uniform stiffness.</li>\n<li><strong>useMass (bool)</strong>: Whether this ForceField is used as a Mass component.</li>\n<li><strong>totalMass (Real)</strong>: Total mass of the element.</li>\n</ul>"
}