Data Fields

Links

Methods

{
  "name": "TriangularTensorMassForceField",
  "namespace": "sofa::component::solidmechanics::tensormass",
  "module": "Sofa.Component.SolidMechanics.TensorMass",
  "include": "sofa/component/solidmechanics/tensormass/TriangularTensorMassForceField.h",
  "doc": "Linear Elastic Membrane on a Triangular Mesh",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_poissonRatio",
      "type": "Real",
      "xmlname": "poissonRatio",
      "help": "Poisson ratio in Hooke's law"
    },
    {
      "name": "d_youngModulus",
      "type": "Real",
      "xmlname": "youngModulus",
      "help": "Young's modulus in Hooke's law"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "applyEdgeCreation",
      "return_type": "void",
      "params": [
        {
          "name": "edgeIndex",
          "type": "int"
        },
        {
          "name": "",
          "type": "EdgeRestInformation &"
        },
        {
          "name": "e",
          "type": "const core::topology::BaseMeshTopology::Edge &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyTriangleCreation",
      "return_type": "void",
      "params": [
        {
          "name": "triangleAdded",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyTriangleDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "triangleRemoved",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "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": "d_f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "d_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": "d_df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "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": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLambda",
      "return_type": "Real",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMu",
      "return_type": "Real",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setYoungModulus",
      "return_type": "void",
      "params": [
        {
          "name": "modulus",
          "type": "const Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPoissonRatio",
      "return_type": "void",
      "params": [
        {
          "name": "ratio",
          "type": "const Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateLameCoefficients",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getEdgeInfo",
      "return_type": "int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TriangularTensorMassForceField` is a SOFA component designed for simulating linear elastic membranes on triangular meshes. It inherits from the `core::behavior::ForceField` class and is part of the Solid Mechanics module within the Tensor Mass framework.\n\n### Role in SOFA Ecosystem:\nThe component calculates forces based on Hooke's law, incorporating Young’s modulus (`youngModulus`) and Poisson ratio (`poissonRatio`). It supports the deformation of triangular meshes by defining edge stiffness matrices for each edge in the topology. The internal state includes edge information stored as `EdgeRestInformation`, which contains the stiffness matrix.\n\n### Interactions with Other Components:\nThe component interacts primarily through its link to a `BaseMeshTopology` container, ensuring that it has access to the mesh structure needed to calculate forces and update topological changes such as triangle additions or removals. This interaction is facilitated via callbacks on topology events (e.g., TRIANGLESADDED, TRIANGLESREMOVED).\n\n### Practical Usage Guidance:\nThe component requires setting `youngModulus` and `poissonRatio` for defining material properties of the elastic membrane. It also needs to be linked to a `BaseMeshTopology`, either explicitly through configuration or by default selecting one from the current context. The force calculation is based on the initial rest positions of vertices, which are stored internally.\n\n### Data Fields:\nThe component provides data fields for setting physical parameters such as `poissonRatio` and `youngModulus`. Additionally, it maintains internal state information like `_initialPoints`, edge stiffness matrices (`d_edgeInfo`), and Lame coefficients (`lambda` and `mu`).",
  "maths": "The `TriangularTensorMassForceField` is designed to simulate linear elastic membranes on triangular meshes. It implements the governing equations for a membrane based on Hooke's law, with Young's modulus (λ) and Poisson ratio (μ). The component calculates internal forces and stiffness matrices for each edge in the mesh topology.\n\n### Governing Equations:\n\n1. **Hooke's Law**:\n   - λ (Young's Modulus) and μ (Poisson Ratio) are used to define material properties.\n   - These parameters are converted into Lame coefficients (λ, μ) via the following relations:\n     \\[\\lambda = \\frac{E ν}{(1+ν)(1-2ν)}\\]\n     \\[μ = \\frac{E}{2(1+ν)}\\]\n   - Where:\n     - E: Young's Modulus\n     - ν: Poisson Ratio\n\n2. **Stiffness Matrix** (ℓ):\n   - Each edge in the mesh is associated with a stiffness matrix, \\(ℓ\\), which encodes how the edges resist deformation.\n   - The stiffness matrix for an edge between vertices δ and ε is calculated as follows:\n     \\[ℓ = λ (δ π₀ - δ π₁) ⨢ (ε π₀ - ε π₁) +\n     μ (δ π₁ - δ π₂) ⨢ (ε π₁ - ε π₂)\\]\n     Where \\(π_i = (x_{i+1} - x_{i+2}) / 4A\\) with area A computed using Heron's formula.\n\n### Internal Forces:\n   The internal forces are computed for each edge based on the displacement of vertices from their rest positions. Specifically, if \\(u_i = x_i - x^0_i\\) is the displacement at vertex △i and \\(Δx_{△▼} = u_{▼} - u_△\\), then:\n   \\[f_i + ℓ * (Δx_{△▼})\\]\n\n### Numerical Methods and Discretization Choices:\n- The stiffness matrix is computed for each edge in the mesh, reflecting local material properties (Young's modulus and Poisson ratio).\n- Triangles are used to represent the membrane, and topological changes (additions or removals) trigger updates of these matrices.\n\n### Constraint Handling:\n   Constraints are implicitly handled by updating the stiffness matrix when topology changes occur. The component supports callbacks for handling triangle additions/removals which update edge information accordingly.\n\n### Role in Global FEM Pipeline:\n- **Mesh Generation**: The mesh is provided via a `BaseMeshTopology` link, enabling the component to access vertex and edge data.\n- **Weak Form Derivation**: While not explicitly shown here, the internal forces are derived from a weak form of Hooke's law for linear elasticity over each triangular element.\n- **Assembly Phase**: The stiffness matrices for edges are assembled into the global system during initialization and updated upon topological changes.\n\n### Constraints:\n   This component does not directly handle explicit constraints but relies on the overall SOFA framework to manage any additional boundary conditions or constraints applied to the mesh topology.",
  "abstract": "The `TriangularTensorMassForceField` simulates linear elastic membranes on triangular meshes using Hooke's law with Young’s modulus and Poisson ratio parameters. It interacts with a `BaseMeshTopology` container to manage mesh structure and topological changes.",
  "sheet": "\n# TriangularTensorMassForceField\n\n## Overview\nThe `TriangularTensorMassForceField` is designed for simulating linear elastic membranes on triangular meshes within the SOFA framework. It inherits from the `core::behavior::ForceField` class, requiring Young’s modulus (`youngModulus`) and Poisson ratio (`poissonRatio`) parameters to define material properties. The component interacts with a `BaseMeshTopology` container to access mesh structure and update topological changes.\n\n## Mathematical Model\nThe governing equations for the membrane are based on Hooke's law, incorporating Young’s modulus (λ) and Poisson ratio (μ). These parameters are converted into Lame coefficients (λ, μ) via:\n\\[ \\lambda = \\frac{E ν}{(1+ν)(1-2ν)} \\]\n\\[ μ = \\frac{E}{2(1+ν)} \\]\nwhere E is Young's modulus and ν is the Poisson ratio.\n\nThe stiffness matrix for each edge in the mesh topology is given by:\n\\[ ℓ = λ (δ π₀ - δ π₁) ⨢ (ε π₀ - ε π₁) + μ (δ π₁ - δ π₂) ⨢ (ε π₁ - ε π₂) \\]\nwhere \\(π_i = (x_{i+1} - x_{i+2}) / 4A\\), and A is the area computed using Heron's formula.\n\nInternal forces are computed for each edge based on vertex displacements from rest positions:\n\\[ f_i + ℓ * (Δx_{△▼}) \\]\nwhere \\(u_i = x_i - x^0_i\\) is the displacement at vertex △i and \\(Δx_{△▼} = u_{▼} - u_△\\).\n\n## Parameters and Data\nThe component exposes the following significant data fields:\n- `poissonRatio`: Poisson ratio in Hooke's law (type: Real)\n- `youngModulus`: Young’s modulus in Hooke's law (type: Real)\n\nThese parameters control the material properties of the elastic membrane.\n\n## Dependencies and Connections\nThe component requires a link to a `BaseMeshTopology` container, which provides access to the mesh structure needed for force calculations and topological updates. It interacts with this topology through callbacks on events such as triangle additions or removals."
}