Data Fields

Links

Methods

{
  "name": "TriangularQuadraticSpringsForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/TriangularQuadraticSpringsForceField.h",
  "doc": "Quadratic Springs on a Triangular Mesh.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_initialPoints",
      "type": "VecCoord",
      "xmlname": "initialPoints",
      "help": "Initial Position"
    },
    {
      "name": "d_poissonRatio",
      "type": "Real",
      "xmlname": "poissonRatio",
      "help": "Poisson ratio in Hooke's law"
    },
    {
      "name": "d_youngModulus",
      "type": "Real",
      "xmlname": "youngModulus",
      "help": "Young modulus in Hooke's law"
    },
    {
      "name": "d_dampingRatio",
      "type": "Real",
      "xmlname": "dampingRatio",
      "help": "Ratio damping/stiffness"
    },
    {
      "name": "d_useAngularSprings",
      "type": "bool",
      "xmlname": "useAngularSprings",
      "help": "If Angular Springs should be used or not"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "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": "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": "includeAngularSprings",
      "return_type": "void",
      "params": [
        {
          "name": "useAngularSprings",
          "type": "const bool"
        }
      ],
      "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": "applyEdgeCreation",
      "return_type": "void",
      "params": [
        {
          "name": "edgeIndex",
          "type": "int"
        },
        {
          "name": "ei",
          "type": "EdgeRestInformation &"
        },
        {
          "name": "edge",
          "type": "const core::topology::BaseMeshTopology::Edge &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyTriangleCreation",
      "return_type": "void",
      "params": [
        {
          "name": "triangleIndex",
          "type": "int"
        },
        {
          "name": "tinfo",
          "type": "TriangleRestInformation &"
        },
        {
          "name": "triangle",
          "type": "const core::topology::BaseMeshTopology::Triangle &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyTriangleDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "triangleIndex",
          "type": "int"
        },
        {
          "name": "tinfo",
          "type": "TriangleRestInformation &"
        }
      ],
      "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 `TriangularQuadraticSpringsForceField` is a SOFA component designed to simulate forces within a triangular mesh using quadratic springs. It extends the `ForceField` class and operates on solid mechanics components, specifically dealing with spring-based forces for deformable objects represented by triangles. This component supports elastic and angular stiffness computations based on Hooke's law, employing material properties such as Young’s modulus and Poisson ratio to calculate forces.\n\n### Interactions:\nThe `TriangularQuadraticSpringsForceField` interacts with other SOFA components through its API, particularly with the topology container linked via the `l_topology` field. It requires a mesh topology for defining edges and triangles. The component computes forces between nodes based on their initial positions (`d_initialPoints`) and current displacements.\n\n### Data Fields:\nThe key data fields include:\n- **Initial Position** (`initialPoints`): Defines the initial position of the points in the mesh.\n- **Poisson Ratio** (`poissonRatio`): Material property used in Hooke's law to compute elastic forces.\n- **Young Modulus** (`youngModulus`): Another material property for calculating stiffness.\n- **Damping Ratio** (`dampingRatio`): Controls damping relative to stiffness.\n- **Angular Springs Usage** (`useAngularSprings`): Boolean flag indicating whether angular springs are used in the simulation.\n\n### Methods:\nThe component provides methods like `addForce`, `addDForce`, and `getPotentialEnergy`. These methods handle force computation, derivative forces, and potential energy calculation respectively. The `updateLameCoefficients` method updates Lamé coefficients based on provided material properties.\n\n### Practical Usage:\nTo use this component effectively, users should provide a topology container that defines the mesh structure (edges and triangles). Initial positions of nodes must be specified to establish rest lengths for edges and angles within triangles. Material parameters such as Young’s modulus and Poisson ratio need to be set appropriately to model the desired elastic behavior.",
  "maths": "**Mathematical and Physical Description**\n\n### Governing Equations and Operators:\n\nThe `TriangularQuadraticSpringsForceField` implements force contributions to a finite element simulation using quadratic springs on triangular elements. It computes internal forces due to both edge elongation and angular deformation, based on the material properties such as Young's modulus ($E$) and Poisson ratio ($\\nu$).\n\n#### Edge Forces:\nThe force contribution for each edge in the mesh is computed by considering deviations from the rest length of the edge. The edge elongation $e_i$ for an edge between nodes $j$ and $k$ is given by:\n\\[ e_i = \\lVert x_j - x_k \\rVert - L_{rest} \\]\nwhere $L_{rest}$ is the initial rest length, and $x_j$, $x_k$ are the current positions of the nodes.\nThe force contribution for each edge can be written as:\n\\[ f^{edge}_{j,k} = k_e (e_i) \\frac{x_j - x_k}{\\lVert x_j - x_k \\rVert} \\]\nwhere $k_e$ is the stiffness coefficient, and $\\lVert . \\rVert$ denotes the norm.\n\n#### Angular Forces:\nThe angular spring forces are computed based on the angles formed by the edges of each triangle in the mesh. The angular deviation for a given angle $\\theta_i$ (formed between edges $i,j$ and $j,k$) is calculated, and the force contribution due to this angle is given by:\n\\[ f^{angle}_{ijk} = k_{\\theta}(\\theta - \\theta_{rest}) \\cdot N_{ijk} \\]\nwhere $k_{\\theta}$ is the angular stiffness coefficient, $N_{ijk}$ are the normal vectors, and $\\theta_{rest}$ is the rest angle.\n\n### Constitutive or Kinematic Laws:\nThe component uses Hooke's law to compute elastic forces. The Lamé coefficients ($\\lambda$, $\\mu$) are derived from Young’s modulus ($E$) and Poisson ratio ($\\nu$):\n\\[ \\lambda = \\frac{E\\nu}{(1+\\nu)(1-2\\nu)}, \\quad \\mu = \\frac{E}{2(1+\\nu)} \\]\nThe stiffness matrix for each triangle is derived based on these Lamé coefficients and the current geometry of the mesh.\n\n### Role in FEM Pipeline:\nThis component contributes to the assembly phase by computing internal forces (both edge elongation and angular deformation) for each element. It also participates in the nonlinear solution process, where it provides contributions to the residual force vector $R$ during the Newton-Raphson iterations.\n\n#### Assembly Phase:\nThe internal forces are assembled into the global system of equations through the `addForce` method, which computes contributions from edge and angular springs and adds them to the global force vector. The tangent stiffness matrix is computed in the `addDForce` method by evaluating derivatives with respect to displacements.\n\n#### Nonlinear Solution Phase:\nThe residual forces $R(x)$ include contributions from this component's internal forces, which are updated during each Newton-Raphson iteration.\n\n### Numerical Methods and Discretization Choices:\nThe discretization involves quadratic springs on triangular elements. The stiffness matrix for the edge and angular spring contributions is computed using finite differences or directly based on material properties and geometric information provided by the mesh topology.\n\n#### Edge Stiffness Matrix:\nThe edge stiffness matrix $K_{edge}$ is derived from the rest length of edges and current lengths, which are updated during each time step. The damping term is also included to account for energy dissipation due to deformation.\n\n#### Angular Stiffness Matrix:\nThe angular stiffness matrix $K_{angle}$ accounts for angular deviations within triangles and includes terms that reflect both edge elongation and angular changes.\n\n### Variational Mechanics Framework:\nThis component fits into the broader variational mechanics framework by contributing to the weak form of the governing equations through internal force contributions. The forces computed here are consistent with Lagrangian mechanics, where they contribute to the potential energy term in the Lagrangian $\\mathcal{L} = T - V$.\n\n#### Weak Form:\nThe weak form for this component involves integrating over the triangular elements and considering test functions that enforce equilibrium conditions. The stiffness contributions from edges and angles are integrated into the global system of equations, ensuring consistency with variational principles.",
  "abstract": "The `TriangularQuadraticSpringsForceField` simulates quadratic spring forces within a triangular mesh, computing internal forces due to edge elongation and angular deformation based on material properties such as Young’s modulus and Poisson ratio.",
  "sheet": "# TriangularQuadraticSpringsForceField\n\n## Overview\nThe `TriangularQuadraticSpringsForceField` is a SOFA component that simulates quadratic spring forces within a triangular mesh. It extends the `ForceField` class to compute internal forces due to edge elongation and angular deformation based on material properties such as Young’s modulus and Poisson ratio.\n\n## Mathematical Model\nThe force contributions for each edge in the mesh are computed by considering deviations from the rest length of the edge. The edge elongation $e_i$ for an edge between nodes $j$ and $k$ is given by:\n\\[ e_i = \\lVert x_j - x_k \\rVert - L_{rest} \\]\nwhere $L_{rest}$ is the initial rest length, and $x_j$, $x_k$ are the current positions of the nodes. The force contribution for each edge can be written as:\n\\[ f^{edge}_{j,k} = k_e (e_i) \\frac{x_j - x_k}{\\lVert x_j - x_k \\rVert} \\]\nwhere $k_e$ is the stiffness coefficient, and $\\lVert . \\rVert$ denotes the norm.\n\nThe angular spring forces are computed based on the angles formed by the edges of each triangle in the mesh. The angular deviation for a given angle $\\theta_i$ (formed between edges $i,j$ and $j,k$) is calculated, and the force contribution due to this angle is given by:\n\\[ f^{angle}_{ijk} = k_{\\theta}(\\theta - \\theta_{rest}) \\cdot N_{ijk} \\]\nwhere $k_{\\theta}$ is the angular stiffness coefficient, $N_{ijk}$ are the normal vectors, and $\\theta_{rest}$ is the rest angle.\n\nThe Lamé coefficients ($\\lambda$, $\\mu$) are derived from Young’s modulus ($E$) and Poisson ratio ($\\nu$):\n\\[ \\lambda = \\frac{E\\nu}{(1+\\nu)(1-2\\nu)}, \\quad \\mu = \\frac{E}{2(1+\\nu)} \\]\nThe stiffness matrix for each triangle is derived based on these Lamé coefficients and the current geometry of the mesh.\n\n## Parameters and Data\nThe significant data fields exposed by this component include:\n- **Initial Position** (`initialPoints`): Defines the initial position of the points in the mesh.\n- **Poisson Ratio** (`poissonRatio`): Material property used in Hooke's law to compute elastic forces.\n- **Young Modulus** (`youngModulus`): Another material property for calculating stiffness.\n- **Damping Ratio** (`dampingRatio`): Controls damping relative to stiffness.\n- **Angular Springs Usage** (`useAngularSprings`): Boolean flag indicating whether angular springs are used in the simulation."
}