Data Fields

Links

Methods

{
  "name": "VectorSpringForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/VectorSpringForceField.h",
  "doc": "Spring force field acting along the edges of a mesh.",
  "inherits": [
    "PairInteractionForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_stiffness",
      "type": "SReal",
      "xmlname": "stiffness",
      "help": "Default edge stiffness used in absence of file information"
    },
    {
      "name": "d_viscosity",
      "type": "SReal",
      "xmlname": "viscosity",
      "help": "Default edge viscosity used in absence of file information"
    },
    {
      "name": "d_useTopology",
      "type": "bool",
      "xmlname": "useTopology",
      "help": "Activate/Deactivate topology mode of the component (springs on each edge)"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "resizeArray",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "createEdgeInformation",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int"
        },
        {
          "name": "t",
          "type": "Spring &"
        },
        {
          "name": "e",
          "type": "const core::topology::BaseMeshTopology::Edge &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "load",
      "return_type": "bool",
      "params": [
        {
          "name": "filename",
          "type": "const char *"
        }
      ],
      "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"
    },
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdInit",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "createDefaultSprings",
      "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_x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_x2",
          "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": "buildDampingMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "is_virtual": false,
      "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": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStiffness",
      "return_type": "Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getViscosity",
      "return_type": "const Real",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSpringArray",
      "return_type": "const int &",
      "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"
    },
    {
      "name": "clear",
      "return_type": "void",
      "params": [
        {
          "name": "reserve",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addSpring",
      "return_type": "void",
      "params": [
        {
          "name": "m1",
          "type": "int"
        },
        {
          "name": "m2",
          "type": "int"
        },
        {
          "name": "ks",
          "type": "SReal"
        },
        {
          "name": "kd",
          "type": "SReal"
        },
        {
          "name": "restVector",
          "type": "Coord"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `VectorSpringForceField` is a component in the SOFA framework's Solid Mechanics module that simulates spring forces acting along the edges of a mesh. It inherits from `PairInteractionForceField`, indicating it can interact with two different sets of mechanical states. This force field allows for the definition of stiffness and viscosity parameters to model elastic and damping behaviors respectively.\n\n**Interactions:*\n- **Topology:** The component links to a `BaseMeshTopology` container, which provides information about the mesh edges used in spring calculations. The link can be set manually or automatically detected from the current context.\n- **Mechanical States:** It interacts with two mechanical states (`mstate1` and `mstate2`) to apply forces based on the relative positions and velocities of points along the edges.\n\n**Data Fields:*\n- *stiffness:* Default edge stiffness used in absence of file information.\n- *viscosity:* Default edge viscosity used in absence of file information.\n- *useTopology:* Boolean flag to activate or deactivate topology-based spring initialization (one spring per mesh edge).\n- *filename:* File path from which the springs’ information can be loaded. If provided, it overrides default stiffness and viscosity values.\n\n**Usage:*\nThe `VectorSpringForceField` is used for modeling elastic behaviors in solid mechanics simulations where springs represent connections between points along edges of a mesh. It can initialize springs based on topology or user-defined files, allowing flexibility in setting up the simulation environment.",
  "maths": "The `VectorSpringForceField` in the SOFA framework implements force fields representing springs along the edges of a mesh. These forces are used to model elastic and damping behaviors between points, contributing to the internal forces acting on the mechanical system.\n\n### Governing Equations\n\nThe component calculates the spring forces using Hooke's law for elasticity and linear damping based on relative velocities:\n\n\begin{align*}\n  f_{\\text{s}} &= k_s (x_2 - x_1) + \\mathbf{k}_d (v_2 - v_1),\n\\end{align*}\nwhere $k_s$ is the spring stiffness, $k_d$ is the damping factor, $(x_1, x_2)$ are the positions of the two points connected by a spring, and $(v_1, v_2)$ are their corresponding velocities.\n\n### Contribution to FEM Pipeline\n\n- **Assembly Phase:** The `VectorSpringForceField` assembles internal force contributions ($f_{\\text{int}}$) based on the relative positions and velocities of points along edges. This is done through the method `addForce`, which updates the forces in the mechanical states (`data_f1` and `data_f2`).\n\n- **Time Integration:** The component supports implicit time integration schemes used by SOFA, where it contributes to the internal force calculation for each time step.\n\n### Numerical Methods and Discretization Choices\n\nThe component uses a simple linear spring model along edges of the mesh. For topology-based initialization (when `useTopology` is true), it creates one spring per edge in the mesh topology provided by the linked `BaseMeshTopology`. The spring stiffness ($k_s$) and damping factor ($k_d$) can be specified either through default values or loaded from a file.\n\n### Constitutive Laws Involved\n\nThe constitutive law here is a simple linear elastic model with viscous damping:\n\n\begin{align*}\n  f_{\\text{s}} &= k_s (x_2 - x_1) + \\mathbf{k}_d (v_2 - v_1),\n\\end{align*}\nwhere $k_s$ and $k_d$ are constants representing the stiffness and damping coefficients, respectively.\n\n### Role in Variational Mechanics Framework\n\nIn a variational mechanics framework, this component contributes to the weak form of the governing equations by adding internal forces due to elastic deformations and damping. The spring force is derived from the potential energy associated with the deformation:\n\n\begin{align*}\n  U(x) &= \\frac{1}{2} k_s (x_2 - x_1 - l_0)^2,\n\\end{align*}\nwhere $l_0$ is the rest length of the spring. The corresponding force is given by:\n\n\begin{align*}\n  f_{\\text{s}} &= - \\frac{dU}{dx} = k_s (x_2 - x_1 - l_0).\n\\end{align*}\n\nWhen damping is included, the forces contribute to the time-dependent term in the weak form. The component fits into a broader variational framework by ensuring consistency with the mechanical laws governing deformable systems.",
  "abstract": "The `VectorSpringForceField` simulates spring forces along the edges of a mesh using Hooke's law for elasticity and linear damping based on relative velocities.",
  "sheet": "# VectorSpringForceField\n\n## Overview\n\nThe `VectorSpringForceField` is a component in the SOFA framework that simulates spring forces acting along the edges of a mesh. It inherits from `PairInteractionForceField`, allowing it to interact with two different sets of mechanical states. The component links to a `BaseMeshTopology` container for topology information and allows customization through stiffness and viscosity parameters.\n\n## Mathematical Model\n\nThe component calculates the spring forces using Hooke's law for elasticity and linear damping based on relative velocities:\n\n\\[ f_{\\text{s}} = k_s (x_2 - x_1) + \\mathbf{k}_d (v_2 - v_1), \\]\nwhere $k_s$ is the spring stiffness, $k_d$ is the damping factor, $(x_1, x_2)$ are the positions of the two points connected by a spring, and $(v_1, v_2)$ are their corresponding velocities.\n\nThe potential energy associated with the deformation is given by:\n\n\\[ U(x) = \\frac{1}{2} k_s (x_2 - x_1 - l_0)^2, \\]\nwhere $l_0$ is the rest length of the spring. The corresponding force is derived as:\n\n\\[ f_{\\text{s}} = - \\frac{dU}{dx} = k_s (x_2 - x_1 - l_0). \\]\n\n## Parameters and Data\n\n- **stiffness:** Default edge stiffness used in absence of file information (`SReal` type).\n- **viscosity:** Default edge viscosity used in absence of file information (`SReal` type).\n- **useTopology:** Boolean flag to activate or deactivate topology-based spring initialization (one spring per mesh edge) (`bool` type).\n\n## Dependencies and Connections\n\nThe `VectorSpringForceField` requires a link to a `BaseMeshTopology` container for topology information. It interacts with two mechanical states (`mstate1` and `mstate2`) to apply forces based on the relative positions and velocities of points along the edges."
}