Data Fields

Methods

{
  "name": "NonUniformHexahedralFEMForceFieldAndMass",
  "namespace": "sofa::component::solidmechanics::fem::nonuniform",
  "module": "Sofa.Component.SolidMechanics.FEM.NonUniform",
  "include": "sofa/component/solidmechanics/fem/nonuniform/NonUniformHexahedralFEMForceFieldAndMass.h",
  "doc": "Non uniform Hexahedral finite elements.\n\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}\nindices ordering (same as in HexahedronSetTopology):\n     Y  7---------6\n     ^ /         /|\n     |/    Z    / |\n     3----^----2  |\n     |   /     |  |\n     |  4------|--5\n     | /       | /\n     |/        |/\n     0---------1-->X",
  "inherits": [
    "HexahedralFEMForceFieldAndMass"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "_bRecursive",
      "type": "bool",
      "xmlname": "recursive",
      "help": "Use recursive matrix computation"
    },
    {
      "name": "useMBK",
      "type": "bool",
      "xmlname": "useMBK",
      "help": "compute MBK and use it in addMBKdx, instead of using addDForce and addMDx."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleTopologyChange",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::topology::Topology *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeMechanicalMatricesByCondensation",
      "return_type": "void",
      "params": [
        {
          "name": "K",
          "type": "ElementStiffness &"
        },
        {
          "name": "M",
          "type": "ElementMass &"
        },
        {
          "name": "totalMass",
          "type": "Real &"
        },
        {
          "name": "elementIndex",
          "type": "const int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initLarge",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initPolar",
      "return_type": "void",
      "params": [
        {
          "name": "i",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "addMBKdx",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "dfId",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeCorrection",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "ElementMass &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `NonUniformHexahedralFEMForceFieldAndMass` is a SOFA component for simulating non-uniform hexahedral finite elements in solid mechanics simulations. It is part of the SolidMechanics FEM Non-Uniform module and inherits from `HexahedralFEMForceFieldAndMass`. This component facilitates animating shapes at arbitrary resolutions with non-uniform stiffness, which is particularly useful for applications like surgical simulation or soft tissue modeling.\n\n**Role and Purpose:**\nThe component computes mechanical properties (stiffness and mass) at different levels of resolution within hexahedral elements. It supports recursive matrix computation, allowing for efficient management of multi-resolution models. Additionally, it can compute the MBK matrix (mass + damping + stiffness), which is used in implicit time integration schemes.\n\n**Interactions with Other Components:**\nThe `NonUniformHexahedralFEMForceFieldAndMass` interacts primarily with:\n- **Topology Containers**: It requires a `MultilevelHexahedronSetTopologyContainer`, which provides the topological information of hexahedral elements at various levels of refinement.\n- **Mechanical Models and States**: The component uses mechanical states (`core::BaseState`) to access positions, velocities, and forces. It also interacts with implicit solvers via matrix-vector products like `addMBKdx` for efficient simulation.\n\n**Practical Usage Guidance:**\nThe key data fields are:\n- `_bRecursive`: A boolean flag indicating whether recursive matrix computation is used (`true`) or not (`false`).\n- `useMBK`: A boolean to enable the pre-computation and usage of the MBK matrix in implicit integration schemes.\n\nThe component initializes and reinitializes the mechanical properties based on topological changes. It handles topology modifications, such as adding or removing hexahedra, by updating stiffness and mass matrices accordingly. The `handleTopologyChange` method ensures that these updates are consistent with the current topology of the system.\n",
  "maths": "<div>\n<h3>Governing Equations and Operators</h3>\n\n<p>The <code>NonUniformHexahedralFEMForceFieldAndMass</code> is a SOFA component that computes the mechanical properties (mass matrix, stiffness matrix) for hexahedral finite elements. It implements both the mass matrix \\(M\\), internal force vector \\(f_{int}\\), and residual vector \\(R\\).</p>\n\n<p>The key mathematical operators are:</p>\n\n<ul>\n<li><strong>Mass Matrix</strong> (\\(M\\)):</li>\n</ul>\n\n<pre><code class=\"language-latex\">M_e = \\int_{\\Omega_e} \\rho N_e^T N_e d\\Omega\n</code></pre>\n\n<ul>\n<li><strong>Stiffness Matrix</strong> (\\(K_e\\)):</li>\n</ul>\n\n<pre><code class=\"language-latex\">K_e = \\frac{\\partial f_{int}^e}{\\partial x_e}\n</code></pre>\n\n<ul>\n<li><strong>Internal Force Vector</strong> (\\(f_{int}\\)):</li>\n</ul>\n\n<pre><code class=\"language-latex\">f^{e}_{int} = \\int_{\\Omega_e} B_e^T \\sigma_e d\\Omega\n</code></pre>\n\n<ul>\n<li><strong>Residual Vector</strong> (\\(R\\)):</li>\n</ul>\n\n<pre><code class=\"language-latex\">R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{\\Delta t} - \\Delta t f_{int}(x_{n+1}) - \\Delta t f_{ext}\n</code></pre>\n\n<p>The component can also compute the MBK matrix (mass + damping + stiffness), which is used in implicit time integration schemes:</p>\n\n<pre><code class=\"language-latex\">\\alpha M_e + \\beta B_e + \\gamma K_e\n</code></pre>\n\n<h3>Constitutive and Kinematic Laws Involved</h3>\n\n<p>The component computes mechanical properties at different levels of resolution within hexahedral elements. It supports both large deformation formulations (corotational deformations) and polar decomposition for rotations:</p>\n\n<ul>\n<li><strong>Polar Decomposition</strong>: The rotation matrix \\(R_0\\) is computed using polar decomposition, which decomposes the deformation gradient into a rotational part and a stretch part.</li>\n<li><strong>Material Stiffness Tensor</strong>: It computes the material stiffness tensor \\(C\\), which relates strain to stress in Hooke's law:</li>\n</ul>\n\n<pre><code class=\"language-latex\">\\sigma = C : \\varepsilon(u)\n</code></pre>\n\n<ul>\n<li><strong>Mass and Stiffness Matrices Condensation</strong>: The mass and stiffness matrices are condensed from the finest level to the coarsest level using interpolation matrices (denoted as \\(H\\)):</li>\n</ul>\n\n<pre><code class=\"language-latex\">K = H^T K_{fine} H, \\quad M = H^T M_{fine} H\n</code></pre>\n\n<h3>Role in the Global FEM Pipeline</h3>\n\n<p>The <code>NonUniformHexahedralFEMForceFieldAndMass</code> component plays a significant role in:</p>\n\n<ul>\n<li><strong>Assembly Phase</strong>: It computes and assembles mass and stiffness matrices for each element.</li>\n<li><strong>Time Integration</strong>: The component participates in implicit time integration schemes, such as Backward Euler.</li>\n<li><strong>Nonlinear Solution</strong>: It handles the nonlinear residual \\(R\\) and Jacobian matrix evaluation.</li>\n<li><strong>Multilevel Topology Handling</strong>: It manages multi-resolution models by updating stiffness and mass matrices when the topology changes (e.g., adding or removing hexahedra).</li>\n</ul>\n\n<h3>Numerical Methods and Discretization Choices</h3>\n\n<p>The component supports:</p>\n\n<ul>\n<li><strong>Recursive Matrix Computation</strong>: A boolean flag `_bRecursive` controls whether to use recursive methods for efficient computation of matrices at different levels.</li>\n<li><strong>Mechanical Matrices Condensation</strong>: It can compute mechanical matrices via interval analysis or direct summation, and supports both recursive and non-recursive approaches.</li>\n<li><strong>Matrix Correction</strong>: The component applies corrections to the MBK matrix to avoid ill-conditioning issues.</li>\n</ul>\n\n<h3>Fit into Variational/Lagrangian Mechanics Framework</h3>\n\n<p>The <code>NonUniformHexahedralFEMForceFieldAndMass</code> fits into a variational framework by discretizing the weak form of the governing equations. It maintains consistency with Lagrangian mechanics principles:</p>\n\n<ul>\n<li><strong>Variational Formulation</strong>: The component computes mass and stiffness matrices from integrals involving shape functions, which are derived from the weak form.</li>\n<li><strong>Consistency in Large Deformations</strong>: It handles large deformations through corotational formulations or polar decomposition to ensure that rotations and stretches are correctly computed.</li>\n<li><strong>Variationally Consistent Constraints</strong>: The component ensures that constraint forces (e.g., due to topology changes) maintain the variational consistency of the system.</li>\n</ul>\n\n<p>This component is designed for efficient simulation of non-uniform hexahedral elements, making it suitable for applications such as surgical simulation or soft tissue modeling where arbitrary resolution and stiffness variations are required.</p>\n</div>",
  "abstract": "The `NonUniformHexahedralFEMForceFieldAndMass` computes mass and stiffness matrices for non-uniform hexahedral finite elements, supporting multi-resolution models through recursive matrix computation.",
  "sheet": "# NonUniformHexahedralFEMForceFieldAndMass\n\n## Overview\n\nThe `NonUniformHexahedralFEMForceFieldAndMass` is a SOFA component designed to compute mass and stiffness matrices for non-uniform hexahedral finite elements. It supports multi-resolution models through recursive matrix computation, making it suitable for applications such as surgical simulation or soft tissue modeling.\n\n## Mathematical Model\n\nThe component computes the following mechanical properties:\n\n- **Mass Matrix** (\\(M\")): \n  \\[ M_e = \\int_{\\Omega_e} \\rho N_e^T N_e d\\Omega \\]\n- **Stiffness Matrix** (\\(K_e\"): \n  \\[ K_e = \\frac{\\partial f_{int}^e}{\\partial x_e} \\]\n- **Internal Force Vector** (\\(f_{int}\")): \n  \\[ f^{e}_{int} = \\int_{\\Omega_e} B_e^T \\sigma_e d\\Omega \\]\n- **Residual Vector** (\\(R\"): \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} \\]\n\nThe component also computes the MBK matrix (mass + damping + stiffness) for implicit time integration schemes:\n  \\[ \\alpha M_e + \\beta B_e + \\gamma K_e \\]\n\n## Parameters and Data\n\n- **_bRecursive**: A boolean flag indicating whether recursive matrix computation is used (`true`) or not (`false`).\n- **useMBK**: A boolean to enable the pre-computation and usage of the MBK matrix in implicit integration schemes.\n\n## Dependencies and Connections\n\nThe component interacts with:\n- **Topology Containers**: Requires a `MultilevelHexahedronSetTopologyContainer` for topological information at various levels of refinement.\n- **Mechanical Models and States**: Uses mechanical states (`core::BaseState`) to access positions, velocities, and forces. Interacts with implicit solvers via matrix-vector products like `addMBKdx` for efficient simulation.\n\n## Practical Notes\n\nThe component supports recursive matrix computation for efficient management of multi-resolution models. Numerical stability is maintained through careful handling of mechanical matrices and MBK corrections."
}