Data Fields

Links

Methods

{
  "name": "RestShapeSpringsForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/RestShapeSpringsForceField.h",
  "doc": "Elastic springs generating forces on degrees of freedom between their current and rest shape position.\n\nThis class describes a simple 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::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_stiffness",
      "type": "VecReal",
      "xmlname": "stiffness",
      "help": "stiffness values between the actual position and the rest shape position"
    },
    {
      "name": "d_angularStiffness",
      "type": "VecReal",
      "xmlname": "angularStiffness",
      "help": "angularStiffness assigned when controlling the rotation of the points"
    },
    {
      "name": "d_external_points",
      "type": "VecIndex",
      "xmlname": "external_points",
      "help": "points from the external Mechanical State that define the rest shape springs"
    },
    {
      "name": "d_recompute_indices",
      "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. (default=[0.0,1.0,0.0,1.0])"
    }
  ],
  "links": [
    {
      "name": "l_restMState",
      "target": "MechanicalState<DataTypes>",
      "kind": "single",
      "xmlname": "external_rest_shape",
      "help": "rest_shape can be defined by the position of an external Mechanical State"
    },
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "Link to be set to the topology container in the component graph"
    }
  ],
  "methods": [
    {
      "name": "bwdInit",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "parse",
      "return_type": "void",
      "params": [
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "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": "f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "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": "df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "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": "x",
          "type": "const DataVecCoord &"
        }
      ],
      "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 sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "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": "matrix",
          "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": "getExtPosition",
      "return_type": "const DataVecCoord *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIndices",
      "return_type": "const VecIndex &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getExtIndices",
      "return_type": "const VecIndex &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "recomputeIndices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "checkOutOfBoundsIndices",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "checkOutOfBoundsIndices",
      "return_type": "bool",
      "params": [
        {
          "name": "indices",
          "type": "const VecIndex &"
        },
        {
          "name": "dimension",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `RestShapeSpringsForceField` is a component in the SOFA framework used to generate elastic forces between the current positions and rest shape positions of degrees of freedom (DOFs). It supports both translations and rotations by controlling stiffness values for each direction. The force field can also use an external MechanicalState as a reference for the rest shape position, allowing more flexibility in defining constraints.\n\n### Interactions with Other Components:\n- **MechanicalState**: Provides the rest shape positions if an external MechanicalState is linked to `l_restMState`. If not provided, it defaults to using the current context's rest positions.\n- **BaseMeshTopology**: Linked via `l_topology`, this provides topological information used for updating and validating indices of DOFs being controlled by the springs.\n\n### Data Fields:\n- `stiffness`: Defines stiffness values between actual position and rest shape position. If not defined, it assumes a default value (e.g., 100.0).\n- `angularStiffness`: Stiffness assigned to control rotation of points when working with rigid bodies.\n- `external_points`: Indices from the external Mechanical State that define the rest shape springs.\n- `recompute_indices`: Boolean indicating whether indices should be recomputed (useful for BBOX operations).\n- `drawSpring`: Boolean controlling whether springs are drawn visually in the simulation.\n- `springColor`: Color used to visualize springs (default is green).\n\n### Usage Guidance:\nThis component can be useful when simulating elastic deformations where a reference rest shape needs to be maintained. Users should set appropriate stiffness values and optionally link an external MechanicalState if different rest shapes are desired for the simulation.\n",
  "maths": "<h3>Governing Equations and Operators</h3>\n\n<p>The <code>RestShapeSpringsForceField</code> in the SOFA framework implements a simple elastic springs force field between degrees of freedom (DOFs) and their rest shape positions. The main contributions are:</p>\n<ul>\n<li><strong>Internal Force Contribution</strong>: This component contributes to the internal forces (<span class=\"math-inline\"><em>f<sub>int</sub></em></span>) acting on each degree of freedom.</li>\n<li><strong>Tangent Stiffness Matrix Contribution</strong>: The stiffness matrix (<span class=\"math-inline\"><em>K</em></span>) is also contributed to by the springs, reflecting the linearization of internal forces around the current configuration.</li>\n</ul>\n\n<h4>Internal Forces Calculation</h4>\n<p>The internal force contribution for each DOF <span class=\"math-inline\"><em>i</em></span> can be expressed as:</p>\n\\[ f_i = -k_{i} (u_i - u_0) \\]\n<ul>\n<li><strong>Translation Forces</strong>: For translations, the force is proportional to the displacement between the current position <span class=\"math-inline\"><em>u<sub>i</sub></em></span> and the rest shape position <span class=\"math-inline\"><em>u<sub>0,i</sub></em></span>.</li>\n<li><strong>Rotation Forces (for Rigid Bodies)</strong>: For rotations, an additional rotational spring is considered. The force accounts for the difference between current orientation and initial orientation.</li>\n</ul>\n\n<p>The stiffness values <span class=\"math-inline\"><em>k<sub>i</sub></em></span> are defined per DOF:</p>\n\\[ k_{i} = \\begin{cases}\n  k, &amp; \\text{if } i &lt; |k| \\\\\n  k_0, &amp; \\text{otherwise}\n\\end{cases} \\]\n<p>where <span class=\"math-inline\"><em>k</em></span> is the stiffness vector and <span class=\"math-inline\"><em>k<sub>0</sub></em></span> is a default stiffness value (e.g., 100.0).</p>\n\n<h4>Tangent Stiffness Matrix Calculation</h4>\n<p>The contribution to the tangent stiffness matrix (<span class=\"math-inline\"><em>K</em></span>) for each DOF <span class=\"math-inline\"><em>i</em></span> is:</p>\n\\[ K_{i,i} = k_i \\]\n<ul>\n<li><strong>Translation Stiffness</strong>: The stiffness matrix contains diagonal entries corresponding to the translational springs.</li>\n<li><strong>Rotation Stiffness (for Rigid Bodies)</strong>: For rigid bodies, additional rotational stiffness terms are included in the appropriate components of <span class=\"math-inline\"><em>K</em></span>.</li>\n</ul>\n\n<h4>Potential Energy Contribution</h4>\n<p>The potential energy stored by each spring is:</p>\n\\[ U_i = \\frac{1}{2} k_{i} (u_i - u_0)^T (u_i - u_0) \\]\n<p>Note that the calculation of <span class=\"math-inline\"><em>U<sub>i</sub></em></span> is not currently implemented in this component.</p>\n\n<h3>Constitutive and Kinematic Laws</h3>\n<ul>\n<li><strong>Hooke's Law for Translational Springs</strong>: The translational spring forces follow Hooke’s law, which states that the force is proportional to the displacement from equilibrium.</li>\n<li><strong>Rotational Spring Forces (for Rigid Bodies)</strong>: For rigid bodies, rotational springs are also considered. The rotation difference is computed using quaternions and normalized before calculating the angular stiffness term.</li>\n</ul>\n\n<h3>Role in the FEM Pipeline</h3>\n<ul>\n<li><strong>Assembly Phase:</strong> During assembly, this component contributes to the internal forces <span class=\"math-inline\"><em>f<sub>int</sub></em></span> and the tangent stiffness matrix <span class=\"math-inline\"><em>K</em></span>.</li>\n<li><strong>Time Integration:</strong> The calculated internal forces are incorporated into the time integration scheme (e.g., implicit Euler).</li>\n<li><strong>Nonlinear Resolution:</strong> This component contributes to the nonlinear residual during the Newton-Raphson iteration by computing and updating <span class=\"math-inline\"><em>f<sub>int</sub></em></span>.</li>\n<li><strong>Linear Solve:</strong> The stiffness matrix contributions from this component are used in solving the linear system.</li>\n</ul>\n\n<h3>Numerical Methods and Discretization Choices</h3>\n<ul>\n<li>The springs apply forces directly between current positions and rest shape positions, effectively discretizing the continuous mechanical model into a set of discrete spring elements.</li>\n<li>For rigid bodies (Rigid3Types), both translational and rotational stiffness are considered. The translational stiffness acts on the center of mass, while the rotational stiffness accounts for changes in orientation.</li>\n</ul>\n\n<h3>Fitting into Variational / Lagrangian Mechanics Framework</h3>\n<p>The <code>RestShapeSpringsForceField</code> component is part of a larger variational and Lagrangian mechanics framework:</p>\n<ul>\n<li><strong>Lagrangian Mechanics Basis:</strong> The forces generated by the springs can be derived from a potential energy function that corresponds to Hooke’s law. This aligns with the principle of least action in Lagrangian mechanics.</li>\n<li><strong>Weak Formulation:</strong> In the context of FEM, these forces are incorporated into the weak form through the internal force term <span class=\"math-inline\"><em>f<sub>int</sub></em></span>.</li>\n<li><strong>Variational Consistency:</strong> The component ensures that the variational consistency is maintained by accurately computing and updating both the internal forces and the tangent stiffness matrix.</li>\n</ul>",
  "abstract": "The `RestShapeSpringsForceField` generates elastic forces between current positions and rest shape positions of degrees of freedom, supporting both translational and rotational stiffness. It can use an external MechanicalState for defining rest shapes.",
  "sheet": "# RestShapeSpringsForceField\n\n## Overview\n\nThe `RestShapeSpringsForceField` is a component in the SOFA framework that generates elastic forces between the current positions and rest shape positions of degrees of freedom (DOFs). It supports both translational and rotational stiffness, and can use an external MechanicalState for defining rest shapes.\n\n## Mathematical Model\n\n### Internal Forces Calculation\nThe internal force contribution for each DOF $i$ can be expressed as:\n\\[ f_i = -k_{i} (u_i - u_0) \\]\n- **Translation Forces**: For translations, the force is proportional to the displacement between the current position $u_i$ and the rest shape position $u_{0,i}$.\n- **Rotation Forces (for Rigid Bodies)**: For rotations, an additional rotational spring is considered. The force accounts for the difference between current orientation and initial orientation.\n\nThe stiffness values $k_i$ are defined per DOF:\n\\[ k_{i} = \\begin{cases}\n  k, &amp; \\text{if } i &lt; |k| \\\\\n  k_0, &amp; \\text{otherwise}\n\\end{cases} \\]\nwhere $k$ is the stiffness vector and $k_0$ is a default stiffness value (e.g., 100.0).\n\n### Tangent Stiffness Matrix Calculation\nThe contribution to the tangent stiffness matrix ($K$) for each DOF $i$ is:\n\\[ K_{i,i} = k_i \\]\n- **Translation Stiffness**: The stiffness matrix contains diagonal entries corresponding to the translational springs.\n- **Rotation Stiffness (for Rigid Bodies)**: For rigid bodies, additional rotational stiffness terms are included in the appropriate components of $K$.\n\n### Potential Energy Contribution\nThe potential energy stored by each spring is:\n\\[ U_i = \\frac{1}{2} k_{i} (u_i - u_0)^T (u_i - u_0) \\]\nNote that the calculation of $U_i$ is not currently implemented in this component.\n\n## Parameters and Data\n- **stiffness**: Defines stiffness values between actual position and rest shape position. If not defined, it assumes a default value (e.g., 100.0).\n- **angularStiffness**: Stiffness assigned to control rotation of points when working with rigid bodies.\n- **external_points**: Indices from the external Mechanical State that define the rest shape springs.\n- **recompute_indices**: Boolean indicating whether indices should be recomputed (useful for BBOX operations).\n- **drawSpring**: Boolean controlling whether springs are drawn visually in the simulation.\n- **springColor**: Color used to visualize springs (default is green).\n\n## Dependencies and Connections\nThe `RestShapeSpringsForceField` typically requires a linked MechanicalState (`l_restMState`) for defining rest shape positions, and a BaseMeshTopology (`l_topology`) for topological information."
}