Data Fields

Links

Methods

{
  "name": "TriangularBiquadraticSpringsForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/TriangularBiquadraticSpringsForceField.h",
  "doc": "Biquadratic 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"
    },
    {
      "name": "d_compressible",
      "type": "bool",
      "xmlname": "compressible",
      "help": "If additional energy penalizing compressibility should be used"
    },
    {
      "name": "d_stiffnessMatrixRegularizationWeight",
      "type": "Real",
      "xmlname": "matrixRegularization",
      "help": "Regularization of the Stiffnes Matrix (between 0 and 1)"
    }
  ],
  "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": "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 `TriangularBiquadraticSpringsForceField` is a force field component in the SOFA framework designed to simulate mechanical behavior on triangular meshes using biquadratic springs. This component inherits from `core::behavior::ForceField`, which means it contributes forces and potentially energy computations for deformable solid mechanics simulations.\n\n### Role and Purpose\nThe primary role of this component is to enforce stiffness and elastic properties in a mesh made up of triangles by modeling each triangle with biquadratic springs. It supports linear elasticity through Hooke's law, where the Young’s modulus and Poisson’s ratio define material behavior. The component also manages angular stiffness and can account for compressibility effects.\n\n### Interactions with Other SOFA Components\n- **Topology Link (`topology`)**: This component requires a link to a `BaseMeshTopology` object to access mesh information such as vertices, edges, and triangles. It uses this topology data to initialize and update internal edge and triangle rest state information.\n- **Mechanical State**: The force computation methods interact with the mechanical state of the simulation to retrieve positions (`x`), velocities (`v`), forces (`f`), and apply computed forces back into the system.\n\n### Data Fields\n- `initialPoints`: Stores the initial resting position of vertices in the mesh.\n- `poissonRatio`: Sets the Poisson’s ratio for Hooke's law, influencing material elasticity.\n- `youngModulus`: Defines the Young’s modulus, determining stiffness.\n- `dampingRatio`: Controls the damping relative to the stiffness coefficient.\n- `useAngularSprings`: Enables or disables angular springs that enforce angles between edges within triangles.\n- `compressible`: Indicates whether additional energy should penalize compressibility of elements in the mesh.\n- `matrixRegularization`: Affects regularization weight for the stiffness matrix, providing control over stability and robustness under large deformations.\n\n### Practical Usage Guidance\nTo use this component effectively:\n1. Connect a valid `BaseMeshTopology` to ensure correct access to the triangular mesh topology.\n2. Adjust the `youngModulus`, `poissonRatio`, and other material parameters according to desired physical behavior.\n3. Optionally enable or disable angular springs through `useAngularSprings` based on whether angular stiffness should be enforced.\n4. Manage compressibility behavior by setting `compressible` appropriately, particularly if elements may undergo large deformations.",
  "maths": "\n## Governing Equations\n\nThe `TriangularBiquadraticSpringsForceField` contributes to the global FEM simulation by providing internal forces and potential energy based on biquadratic springs for each triangle in a mesh. The main equations and operators involved are as follows:\n\n### Internal Force Contributions\n\n1. **Linear Elastic Forces: (Edge Springs)**\n   - **Displacement Vector**: $\\mathbf{dp} = \\mathbf{x}_{v0} - \\mathbf{x}_{v1}$ where $\\mathbf{x}_{v0}, \\mathbf{x}_{v1}$ are positions of the vertices connected by an edge.\n   - **Force Contribution**: \n     \n     \\[ \\mathbf{f}_e = \\mathbf{dp} \\times einfo.stiffness \\times (\\text{currentSquareLength} - \\text{restSquareLength}) + \\eta \\cdot \\dot{\\mathbf{dp}} \\]\n\n   where $einfo$ represents edge information, and $\\eta$ is the damping ratio.\n\n2. **Angular Stiffness Contribution**: (If enabled)\n   - **Stiffness Matrix Calculation**: \n     \n     The stiffness matrix for each triangle involves contributions from both edge lengths and angles between edges:\n     \\[ m_{u,v} = d\\mathbf{p}_k[u]d\\mathbf{p}_k[v]val2 + d\\mathbf{p}_j[u]d\\mathbf{p}_i[v]valk - d\\mathbf{p}_j[u]d\\mathbf{p}_k[v]vali + d\\mathbf{p}_k[u]d\\mathbf{p}_i[v]valj \\]\n\n   where $m_{u,v}$ is an element of the stiffness matrix, and various terms are computed based on the edge lengths and Poisson's ratio.\n\n### Potential Energy\n\n- **Potential Energy Calculation**: \n  The potential energy for the system includes contributions from both elongation and compressibility:\n  \\[ U = \\frac{1}{2} \\sum_{e \\in edges} k_e (\\mathbf{dp}_e^T \\cdot \\mathbf{dp}_e - l_0^2)^2 + \\frac{1}{2} \\sum_{t \\in triangles} \\mu J (J-1)^3 \\]\n\n  where $k_e$ is the edge stiffness, $\\mathbf{dp}_e$ is the current displacement vector for edge $e$, and $l_0^2$ is its rest length squared. The second term accounts for compressibility.\n\n### Constitutive Laws\n\n- **Linear Elasticity**: \n  - **Stiffness Calculation from Lamé Parameters**:\n    \\[ \\lambda = \\frac{E\\nu}{(1+\\nu)(1-2\\nu)} \\quad , \\quad \\mu = \\frac{E(1-\\nu)}{(1+\\nu)(1-2\\nu)} \\]\n  where $E$ is the Young's modulus, and $\\nu$ is the Poisson’s ratio.\n\n### Kinematic Laws\n\nThe component handles both linear and angular kinematics for each triangle in the mesh:\n\n- **Linear Displacement**: \n  - Each edge stores its rest length and current displacement vector from which forces are computed.\n\n- **Angular Stiffness** (if enabled): \n  - The angles between edges within triangles are modeled with additional stiffness terms that contribute to the overall force calculations, ensuring angular stability.\n\n### Numerical Methods and Discretization Choices\n\nThe component discretizes forces and potential energy contributions over triangular elements using biquadratic springs. It updates these values at each time step based on the current deformation state of the mesh:\n\n1. **Force Computation**: \n   - The `addForce` method computes the internal forces based on displacements from rest positions, incorporating both edge lengths and angular stiffness contributions.\n2. **Damping Matrix Construction**:\n   - Although not explicitly stated in the description provided, damping matrices are computed to stabilize simulations with dynamic effects.\n\n### Role in the Global FEM Pipeline\n\n- **Assembly**: \n  The internal forces calculated contribute to the global force vector $\\mathbf{f}_{int}$ used in solving the nonlinear system of equations during time integration. Similarly, potential energy contributions feed into the overall energetic balance of the simulated system.\n- **Time Integration**: \n  Forces are computed and applied at each time step, contributing to updating nodal positions and velocities.\n\n### Constraint Handling\n\nWhile no explicit constraint handling is described in this component, it relies on the broader SOFA framework's mechanisms for enforcing boundary conditions and constraints such as Dirichlet or Neumann boundaries through its interaction with other components like topological data structures and mechanical state management.\n",
  "abstract": "The `TriangularBiquadraticSpringsForceField` simulates mechanical behavior on triangular meshes using biquadratic springs, enforcing stiffness and elastic properties through Hooke's law with options for angular stiffness and compressibility effects.",
  "sheet": "# TriangularBiquadraticSpringsForceField\n\n## Overview\nThe `TriangularBiquadraticSpringsForceField` is a force field component that simulates mechanical behavior on triangular meshes using biquadratic springs. It enforces linear elasticity through Hooke's law, with options to include angular stiffness and compressibility effects.\n\n## Mathematical Model\n### Internal Force Contributions\n1. **Linear Elastic Forces (Edge Springs)**\n   - **Displacement Vector**: \\(\\mathbf{dp} = \\mathbf{x}_{v0} - \\mathbf{x}_{v1}\\) where \\(\\mathbf{x}_{v0}, \\mathbf{x}_{v1}\\) are positions of the vertices connected by an edge.\n   - **Force Contribution**:\n     \n     \\[ \\mathbf{f}_e = \\mathbf{dp} \\times einfo.stiffness \\times (\\text{currentSquareLength} - \\text{restSquareLength}) + \\eta \\cdot \\dot{\\mathbf{dp}} \\]\n\n   where \\(einfo\\) represents edge information, and \\(\\eta\\) is the damping ratio.\n\n2. **Angular Stiffness Contribution** (If enabled)\n   - **Stiffness Matrix Calculation**: \n     The stiffness matrix for each triangle involves contributions from both edge lengths and angles between edges:\n     \\[ m_{u,v} = d\\mathbf{p}_k[u]d\\mathbf{p}_k[v]val2 + d\\mathbf{p}_j[u]d\\mathbf{p}_i[v]valk - d\\mathbf{p}_j[u]d\\mathbf{p}_k[v]vali + d\\mathbf{p}_k[u]d\\mathbf{p}_i[v]valj \\]\n\n   where \\(m_{u,v}\\) is an element of the stiffness matrix, and various terms are computed based on the edge lengths and Poisson's ratio.\n\n### Potential Energy\n- **Potential Energy Calculation**: \nThe potential energy for the system includes contributions from both elongation and compressibility:\n\\[ U = \\frac{1}{2} \\sum_{e \\in edges} k_e (\\mathbf{dp}_e^T \\cdot \\mathbf{dp}_e - l_0^2)^2 + \\frac{1}{2} \\sum_{t \\in triangles} \\mu J (J-1)^3 \\]\n\nwhere \\(k_e\\) is the edge stiffness, \\(\\mathbf{dp}_e\\) is the current displacement vector for edge \\(e\\), and \\(l_0^2\\) is its rest length squared. The second term accounts for compressibility.\n\n### Constitutive Laws\n- **Linear Elasticity**: \n  - **Stiffness Calculation from Lamé Parameters**:\n    \\[ \\lambda = \\frac{E\\nu}{(1+\\nu)(1-2\\nu)} \\quad , \\quad \\mu = \\frac{E(1-\\nu)}{(1+\\nu)(1-2\\nu)} \\]\n  where \\(E\\) is the Young's modulus, and \\(\\nu\\) is the Poisson’s ratio.\n\n## Parameters and Data\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `initialPoints` | VecCoord | Initial Position of vertices in the mesh. |\n| `poissonRatio` | Real | Poisson's ratio for Hooke's law, influencing material elasticity. Default: Not specified. |\n| `youngModulus` | Real | Young’s modulus determining stiffness. Default: Not specified. |\n| `dampingRatio` | Real | Ratio damping/stiffness. Default: Not specified. |\n| `useAngularSprings` | bool | Enables or disables angular springs that enforce angles between edges within triangles. Default: Not specified. |\n| `compressible` | bool | Indicates whether additional energy should penalize compressibility of elements in the mesh. Default: Not specified. |\n| `matrixRegularization` | Real | Regularization weight for the stiffness matrix, providing control over stability and robustness under large deformations. Default: Not specified. |\n\n## Dependencies and Connections\n- **Topology Link (`topology`)**: This component requires a link to a `BaseMeshTopology` object to access mesh information such as vertices, edges, and triangles."
}