Data Fields

Links

Methods

{
  "name": "PolynomialRestShapeSpringsForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/PolynomialRestShapeSpringsForceField.h",
  "doc": "Simple elastic springs applied to given degrees of freedom between their current and rest shape position.\n\nThis class describes a polynomial elastic springs ForceField between DOFs positions and rest positions.\nSprings are applied to given degrees of freedom between their current positions and their rest shape positions.\nAn external MechanicalState reference can also be passed to the ForceField as rest shape position.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_polynomialStiffness",
      "type": "VecReal",
      "xmlname": "polynomialStiffness",
      "help": "coefficients for all spring polynomials"
    },
    {
      "name": "d_recomputeIndices",
      "type": "bool",
      "xmlname": "recompute_indices",
      "help": "Recompute indices (should be false for BBOX)"
    },
    {
      "name": "d_drawSpring",
      "type": "bool",
      "xmlname": "drawSpring",
      "help": "draw Spring"
    },
    {
      "name": "d_springColor",
      "type": "sofa::type::RGBAColor",
      "xmlname": "springColor",
      "help": "spring color"
    },
    {
      "name": "d_showIndicesScale",
      "type": "float",
      "xmlname": "showIndicesScale",
      "help": "Scale for indices display. (default=0.02)"
    },
    {
      "name": "d_zeroLength",
      "type": "VecReal",
      "xmlname": "initialLength",
      "help": "initial virtual length of the spring"
    },
    {
      "name": "d_smoothShift",
      "type": "Real",
      "xmlname": "smoothShift",
      "help": "denominator correction adding shift value"
    },
    {
      "name": "d_smoothScale",
      "type": "Real",
      "xmlname": "smoothScale",
      "help": "denominator correction adding scale"
    }
  ],
  "links": [
    {
      "name": "d_restMState",
      "target": "MechanicalState<DataTypes>",
      "kind": "single",
      "xmlname": "external_rest_shape",
      "help": "rest_shape can be defined by the position of an external Mechanical State"
    }
  ],
  "methods": [
    {
      "name": "init",
      "description": "Initializes internal structures and computes polynomial stiffness coefficients and rest shapes from input parameters.",
      "returnType": "void"
    },
    {
      "name": "addForce",
      "description": "Computes and adds force contributions for each spring to the overall force computation in a simulation step.",
      "returnType": "void"
    },
    {
      "name": "PolynomialValue",
      "description": "Evaluates the polynomial function that defines the stiffness of the springs based on strain. This is used to compute forces.",
      "returnType": "Real"
    },
    {
      "name": "draw",
      "description": "Renders the spring connections in a visualization tool, allowing for visual inspection of the force field within a simulation scene.",
      "returnType": "void"
    },
    {
      "name": "addKToMatrix",
      "description": "Contributes to global stiffness matrices by adding entries corresponding to each spring's stiffness. This is crucial for implicit integration methods.",
      "returnType": "void"
    }
  ],
  "title": "PolynomialRestShapeSpringsForceField",
  "description": "This class implements a polynomial rest shape spring force field in the SOFA physics engine. It allows for the creation of springs with stiffness that can vary based on a polynomial function, which is useful for simulating more complex and realistic mechanical behaviors.",
  "details": "The PolynomialRestShapeSpringsForceField extends the generic SolidMechanicalState class and implements various interfaces required by the SOFA framework to integrate within a simulation pipeline. It allows users to define springs with varying stiffness based on polynomial functions of strain, which can be useful for simulating more complex mechanical behaviors in soft tissues or other materials.\n\nThe force field uses rest shapes defined by a set of points and computes forces between current positions and these rest positions. The stiffness of the spring is not constant but depends on the strain through a polynomial function, where the coefficients of the polynomial are user-defined.\n\nKey functionalities include:\n- **Initialization**: Sets up internal structures for storing spring data and polynomial coefficients.\n- **Force Computation**: Computes forces based on the distance between current and rest positions, using the polynomial stiffness to determine force magnitude.\n- **Derivative Computation**: Calculates derivatives of the force with respect to displacements for use in numerical integration methods like implicit Euler.\n- **Drawing**: Visualizes springs and their connections within a simulation scene.\n- **Matrix Contributions**: Provides contributions to global stiffness matrices used in solving systems of equations that describe the physical behavior of the simulated objects.",
  "parameters": [
    {
      "name": "springStiffness",
      "type": "Real",
      "description": "The stiffness coefficient for each degree of the polynomial. This is a vector where each element represents the stiffness at a different order (degree) in the polynomial function."
    },
    {
      "name": "restShapePosition",
      "type": "VecCoord",
      "description": "The positions defining the rest shape that the spring force field will pull towards. These are typically set to the initial configuration of the object being simulated."
    },
    {
      "name": "drawSpring",
      "type": "bool",
      "description": "A flag to enable or disable drawing of springs in the visualizer."
    },
    {
      "name": "points",
      "type": "VecIndex",
      "description": "The indices defining which pairs of points are connected by the springs. Each spring connects two points, and this parameter defines these connections."
    }
  ],
  "usageExample": {
    "description": "Below is an example of how this component might be used in a SOFA scene file.",
    "exampleCode": "// Define the polynomial rest shape springs\n<RestShapeSpringsForceField>\n\t<numberValues='3' values='10 20 5'/>\n\t<points>0 1, 1 2</points>\n\t<drawSpring>true</drawSpring>\n</RestShapeSpringsForceField>"
  },
  "maths": "<h3>Governing Equations and Operators</h3>\n\n<p>The <code>PolynomialRestShapeSpringsForceField</code> class in the SOFA framework implements elastic springs with polynomial stiffness between given degrees of freedom (DOFs) and their rest shape positions. This component contributes to the following aspects of the FEM simulation pipeline:</p>\n<ul>\n<li><strong>Internal Force Field Contribution ($f_{int}$)</strong>: It computes the internal forces due to the spring deformation based on polynomial stiffness terms.</li>\n<li><strong>Tangent Stiffness Matrix Contribution ($K$)</strong>: It assembles the tangent stiffness matrix that represents the derivative of the internal force with respect to nodal displacements.</li>\n</ul>\n\n<h4>Internal Force Field</h4>\n<p>The internal forces due to the springs are computed using the following polynomial stiffness terms:</p>\n\\[\n f_{int}(x) = -k(x - x_0)\n\\]\nwhere:\n<ul>\n<li>$x$ is the current position of a DOF.</li>\n<li>$x_0$ is the rest shape position (from an external or default mechanical state).</li>\n<li>$k$ is the polynomial stiffness term, which can vary based on the strain ($\\varepsilon = \\frac{|x - x_0|}{L_0}$), where $L_0$ is the initial virtual length of the spring.</li>\n</ul>\nThe polynomial stiffness term is given by:\n\\[\nk(\\varepsilon) = a_1 + a_2 \\varepsilon^2 + a_3 \\varepsilon^3 + \\dots\n\\]\nwhere $a_i$ are the coefficients of the polynomial, specified in <code>d_polynomialStiffness</code>.\n\n<h4>Tangent Stiffness Matrix Contribution ($K$)</h4>\nThe tangent stiffness matrix is derived from the derivative of the internal force with respect to nodal displacements. For each spring:\n\\[\n K_{ij} = - \\frac{\\partial f_{int}(x)}{\\partial x_i}\n\\]\nThis involves computing derivatives based on the polynomial form and modifying the stiffness matrix accordingly.\n\n<h4>Numerical Methods and Discretization</h4>\nThe <code>PolynomialRestShapeSpringsForceField</code> class discretizes the internal forces and tangent stiffness contributions for each spring, based on the current positions of the DOFs and their rest shape positions. The polynomial terms are computed explicitly using a set of coefficients provided by the user.\n\n<h4>Constraint Handling and Mapping</h4>\nThe component handles constraints through the use of an external mechanical state <code>d_restMState</code>, allowing for defining rest shape positions externally if needed.\n\n<p>This class fits into the broader variational / Lagrangian mechanics framework by contributing to the internal force field and tangent stiffness matrix, which are essential components in the overall energy minimization process. The polynomial springs provide a more flexible and realistic mechanical behavior compared to simple linear springs.</p>\n",
  "abstract": "Implements polynomial elastic springs between DOFs and their rest shape positions, contributing to internal forces and tangent stiffness matrix in SOFA simulations.",
  "sheet": "# PolynomialRestShapeSpringsForceField\n\n## Overview\nThe `PolynomialRestShapeSpringsForceField` class implements elastic springs with polynomial stiffness terms between given degrees of freedom (DOFs) and their rest shape positions. This component is part of the SolidMechanics.Spring module and contributes to the internal forces and tangent stiffness matrix in SOFA simulations.\n\n## Mathematical Model\nThe internal forces due to the springs are computed using polynomial stiffness terms:\n\begin{equation}\n f_{int}(x) = -k(x - x_0)\n\\end{equation}\nwhere $x$ is the current position of a DOF, $x_0$ is the rest shape position, and $k$ is the polynomial stiffness term given by:\n\begin{equation}\nk(\\varepsilon) = a_1 + a_2 \\varepsilon^2 + a_3 \\varepsilon^3 + \\dots\n\\end{equation}\nwhere $a_i$ are the coefficients of the polynomial, specified in `d_polynomialStiffness`, and $\\varepsilon = \\frac{|x - x_0|}{L_0}$ is the strain with $L_0$ being the initial virtual length of the spring.\nThe tangent stiffness matrix contribution ($K$) is derived from the derivative of the internal force with respect to nodal displacements:\n\begin{equation}\n K_{ij} = - \\frac{\\partial f_{int}(x)}{\\partial x_i}\n\\end{equation}\n\n## Parameters and Data\n- **d_polynomialStiffness**: coefficients for all spring polynomials (`VecReal`)\n- **d_recomputeIndices**: recomputes indices (should be false for BBOX) (`bool`, default: `false`)\n- **d_drawSpring**: draw Spring (`bool`, default: `false`)\n- **d_springColor**: spring color (`sofa::type::RGBAColor`, default: `0.8, 0.8, 0.8, 1.0`)\n- **d_showIndicesScale**: scale for indices display (default=0.02) (`float`, default: `0.02`)\n- **d_zeroLength**: initial virtual length of the spring (`VecReal`)\n- **d_smoothShift**: denominator correction adding shift value (`Real`, default: `1e-6`)\n- **d_smoothScale**: denominator correction adding scale (`Real`, default: `1.0`)"
}