Data Fields

Methods

{
  "name": "PolynomialSpringsForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/PolynomialSpringsForceField.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",
  "inherits": [
    "PairInteractionForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_firstObjectPoints",
      "type": "VecIndex",
      "xmlname": "firstObjectPoints",
      "help": "points related to the first object"
    },
    {
      "name": "d_secondObjectPoints",
      "type": "VecIndex",
      "xmlname": "secondObjectPoints",
      "help": "points related to the second object"
    },
    {
      "name": "d_polynomialStiffness",
      "type": "VecReal",
      "xmlname": "polynomialStiffness",
      "help": "coefficients for all spring polynomials"
    },
    {
      "name": "d_computeZeroLength",
      "type": "int",
      "xmlname": "computeZeroLength",
      "help": "flag to compute initial length for springs"
    },
    {
      "name": "d_zeroLength",
      "type": "VecReal",
      "xmlname": "zeroLength",
      "help": "initial length for springs"
    },
    {
      "name": "d_recomputeIndices",
      "type": "bool",
      "xmlname": "recompute_indices",
      "help": "Recompute indices (should be false for BBOX)"
    },
    {
      "name": "d_compressible",
      "type": "bool",
      "xmlname": "compressible",
      "help": "Indicates if object compresses without any reaction force"
    },
    {
      "name": "d_drawMode",
      "type": "int",
      "xmlname": "drawMode",
      "help": "The way springs will be drawn:\\n- 0: Line\\n- 1:Cylinder\\n- 2: Arrow"
    },
    {
      "name": "d_showArrowSize",
      "type": "float",
      "xmlname": "showArrowSize",
      "help": "size of the axis"
    },
    {
      "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)"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "recomputeIndices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "ComputeJacobian",
      "return_type": "void",
      "params": [
        {
          "name": "stiffnessIndex",
          "type": "unsigned int"
        },
        {
          "name": "springIndex",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "PolynomialValue",
      "return_type": "double",
      "params": [
        {
          "name": "springIndex",
          "type": "unsigned int"
        },
        {
          "name": "strainValue",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "PolynomialDerivativeValue",
      "return_type": "double",
      "params": [
        {
          "name": "springIndex",
          "type": "unsigned int"
        },
        {
          "name": "strainValue",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "bwdInit",
      "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": "data_f1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_f2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_p1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_p2",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_v1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_v2",
          "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": "data_df1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_df2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_dx1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_dx2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": true,
      "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": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMBKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFirstObjectIndices",
      "return_type": "const VecIndex &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSecondObjectIndices",
      "return_type": "const VecIndex &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getObject1",
      "return_type": "core::behavior::MechanicalState<DataTypes> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getObject2",
      "return_type": "core::behavior::MechanicalState<DataTypes> *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `PolynomialSpringsForceField` is a SOFA component that implements elastic springs with polynomial stiffness between given degrees of freedom in solid mechanics simulations. It inherits from the `PairInteractionForceField` and operates on two mechanical states, allowing it to apply forces between different sets of points. This component supports multiple spring polynomials and can handle various drawing modes (lines, cylinders, or arrows) for visualization.\n\n**Role:**\nThe primary role is to model elastic behavior with a flexible polynomial stiffness formulation, providing nonlinear force responses based on the deformation of the springs. It allows specifying coefficients for each polynomial, enabling complex mechanical interactions beyond simple linear elasticity.\n\n**Interactions:*\n- Interacts with `MechanicalState` objects representing different parts of the simulation.\n- Utilizes various SOFA API methods to compute and apply forces (`addForce`, `addDForce`), update stiffness matrices (`buildStiffnessMatrix`, `addKToMatrix`), and draw springs (`draw`).\n\n**Practical Usage:**\n- Configure `firstObjectPoints` and `secondObjectPoints` to specify the points between which springs are applied.\n- Define polynomial coefficients using `polynomialStiffness`. \n- Set `computeZeroLength` to compute initial lengths for springs.\n- Adjust drawing settings with `drawMode`, `springColor`, and other visual parameters. \n\n**Data Fields:**\n- **d_firstObjectPoints**: Indices of points related to the first object.\n- **d_secondObjectPoints**: Indices of points related to the second object.\n- **d_polynomialStiffness**: Polynomial coefficients for all springs.\n- **d_computeZeroLength**: Flag to compute initial lengths for springs.\n- **d_zeroLength**: Initial lengths for springs.\n- **d_recomputeIndices**: Boolean to recompute indices (useful when the topology changes).\n- **d_compressible**: Indicates if objects can compress without reaction force.\n- **d_drawMode**: Specifies how springs are drawn (Line, Cylinder, Arrow).\n- **d_showArrowSize**: Size of arrow axis for visualization.\n- **d_springColor**: Color of the spring.\n- **d_showIndicesScale**: Scale factor for displaying indices.",
  "maths": "<h3>Governing Equations and Operators</h3>\n\n<p>The <code>PolynomialSpringsForceField</code> component in the SOFA framework implements a nonlinear elastic spring system. The primary role is to compute forces between two sets of points, where each spring has a polynomial stiffness relation with respect to its deformation.</p>\n\n<h4>Governing Equations and Operators:</h4>\n\n<p>The governing equations include force computation, Jacobian matrix construction, and the contribution to the system stiffness matrix. The key operators are:</p>\n\n<ul>\n<li><strong>Internal Force</strong>: <span class=\"math\">\\( f_{int} \\)</span></li>\n<li><strong>Jacobian Matrix</strong>: <span class=\"math\">\\( J \\)</span>, representing the stiffness matrix contribution.</li>\n</ul>\n\n<h4>Elastic Force and Polynomial Stiffness:</h4>\n\n<p>The elastic force is computed based on polynomial relationships between strain and stress. The deformation (strain) of each spring is defined as:</p>\n\n\\[\n  \\epsilon_i = \\left| \\frac{L_i - L_{0i}}{L_{0i}} \\right|\n\\]\n\n<p>where <span class=\"math\">\\( L_i \\)</span> is the current length of spring <span class=\"math\">\\( i \\)</span>, and <span class=\"math\">\\( L_{0i} \\)</span> is its initial (rest) length.</p>\n\n<p>The force exerted by each polynomial spring is given by:</p>\n\n\\[\n  F_i = P(\\epsilon_i)\n\\]\n\n<p>where <span class=\"math\">\\( P(\\cdot) \\)</span> denotes the polynomial function of strain. The polynomial coefficients are specified in the data field <code>d_polynomialStiffness</code>. For a spring with degree <span class=\"math\">\\( n_i \\)</span>, the force polynomial is:</p>\n\n\\[\n  P_{i}(x) = \\sum_{k=0}^{n_i} c_{ik} x^k\n\\]\n\n<p>with <span class=\"math\">\\( c_{ik} \\)</span> being the coefficients. The force is applied to points specified by indices in <code>d_firstObjectPoints</code> and <code>d_secondObjectPoints</code>.</p>\n\n<h4>Jacobian Matrix (Stiffness Contribution):</h4>\n\n<p>The Jacobian matrix, representing the derivative of the internal forces with respect to displacements, is computed as:</p>\n\n\\[\n  \\frac{dF_i}{dx} = J_{ij}(x) = P'(\\epsilon_i)\n\\]\n\n<p>where <span class=\"math\">\\( P'(\\cdot) \\)</span> denotes the derivative of the polynomial function with respect to strain. This matrix is used for updating the global stiffness matrix.</p>\n\n<h4>Numerical Methods and Discretization:</h4>\n\n<ul>\n<li><strong>Force Calculation</strong>: Forces are computed in <code>addForce()</code>, where each spring's force contribution is added to the nodal forces based on the current displacement of points.</li>\n<li><strong>Jacobian Matrix Construction</strong>: The Jacobian matrix is calculated in <code>ComputeJacobian()</code> and stored for later use in assembling the stiffness matrix.</li>\n<li><strong>K Matrix Assembly</strong>: Contributions to the global stiffness matrix are computed in <code>addKToMatrix()</code>, where the Jacobian matrix values are added with appropriate scaling factors into the system matrix.</li>\n</ul>\n\n<h4>Component Role:</h4>\n\n<p>The <code>PolynomialSpringsForceField</code> component fits into the broader variational / Lagrangian mechanics framework by contributing to the internal forces and stiffness matrix of deformable bodies. It provides nonlinear elasticity behavior through polynomial force-displacement relationships, enabling more complex material modeling than simple linear springs.</p>\n\n<p>The role in the global FEM pipeline includes:</p>\n\n<ul>\n<li><strong>Assembly</strong>: Computation of internal forces and Jacobian matrices.</li>\n<li><strong>Time Integration</strong>: Force contribution to implicit integration schemes.</li>\n<li><strong>Nonlinear Solve</strong>: Contribution to the global system residual through nonlinear force terms.</li>\n<li><strong>Linear Solve</strong>: Contributions to stiffness matrix in the linearization of the nonlinear problem.</li>\n</ul>",
  "abstract": "The `PolynomialSpringsForceField` models elastic springs with polynomial stiffness between given degrees of freedom, providing nonlinear force responses based on deformation.",
  "sheet": "# PolynomialSpringsForceField\n\n## Overview\n\nThe `PolynomialSpringsForceField` is a component that implements elastic springs with polynomial stiffness between specified points in solid mechanics simulations. It inherits from the `PairInteractionForceField`, allowing it to apply forces between different sets of points and supports various drawing modes for visualization.\n\n## Mathematical Model\n\nThe governing equations include force computation, Jacobian matrix construction, and contributions to the system stiffness matrix. The key operators are:\n\n- **Internal Force**: \\( f_{\\mathrm{int}} \\)\n- **Jacobian Matrix**: \\( J \\), representing the stiffness matrix contribution.\n\n### Elastic Force and Polynomial Stiffness\n\nThe elastic force is computed based on polynomial relationships between strain and stress. The deformation (strain) of each spring is defined as:\n\n\\[\n  \\epsilon_i = \\left| \\frac{L_i - L_{0i}}{L_{0i}} \\right|\n\\]\n\nwhere \\( L_i \\) is the current length of spring \\( i \\), and \\( L_{0i} \\) is its initial (rest) length.\n\nThe force exerted by each polynomial spring is given by:\n\n\\[\n  F_i = P(\\epsilon_i)\n\\]\n\nwhere \\( P(\\cdot) \\) denotes the polynomial function of strain. The polynomial coefficients are specified in the data field `d_polynomialStiffness`. For a spring with degree \\( n_i \\), the force polynomial is:\n\n\\[\n  P_{i}(x) = \\sum_{k=0}^{n_i} c_{ik} x^k\n\\]\n\nwith \\( c_{ik} \\) being the coefficients. The force is applied to points specified by indices in `d_firstObjectPoints` and `d_secondObjectPoints`.\n\n### Jacobian Matrix (Stiffness Contribution)\n\nThe Jacobian matrix, representing the derivative of the internal forces with respect to displacements, is computed as:\n\n\\[\n  \\frac{dF_i}{dx} = J_{ij}(x) = P'(\\epsilon_i)\n\\]\n\nwhere \\( P'(\\cdot) \\) denotes the derivative of the polynomial function with respect to strain. This matrix is used for updating the global stiffness matrix.\n\n## Parameters and Data\n\n- **d_firstObjectPoints**: Indices of points related to the first object.\n- **d_secondObjectPoints**: Indices of points related to the second object.\n- **d_polynomialStiffness**: Polynomial coefficients for all springs.\n- **d_computeZeroLength**: Flag to compute initial lengths for springs (default: 0).\n- **d_zeroLength**: Initial lengths for springs.\n- **d_recomputeIndices**: Boolean to recompute indices (useful when the topology changes; default: false).\n- **d_compressible**: Indicates if objects can compress without reaction force (default: false).\n- **d_drawMode**: Specifies how springs are drawn (Line, Cylinder, Arrow; default: 0).\n- **d_showArrowSize**: Size of arrow axis for visualization.\n- **d_springColor**: Color of the spring.\n- **d_showIndicesScale**: Scale factor for displaying indices (default: 0.02).\n\n## Practical Notes\n\n- Ensure that `firstObjectPoints` and `secondObjectPoints` are correctly specified to avoid undefined behavior.\n- The polynomial coefficients in `polynomialStiffness` should be carefully chosen to model the desired nonlinear elastic behavior accurately.\n- Setting `computeZeroLength` to 1 can help initialize springs with correct rest lengths, improving simulation accuracy."
}