Data Fields

Methods

{
  "name": "TetrahedronConstantContractionForceField",
  "namespace": "sofa::component",
  "module": "SofaTestPlugin",
  "include": "forcefield/active/TetrahedronConstantContractionForceField.h",
  "doc": "Applies constant contraction force along fiber directions in tetrahedral meshes",
  "inherits": [
    "BaseTetraForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_contractionStress",
      "type": "Real",
      "xmlname": "contractionStress",
      "help": "Stress magnitude"
    }
  ],
  "links": [],
  "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": "computeContractionStress",
      "return_type": "Matrix3",
      "params": [
        {
          "name": "deformationGradient",
          "type": "const Matrix3 &"
        },
        {
          "name": "fiberDir",
          "type": "const Coord &"
        },
        {
          "name": "stressMagnitude",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "action_potential",
      "return_type": "double",
      "params": [
        {
          "name": "time",
          "type": "double"
        },
        {
          "name": "depol",
          "type": "double"
        },
        {
          "name": "apd",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TetrahedronConstantContractionForceField` is a force field in the SOFA framework designed to apply constant contraction forces along predefined fiber directions within tetrahedral meshes. This component extends the `BaseTetraForceField`, inheriting its mechanisms for handling tetrahedral elements. It primarily operates by computing and applying a contraction stress tensor based on the deformation gradient and specified fiber directions, which are defined per tetrahedron.\n\n### Role in SOFA Ecosystem\nThis force field is particularly useful for simulating active tissue contractions, such as those seen in muscle or cardiac simulations. The component facilitates the modeling of anisotropic mechanical properties, where forces act preferentially along specific fiber orientations within the mesh.\n\n### Interactions with Other Components\n- **BaseTetraForceField**: Inheriting from this base class, `TetrahedronConstantContractionForceField` leverages its methods and data structures for tetrahedral topology management and mechanical computations. It utilizes inherited links such as `d_fiberDirections` to access fiber direction information.\n- **Mechanical State Management**: The component integrates with the SOFA core’s mechanical framework, interfacing through virtual methods like `init()` and `addForce()`. These methods ensure that the force field can be properly initialized and applied during each simulation step.\n\n### Practical Usage Guidance\nTo use this component effectively:\n- **Stress Magnitude (`contractionStress`)**: Set the desired magnitude of the contraction stress using the `d_contractionStress` data field. This determines how strongly the force will act along the fiber directions.\n- **Fiber Directions**: Ensure that fiber direction information is correctly provided for each tetrahedron, as this dictates the orientation and distribution of applied forces.\n\nThe component requires a valid mesh topology to function, where each tetrahedron has associated fiber directions. The `addForce` method computes deformation gradients and contraction stresses at runtime, applying forces accordingly.",
  "maths": "The `TetrahedronConstantContractionForceField` applies constant contraction forces along predefined fiber directions within tetrahedral meshes, simulating active tissue contractions. The mathematical and physical details are as follows:\n\n### Governing Equations and Operators\n- **Stress Tensor**: The component computes a stress tensor \\(\\sigma\\) that is aligned with the fiber direction.\n  \n  Given the fiber direction vector \\(\\mathbf{d}\\), the contraction stress tensor \\(\\sigma\\) is defined as:\n  \n  \n\begin{align*}\n    \n    \\sigma = \\alpha (\\mathbf{d} \\otimes \\mathbf{d})\n    \n\tag{1}\n\n\text{where } \\alpha \\text{ is the stress magnitude specified by `contractionStress` and } \\mathbf{d} \\text{ is a unit vector.}\n  \n\\end{align*}\n\n- **Contraction Force**: The force applied to each node in a tetrahedron is calculated from the deformation gradient \\(F\\) and the contraction stress tensor \\(\\sigma\\).\n  \n  For each tetrahedral element, the deformation gradient \\(F = \\nabla x\\) is computed based on current positions. The force contribution to node \\(j\\) in the tetrahedron is given by:\n\n\begin{align*}\n    f_j &= - F (\\sigma \\cdot N_j) V_0 \\\\\n  \n   & = - F (\\alpha (\\mathbf{d} \\otimes \\mathbf{d}) \\cdot N_j) V_0 \n\tag{2}\n\n\\end{align*}\n\nwhere:\n- \\(N_j\\): Shape function derivatives for node \\(j\\).\n- \\(V_0\\): Rest volume of the tetrahedron.\n\n### Constitutive or Kinematic Laws Involved\nThe contraction stress tensor is computed based on a constant stress magnitude and predefined fiber directions. The stress tensor in equation (1) represents an isotropic distribution along the fiber direction with strength proportional to \\(\\alpha\\).\n\n### Role in FEM Pipeline\n- **Assembly Phase**: This component contributes to the internal forces vector \\(\boldsymbol{f}_{\text{int}}\\). It does this by computing and adding contributions to each node based on tetrahedral deformations and fiber directions.\n- **Time Integration**: The force field is applied at each time step during implicit integration, contributing to the residual equation.\n\n### Numerical Methods or Discretization Choices\nThe component uses a weak formulation of the internal forces by calculating contributions from each tetrahedron in the mesh. It leverages shape functions and deformation gradients for accurate force computation.\n\n### Integration into Variational/Lagrangian Mechanics Framework\nIn the context of Lagrangian mechanics, this component modifies the potential energy term \\(V\\) by adding an active contraction contribution. The force applied is consistent with minimizing the total potential energy while respecting the fiber direction constraints.\n\n\begin{align*}\n    V_{\text{contraction}} = - \boldsymbol{f}_{\text{int}} \\cdot u \\\\\n  \n   = - (\\sum_j f_j) \\cdot u \\\\\n  \n   = \\alpha \\left( \\sum_j F (\\mathbf{d} \\otimes \\mathbf{d}) N_j V_0 \\right) \\cdot u\n\tag{3}\n\n\\end{align*}\n\nwhere \\(\boldsymbol{f}_{\text{int}}\\) is the sum of forces from all tetrahedra, and \\(u\\) represents displacements.\n",
  "abstract": "The `TetrahedronConstantContractionForceField` applies constant contraction forces along predefined fiber directions in tetrahedral meshes, simulating active tissue contractions.",
  "sheet": "# TetrahedronConstantContractionForceField\n\n## Overview\n\nThis component is a force field that extends `BaseTetraForceField`, applying constant contraction forces along predefined fiber directions within tetrahedral meshes. It integrates with the SOFA mechanical framework through methods like `init()` and `addForce()`. This component is particularly useful for simulating active tissue contractions, such as those seen in muscle or cardiac simulations.\n\n## Mathematical Model\n\nThe `TetrahedronConstantContractionForceField` computes a contraction stress tensor \\\\(\\sigma\\\\) aligned with the fiber direction vector \\\\(\\mathbf{d}\\\\). The stress tensor is defined as:\n\n\\[ \\sigma = \\alpha (\\mathbf{d} \\otimes \\mathbf{d}) \\]\n\nwhere \\\\(\\alpha\\\\) is the contraction stress magnitude specified by `contractionStress`.\n\nThe force applied to each node in a tetrahedron is calculated from the deformation gradient \\\\(F\\\\) and the contraction stress tensor \\\\(\\sigma\\\\):\n\n\\[ f_j = - F (\\alpha (\\mathbf{d} \\otimes \\mathbf{d}) \\cdot N_j) V_0 \\]\n\nwhere:\n- \\\\(N_j\\\\): Shape function derivatives for node \\\\(j\\\\).\n- \\\\(V_0\\\\): Rest volume of the tetrahedron.\n\n## Parameters and Data\n\nThe significant parameter exposed by this component is `contractionStress`, which controls the magnitude of the contraction stress applied along fiber directions. The type is `Real` (floating-point number).\n\n| Parameter | Type   | Default Value |\n|-----------|--------|---------------|\n| `contractionStress` | Real  | N/A         |\n\n## Dependencies and Connections\n\nThis component inherits from `BaseTetraForceField`, leveraging its methods for tetrahedral topology management and mechanical computations. It requires fiber direction information provided by the mesh, which dictates the orientation and distribution of applied forces."
}