Data Fields

Links

Methods

{
  "name": "TriangularBendingSprings",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/TriangularBendingSprings.h",
  "doc": "Springs added to a triangular mesh to prevent bending\n\nBending springs added between vertices of triangles sharing a common edge.\nThe springs connect the vertices not belonging to the common edge. It compresses when the surface bends along the common edge.\nNote: This TriangularBendingSprings only support manifold triangulation. I.e an edge can only by adjacent to maximum 2 triangles.\nIf more than 2 triangles are connected to an edge, only one spring will be created (the first 2 triangles encountered during initialisation phase)\n@author The SOFA team </www.sofa-framework.org>",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_ks",
      "type": "Real",
      "xmlname": "stiffness",
      "help": "uniform stiffness for the all springs"
    },
    {
      "name": "d_kd",
      "type": "Real",
      "xmlname": "damping",
      "help": "uniform damping for the all springs"
    },
    {
      "name": "d_showSprings",
      "type": "bool",
      "xmlname": "showSprings",
      "help": "option to draw springs"
    }
  ],
  "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": "ei",
          "type": "EdgeInformation &"
        },
        {
          "name": "",
          "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": "applyPointDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "pointIndices",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyPointRenumbering",
      "return_type": "void",
      "params": [
        {
          "name": "pointToRenumber",
          "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": "reinit",
      "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": "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": "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": "getKs",
      "return_type": "Real",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setKs",
      "return_type": "void",
      "params": [
        {
          "name": "ks",
          "type": "const Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getKd",
      "return_type": "Real",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setKd",
      "return_type": "void",
      "params": [
        {
          "name": "kd",
          "type": "const Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAccumulatedPotentialEnergy",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "d_x",
          "type": "const DataVecCoord &"
        }
      ],
      "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": "public"
    }
  ],
  "description": "The `TriangularBendingSprings` component in SOFA is designed to add bending springs between vertices of triangles sharing a common edge, preventing excessive bending deformation along that edge. It inherits from the `ForceField` class and operates on triangular mesh topologies. The springs connect pairs of vertices not belonging to the shared edge and apply forces based on their displacement relative to their rest lengths. This component is particularly useful for simulating thin shell deformations where maintaining surface stiffness is essential.\n\nIt interacts with other SOFA components through its `init` and `reinit` methods, which set up internal data structures like the `d_edgeInfo` container that stores information about each edge's spring properties. The `applyTriangleCreation`, `applyEdgeCreation`, `applyPointDestruction`, and similar functions ensure the springs are correctly initialized or updated when mesh topology changes occur.\n\nThe component has several key data fields:\n- **stiffness (`d_ks`)**: Uniform stiffness for all springs, which can be set via the `setKs` method.\n- **damping (`d_kd`)**: Uniform damping factor for all springs, adjustable through the `setKd` method.\n- **showSprings (`d_showSprings`)**: Boolean flag to enable drawing of the springs in the visualization pipeline.\n\nFor practical usage, users should link this component with a compatible mesh topology and set appropriate stiffness and damping values. It is important to note that the component supports only manifold triangulations where an edge can connect at most two triangles.",
  "maths": "The `TriangularBendingSprings` component in the SOFA framework implements bending springs between vertices of triangles sharing a common edge. The primary goal is to prevent excessive bending deformation along that edge, which is crucial for simulating thin shell deformations where maintaining surface stiffness is essential.\n\n### Governing Equations and Operators\n\n1. **Spring Force**:\n   Each spring connects two vertices not belonging to the shared edge of two adjacent triangles. The force applied by each spring can be expressed as follows:\n   \n   Let \\(\\mathbf{x}_a\\) and \\(\\mathbf{x}_b\\) denote the positions of the two vertices connected by a spring, with rest length \\(l_0\\). The elongation \\(ε\\) is given by:\n   \n   \\[ ε = \\frac{||Δ x|| - l_0}{l_0} \\]\n   where \\(Δ x = \\mathbf{x}_b - \\mathbf{x}_a\\).\n\n   The spring force \\(F_s\\) is then:\n   \n   \\[ F_s = k_s (ε l_0 + v_d τ) \\]\n   where \\(k_s\\) is the stiffness coefficient, and \\(v_d\\) is the relative velocity between the vertices. The damping factor \\(τ\\) is given by:\n   \n   \\[ τ = (\\mathbf{v}_b - \\mathbf{v}_a) \\cdot \\frac{Δ x}{||Δ x||} \\]\n\n2. **Potential Energy**:\n   The potential energy associated with each spring is given by the standard Hooke's law expression for a linear spring:\n   \n   \\[ U = \\frac{1}{2} k_s (ε l_0)^2 \\]\n\n### Constitutive and Kinematic Laws\n\n- **Strain Measure**: The strain measure used here is the relative displacement between two connected vertices, normalized by the rest length.\n- **Stress Tensor**: The spring force represents a simple 1D stress that acts along the line connecting the two vertices.\n- **Spring Properties**:\n   - **Uniform Stiffness**: All springs have a uniform stiffness \\(k_s\\), set via `setKs` method.\n   - **Uniform Damping**: Each spring has a uniform damping factor \\(k_d\\), set via `setKd` method.\n\n### Role in the Global FEM Pipeline\n\n1. **Assembly Phase**:\n   The component contributes to the global force vector and stiffness matrix by adding contributions from each spring in the mesh. Specifically, it adds forces to the global force vector \\(δ φ\\) and updates the stiffness matrix \\(K\\).\n\n2. **Time Integration**:\n   The `addForce` method is called during time integration to compute the internal forces due to bending springs at each time step.\n\n3. **Nonlinear Solve**:\n   During the nonlinear solve, this component contributes to the residual and tangent stiffness matrix through the `buildStiffnessMatrix` method.\n\n4. **Linear Solve**:\n   The `addDForce` method is used in the linear solve phase for incremental changes, updating the global force vector with damping contributions.\n\n5. **Constraint Handling**: This component does not directly handle constraints but interacts with the broader constraint handling system by updating internal data structures when topology changes occur (e.g., triangle creation/destruction).\n\n6. **Mapping**:\n   The `applyPointRenumbering` method ensures that vertex indices are updated correctly during renumbering operations.\n\n### Numerical Methods and Discretization Choices\n\n- **Triangular Mesh Topology**: The component operates on a triangular mesh where each spring connects vertices of triangles sharing an edge. It supports only manifold triangulations (edges connected to at most two triangles).\n- **Uniform Stiffness and Damping**: All springs have uniform stiffness \\(k_s\\) and damping \\(k_d\\), which are set uniformly across the entire system.\n\n### Integration into Variational / Lagrangian Mechanics Framework\n\nThe `TriangularBendingSprings` component fits into the broader variational mechanics framework by contributing to the potential energy of the system. Specifically, each spring contributes a quadratic term to the total potential energy, which is minimized during the solution process. The force and stiffness contributions are derived from this potential energy functional using variational calculus.\n\nOverall, `TriangularBendingSprings` provides a mechanism for maintaining surface stiffness in thin shell deformations by preventing excessive bending along edges shared between triangles.",
  "abstract": "The `TriangularBendingSprings` component adds bending springs between vertices of triangles sharing a common edge to prevent excessive deformation along that edge, contributing to surface stiffness in thin shell simulations.",
  "sheet": "# TriangularBendingSprings\n\n## Overview\n\nThe `TriangularBendingSprings` component is designed to add bending springs between vertices of triangles sharing a common edge. It prevents excessive bending deformation along the shared edges and supports only manifold triangulations where an edge can connect at most two triangles.\n\n## Mathematical Model\n\nEach spring connects two vertices not belonging to the shared edge, applying forces based on their displacement relative to rest lengths. The force applied by each spring is given by:\n\nLet \\(\\mathbf{x}_a\\) and \\(\\mathbf{x}_b\\) denote the positions of the two vertices connected by a spring with rest length \\(l_0\\). The elongation \\(ε\\) is defined as:\n\n\\[ ε = \\frac{||Δ x|| - l_0}{l_0} \\]\nwhere \\(Δ x = \\mathbf{x}_b - \\mathbf{x}_a\\).\n\nThe spring force \\(F_s\\) is then:\n\n\\[ F_s = k_s (ε l_0 + v_d τ) \\]\nwhere \\(k_s\\) is the stiffness coefficient, and \\(v_d\\) is the relative velocity between the vertices. The damping factor \\(τ\\) is given by:\n\n\\[ τ = (\\mathbf{v}_b - \\mathbf{v}_a) \\cdot \\frac{Δ x}{||Δ x||} \\]\n\nThe potential energy associated with each spring is given by the standard Hooke's law expression for a linear spring:\n\n\\[ U = \\frac{1}{2} k_s (ε l_0)^2 \\]\n\n## Parameters and Data\n\n- **stiffness (`d_ks`)**: Uniform stiffness for all springs, set via the `setKs` method.\n- **damping (`d_kd`)**: Uniform damping factor for all springs, adjustable through the `setKd` method.\n- **showSprings (`d_showSprings`)**: Boolean flag to enable drawing of the springs in the visualization pipeline.\n\n## Dependencies and Connections\n\nThe component requires a compatible mesh topology linked via the `topology` field. It interacts with other SOFA components through its initialization methods (`init`, `reinit`) and updates internal data structures when mesh topology changes occur (e.g., triangle creation/destruction).\n"
}