Data Fields

Links

Methods

{
  "name": "TetrahedronDiffusionFEMForceField",
  "namespace": "sofa::component::diffusion",
  "module": "Sofa.Component.Diffusion",
  "include": "sofa/component/diffusion/TetrahedronDiffusionFEMForceField.h",
  "doc": "Isotropic or anisotropic diffusion on Tetrahedral Meshes.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec1Types"
  ],
  "data_fields": [
    {
      "name": "d_constantDiffusionCoefficient",
      "type": "Real",
      "xmlname": "constantDiffusionCoefficient",
      "help": "Constant diffusion coefficient"
    },
    {
      "name": "d_transverseAnisotropyRatio",
      "type": "Real",
      "xmlname": "anisotropyRatio",
      "help": "Anisotropy ratio (r²>1).\\n Default is 1.0 = isotropy."
    },
    {
      "name": "d_drawConduc",
      "type": "bool",
      "xmlname": "drawConduc",
      "help": "To display conductivity map."
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    },
    {
      "name": "l_mecaObj",
      "target": "MechObject",
      "kind": "single",
      "xmlname": "mecaObj",
      "help": "link to the 3D mechanical MechanicalObject"
    }
  ],
  "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": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "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": "dF",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dX",
          "type": "const DataVecCoord &"
        },
        {
          "name": "",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "dF",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dX",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "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": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDiffusionCoefficient",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTetraDiffusionCoefficient",
      "return_type": "Real",
      "params": [
        {
          "name": "i",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDiffusionCoefficient",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "const Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDiffusionCoefficient",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeEdgeDiffusionCoefficient",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TetrahedronDiffusionFEMForceField` is a SOFA component designed for simulating isotropic or anisotropic diffusion on tetrahedral meshes. It inherits from the `ForceField` class and operates within the `sofa::component::diffusion` namespace.\n\n### Role in SOFA Ecosystem\nThis component allows users to model the diffusion process, often used in computational biomechanics for simulating heat transfer or other physical phenomena in soft tissue simulations. It supports both constant and variable diffusion coefficients across tetrahedra, and can handle anisotropic diffusion by specifying transverse anisotropy ratios.\n\n### Interactions with Other Components\nThe `TetrahedronDiffusionFEMForceField` interacts with the following components:\n- **BaseMeshTopology**: Linked to provide topological information about the mesh (tetrahedral elements).\n- **MechanicalObject**: Provides mechanical data for the tetrahedral mesh, including positions and possibly velocities or forces.\n\n### Practical Usage Guidance\nThis component can be configured using the following data fields:\n- `constantDiffusionCoefficient`: Sets a uniform diffusion coefficient across all tetrahedra (default value is 1.0).\n- `anisotropyRatio`: Specifies anisotropic diffusion with a transverse ratio greater than 1.0 (default isotropic).\n- `drawConduc`: Enables visualization of the conductivity map.\n\nThe component must be linked to the mesh topology and mechanical object within the scene graph for proper operation. The method `init` sets up internal data structures, ensuring that the diffusion coefficients are correctly initialized according to the input values or default settings. \n\n### Data Fields\n- `d_constantDiffusionCoefficient`: Real value representing a uniform diffusion coefficient.\n- `d_transverseAnisotropyRatio`: Real value for anisotropic ratio; defaults to 1.0 (isotropic).\n- `d_drawConduc`: Boolean flag enabling visualization of the conductivity map.\n\n### Methods and Functions\nKey methods include:\n- `init()`: Initializes internal structures based on the provided diffusion coefficients and mesh topology.\n- `addForce()`, `addDForce()`: Adds forces due to diffusion into the global force vector, accounting for displacement or velocity changes respectively.\n- `buildStiffnessMatrix()` and `getPotentialEnergy()`: Build stiffness matrix and compute potential energy of the system respectively.\n- `draw()`: Visualizes conductivity if `d_drawConduc` is enabled.",
  "maths": "The `TetrahedronDiffusionFEMForceField` component in the SOFA framework is designed to simulate isotropic or anisotropic diffusion processes on tetrahedral meshes. The key mathematical and physical concepts involved include the computation of diffusion forces, stiffness matrices, and potential energy contributions for a given mesh topology.\n\n### Governing Equations and Operators\n\nThe primary equation governing the diffusion process can be expressed in terms of the diffusion coefficient \\( D \\) and the Laplacian operator \\( \nabla^2 \\):\n\n\\[\n\\frac{φ}{δt} = D \nabla^2 φ,\n\\]\nwhere \\( φ \\) represents the scalar quantity being diffused.\n\nThe component implements this equation in a finite element context, where the diffusion force is computed at each edge of the tetrahedral mesh. The diffusion coefficient can be isotropic (constant throughout the domain) or anisotropic (varying across different directions).\n\n#### Diffusion Coefficients\n\n1. **Constant Diffusion**:\n   - A uniform diffusion coefficient \\( D_0 \\) is applied to all tetrahedra.\n   \n2. **Anisotropic Diffusion**:\n   - The anisotropy ratio \\( r^2 > 1 \\) and a transverse direction vector determine the effective diffusion coefficients along different edges of the mesh.\n\n### Discretization and Assembly\n\nThe component discretizes the domain into tetrahedral elements, with each element contributing to the global stiffness matrix. The `addForce()` method calculates the force contributions due to diffusion for each edge in the mesh:\n\n\\[\nf_i = D_{ij} (u_j - u_i),\n\\]\nwhere \\( f_i \\) is the force at node \\( i \\), and \\( D_{ij} \\) is the diffusion coefficient along the edge connecting nodes \\( i \\) and \\( j \\).\n\nThe stiffness matrix \\( K \\) for each tetrahedron is built using the `buildStiffnessMatrix()` method, contributing to the global system of equations:\n\n\\[\nK_{ij} = D_{ij},\n\\]\nwhere \\( K_{ij} \\) represents the contribution of edge diffusion coefficients to the overall stiffness matrix.\n\n### Role in FEM Pipeline\n\n- **Assembly**: The component contributes to the global force vector and stiffness matrix through methods such as `addForce()` and `buildStiffnessMatrix()`. These contributions are aggregated into the larger simulation system for solving the nonlinear equations of motion.\n\n- **Time Integration**: Although not explicitly detailed, this component is implicitly used within an implicit time integration scheme (e.g., Backward Euler) to update nodal positions over discrete time steps.\n\n- **Nonlinear Solve**: The diffusion forces are incorporated into the residual and Jacobian calculations during nonlinear solution phases using Newton–Raphson iterations or similar methods.\n\n### Constitutive Laws and Kinematics\n\nThe component primarily handles the computation of diffusion coefficients and forces, which can be seen as a type of constitutive law in the context of diffusive processes. The kinematic aspect is handled through the displacement data provided by the `MechanicalObject` linked to this component.\n\n### Numerical Methods and Discretization Choices\n\n- **Spatial Discretization**: Tetrahedral elements are used, and diffusion coefficients are computed at each edge connecting tetrahedra nodes.\n\n- **Integration**: Gauss quadrature is not explicitly mentioned but can be inferred as a standard practice for numerical integration over the edges of tetrahedral elements.\n\n### Variational/Lagrangian Mechanics Framework\n\nThe component fits into a broader variational and Lagrangian mechanics framework by providing contributions to the potential energy and stiffness matrix, which are key components in deriving the equations of motion via the principle of minimum potential energy. The diffusion forces contribute to the total internal force field, thus influencing the overall dynamics of the simulated system.\n\nIn summary, `TetrahedronDiffusionFEMForceField` implements diffusion processes on tetrahedral meshes within a variational mechanics framework, contributing to the global stiffness matrix and force vector during assembly and time integration steps.",
  "abstract": "The `TetrahedronDiffusionFEMForceField` simulates isotropic or anisotropic diffusion on tetrahedral meshes by computing diffusion forces and stiffness matrices based on specified diffusion coefficients and mesh topology.",
  "sheet": "# TetrahedronDiffusionFEMForceField\n\n## Overview\n\nThe `TetrahedronDiffusionFEMForceField` is a component for simulating isotropic or anisotropic diffusion processes on tetrahedral meshes within the SOFA framework. It inherits from the `ForceField` class and interacts with mesh topology and mechanical objects to compute diffusion forces and stiffness matrices.\n\n## Mathematical Model\n\nThe primary equation governing the diffusion process can be expressed as:\n\n\begin{equation}\n  \\frac{ϕ}{δt} = D ∇^2 ϕ,\n\\end{equation}\nwhere ϕ represents the scalar quantity being diffused, and D is the diffusion coefficient.\n\nThe component discretizes the domain into tetrahedral elements and computes the diffusion force at each edge:\n\n\begin{equation}\n  f_i = D_{ij} (u_j - u_i),\n\\end{equation}\nwhere $f_i$ is the force at node i, and $D_{ij}$ is the diffusion coefficient along the edge connecting nodes i and j.\n\nThe stiffness matrix K for each tetrahedron is built using:\n\n\begin{equation}\n  K_{ij} = D_{ij},\n\\end{equation}\nwhere $K_{ij}$ represents the contribution of edge diffusion coefficients to the overall stiffness matrix.\n\n## Parameters and Data\n\n- **constantDiffusionCoefficient**: Real value representing a uniform diffusion coefficient (default is 1.0).\n- **anisotropyRatio**: Real value for anisotropic ratio; defaults to 1.0 (isotropic).\n- **drawConduc**: Boolean flag enabling visualization of the conductivity map.\n\n## Dependencies and Connections\n\nThe component requires links to:\n- **BaseMeshTopology**: Provides topological information about the mesh.\n- **MechanicalObject**: Provides mechanical data for the tetrahedral mesh, including positions and possibly velocities or forces.\n\n## Practical Notes\n\nThis component must be properly initialized with diffusion coefficients and linked to the appropriate topology and mechanical objects. The `init` method sets up internal structures based on these inputs. Visualization of conductivity can be enabled via the `drawConduc` parameter."
}