Data Fields

Links

Methods

{
  "name": "MeshSpringForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/MeshSpringForceField.h",
  "doc": "Spring force field acting along the edges of a mesh.",
  "inherits": [
    "SpringForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_linesStiffness",
      "type": "Real",
      "xmlname": "linesStiffness",
      "help": "Stiffness for the Lines"
    },
    {
      "name": "d_linesDamping",
      "type": "Real",
      "xmlname": "linesDamping",
      "help": "Damping for the Lines"
    },
    {
      "name": "d_trianglesStiffness",
      "type": "Real",
      "xmlname": "trianglesStiffness",
      "help": "Stiffness for the Triangles"
    },
    {
      "name": "d_trianglesDamping",
      "type": "Real",
      "xmlname": "trianglesDamping",
      "help": "Damping for the Triangles"
    },
    {
      "name": "d_quadsStiffness",
      "type": "Real",
      "xmlname": "quadsStiffness",
      "help": "Stiffness for the Quads"
    },
    {
      "name": "d_quadsDamping",
      "type": "Real",
      "xmlname": "quadsDamping",
      "help": "Damping for the Quads"
    },
    {
      "name": "d_tetrahedraStiffness",
      "type": "Real",
      "xmlname": "tetrahedraStiffness",
      "help": "Stiffness for the Tetrahedra"
    },
    {
      "name": "d_tetrahedraDamping",
      "type": "Real",
      "xmlname": "tetrahedraDamping",
      "help": "Damping for the Tetrahedra"
    },
    {
      "name": "d_cubesStiffness",
      "type": "Real",
      "xmlname": "cubesStiffness",
      "help": "Stiffness for the Cubes"
    },
    {
      "name": "d_cubesDamping",
      "type": "Real",
      "xmlname": "cubesDamping",
      "help": "Damping for the Cubes"
    },
    {
      "name": "d_noCompression",
      "type": "bool",
      "xmlname": "noCompression",
      "help": "Only consider elongation"
    },
    {
      "name": "d_drawMinElongationRange",
      "type": "Real",
      "xmlname": "drawMinElongationRange",
      "help": "Min range of elongation (red eongation - blue neutral - green compression)"
    },
    {
      "name": "d_drawMaxElongationRange",
      "type": "Real",
      "xmlname": "drawMaxElongationRange",
      "help": "Max range of elongation (red eongation - blue neutral - green compression)"
    },
    {
      "name": "d_drawSpringSize",
      "type": "Real",
      "xmlname": "drawSpringSize",
      "help": "Size of drawed lines"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "addSpring",
      "return_type": "void",
      "params": [
        {
          "name": "sset",
          "type": "int &"
        },
        {
          "name": "m1",
          "type": "int"
        },
        {
          "name": "m2",
          "type": "int"
        },
        {
          "name": "stiffness",
          "type": "Real"
        },
        {
          "name": "damping",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLinesStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTrianglesStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getQuadsStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTetrahedraStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCubesStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setLinesStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTrianglesStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setQuadsStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTetrahedraStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCubesStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getLinesDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTrianglesDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getQuadsDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getTetrahedraDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getCubesDamping",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setLinesDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTrianglesDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setQuadsDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTetrahedraDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCubesDamping",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "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"
    }
  ],
  "description": "The `MeshSpringForceField` is a force field in SOFA that applies spring forces along the edges of a mesh, inheriting from the `SpringForceField`. It operates on different types of elements within the mesh including lines, triangles, quads, tetrahedra, and cubes. Each type of element can have its own stiffness and damping parameters, which control how strongly the springs resist deformation and dissipate energy, respectively.\n\nThe component interacts with a `BaseMeshTopology` topology container to access the connectivity information for different mesh elements. It uses this data to create spring forces along edges defined by these elements. This setup is common in solid mechanics simulations where linear or nonlinear elasticity needs to be modeled through simple force-displacement relationships.\n\nThe `addSpring` method adds a new spring between two nodes, while various getter and setter methods allow for setting and retrieving the stiffness and damping parameters. The `init` method initializes the component by creating springs according to the provided topology data, and the `draw` method visualizes these forces using color-coded lines based on their elongation.\n\nPractical usage involves specifying stiffness and damping values appropriate for the simulation needs, linking it to a topology container, and ensuring that the mechanical states (`mstate1`, `mstate2`) are correctly defined. The optional data field `noCompression` can be set to true if only elongation forces should be considered.",
  "maths": "The **MeshSpringForceField** in the SOFA framework is a force field that simulates spring forces acting along the edges of a mesh. It contributes to the internal force vector $\\mathbf{f}_{int}$, which represents the elastic and damping forces within the deformed solid. The governing equations for this component can be described as follows:\n\n### Governing Equations\n\n#### Internal Force Contribution ($\\mathbf{f}_{int}$)\n\nThe MeshSpringForceField computes the internal force contributions from springs defined along the edges of mesh elements such as lines, triangles, quads, tetrahedra, and cubes. The internal forces are given by:\n\n\begin{equation}\n    \\mathbf{f}^{e}_{int}(\\mathbf{x}) = -k_s (\\|\\mathbf{l}\\|_0 - \\|\\mathbf{l}\\|) \\frac{\\mathbf{l}}{\\|\\mathbf{l}\\|} + c_d \\dot{\\mathbf{l}},\n\tag{1}\n\text{(Hooke's Law and Damping)}\n\text{\nwhere \n- $k_s$ is the stiffness coefficient for a given edge,\n- $\text{c}_d$ is the damping coefficient for that edge,\n- $\text{l}$ is the length of the edge defined by two nodes, and\n- $\text{l}_0$ is the rest length (initial undeformed length) of that edge.\n}\n\tag{2}\n\text{(Elongation Term)}\n\text{\nIf the component is configured with `noCompression` set to true, forces are only considered for elongations. This means the internal force vector will be zero if $\text{l} \\\\< \\text{l}_0$. }\n\n### Constitutive Laws and Kinematic Measures\n\nThe spring model used by **MeshSpringForceField** is a simple linear elastic relationship based on Hooke's Law, which states that the force exerted by a spring is proportional to its elongation or compression from an equilibrium position. The damping term is also linearly related to the relative velocity of the nodes.\n\nThe strain measure used here is effectively the ratio of the current edge length $\text{l}$ to its rest length $\text{l}_0$. For small deformations, this can be approximated by a linear strain measure, but it remains applicable for large deformations as well since it directly measures the change in distance between nodes.\n\n### Role in FEM Pipeline\n\nIn the broader context of the FEM pipeline, **MeshSpringForceField** contributes to the internal force vector $\textbf{f}_{int}$ during the assembly phase. This component:\n\n1. **Assembly**: Adds spring forces to the global system equations based on connectivity information from a `BaseMeshTopology` topology container.\n2. **Time Integration**: Participates in the implicit time integration scheme by contributing to the residual $\textbf{R}(x_{n+1})$, where $\textbf{x}_{n+1}$ represents the unknown nodal displacements at the next timestep.\n3. **Nonlinear Solution**: During the Newton-Raphson iterations, it contributes to the Jacobian matrix $\\mathcal{J}$ which linearizes the system around the current estimate of the solution.\n4. **Linear Solve**: Contributes to the tangent stiffness matrix $K(x)$ derived from the internal force vector $f^{e}_{int}(x)$.\n\n### Numerical Methods and Discretization Choices\n\nThe **MeshSpringForceField** discretizes the spring forces along the edges of mesh elements, where each edge is modeled as a simple linear spring with optional damping. The stiffness and damping coefficients can be set differently for different types of mesh elements (lines, triangles, quads, tetrahedra, cubes).\n\nThe `init` method initializes these springs by accessing connectivity data from the topology container. It ensures that springs are only added if their nodes lie within a specified local range, which is useful for parallel computations.\n\n### Variational and Lagrangian Mechanics Framework\n\nWithin the variational mechanics framework of SOFA, **MeshSpringForceField** can be seen as providing a discrete approximation to the potential energy $V$ in the Lagrangian formulation:\n\begin{equation}\n    \\mathcal{L}(q,\\dot q) = T(q,\\dot q) - V(q),\n\tag{3}\n\text{(Lagrangian Formulation)}\n\nwhere $V(q)$ includes the potential energy stored in the springs. The internal force vector $\textbf{f}_{int}$ is derived from this potential energy via the principle of virtual work, ensuring consistency with variational principles.\n\n### Summary\n\nIn summary, **MeshSpringForceField** implements a simple but effective model for simulating elastic and dissipative forces within deformable solids by discretizing the solid into springs along mesh edges. It is grounded in Lagrangian mechanics, contributes to the global force vector $\textbf{f}_{int}$, and plays a crucial role in the nonlinear solution process of FEM simulations.",
  "abstract": "The `MeshSpringForceField` applies spring forces along the edges of a mesh, contributing to elastic and damping forces within deformable solids. It interacts with a topology container for connectivity information.",
  "sheet": "# MeshSpringForceField\n\n## Overview\n\nThe `MeshSpringForceField` is a force field that simulates spring forces acting along the edges of a mesh. It inherits from the `SpringForceField` and operates on different types of elements within the mesh, including lines, triangles, quads, tetrahedra, and cubes. Each type of element can have its own stiffness and damping parameters to control how strongly the springs resist deformation and dissipate energy.\n\n## Mathematical Model\n\nThe `MeshSpringForceField` computes internal forces based on Hooke's Law and linear damping. The governing equations for this component are:\n\n\\[ \\mathbf{f}^{e}_{int}(\\mathbf{x}) = -k_s (\\|\\mathbf{l}\\|_0 - \\|\\mathbf{l}\\|) \\frac{\\mathbf{l}}{\\|\\mathbf{l}\\|} + c_d \\dot{\\mathbf{l}}, \\]\n\nwhere:\n- $k_s$ is the stiffness coefficient for a given edge,\n- $c_d$ is the damping coefficient for that edge,\n- $\\mathbf{l}$ is the length of the edge defined by two nodes, and\n- $\\|\\mathbf{l}\\|_0$ is the rest length (initial undeformed length) of that edge.\n\nIf `noCompression` is set to true, forces are only considered for elongations. This means the internal force vector will be zero if $\\|\\mathbf{l}\\| < \\|\\mathbf{l}_0\\|$.\n\n## Parameters and Data\n\nThe significant data fields exposed by the component include:\n\n- `linesStiffness`: Stiffness for lines (default: not specified).\n- `linesDamping`: Damping for lines (default: not specified).\n- `trianglesStiffness`: Stiffness for triangles (default: not specified).\n- `trianglesDamping`: Damping for triangles (default: not specified).\n- `quadsStiffness`: Stiffness for quads (default: not specified).\n- `quadsDamping`: Damping for quads (default: not specified).\n- `tetrahedraStiffness`: Stiffness for tetrahedra (default: not specified).\n- `tetrahedraDamping`: Damping for tetrahedra (default: not specified).\n- `cubesStiffness`: Stiffness for cubes (default: not specified).\n- `cubesDamping`: Damping for cubes (default: not specified).\n- `noCompression`: Only consider elongation (default: false).\n- `drawMinElongationRange`: Min range of elongation (red elongation - blue neutral - green compression) (default: not specified).\n- `drawMaxElongationRange`: Max range of elongation (red elongation - blue neutral - green compression) (default: not specified).\n- `drawSpringSize`: Size of drawn lines (default: not specified).\n\n## Dependencies and Connections\n\nThe component requires a `BaseMeshTopology` topology container to access connectivity information for different mesh elements. It typically exchanges data with mechanical state components (`mstate1`, `mstate2`) to define the nodal positions and velocities."
}