Methods

{
  "name": "RepulsiveSpringForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/RepulsiveSpringForceField.h",
  "doc": "Springs which only repel.",
  "inherits": [
    "SpringForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::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": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [
        {
          "name": "",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `RepulsiveSpringForceField` is a SOFA component within the SolidMechanics.Spring module, responsible for simulating repulsive forces between points in a mechanical system. It inherits from `SpringForceField`, indicating it operates on spring-like interactions but with the specific behavior that only repels, never attracts. This force field is defined in `<sofa/component/solidmechanics/spring/RepulsiveSpringForceField.h>` and implemented for different vector types (Vec1Types, Vec2Types, Vec3Types) via template specialization.\n\nThe primary method `addForce` computes the forces exerted between points based on their positions and velocities. It updates force data fields (`data_f1`, `data_f2`) by adding repulsive forces when the distance between connected points is less than a predefined initial position value (`initpos`). The `getPotentialEnergy` method currently returns 0, indicating that potential energy calculation for this component is not implemented.\n\nThis component interacts with other SOFA components through its mechanical data fields and inheritance from `SpringForceField`, enabling it to be integrated into larger simulation setups involving solid mechanics. Its usage requires defining spring connections between points within the system and setting appropriate parameters such as stiffness (`ks`) and damping coefficients (`kd`).",
  "maths": "The `RepulsiveSpringForceField` component in the SOFA framework is designed to simulate repulsive forces between points (nodes) in a mechanical system. It inherits from the `SpringForceField` class and modifies its behavior such that it only applies repulsion, never attraction.\n\n### Governing Equations and Operators\n- **Internal Force Contribution**: The internal force contribution, denoted as \\( f_{\text{int}}^e \\), is computed in the `addForce` method. It updates the force data fields (`data_f1`, `data_f2`) by adding repulsive forces when the distance between connected points (springs) is less than a predefined initial position value (`initpos`). The repulsive force \\( \boldsymbol{F}^e_i \\) at each node is given by:\n\n\begin{equation}\n    \boldsymbol{F}_i^{\text{rep}} = k_s (d - d_{\text{init}}) + k_d (\boldsymbol{v}_{b} - \boldsymbol{v}_{a}) \\cdot \frac{\boldsymbol{u}}{d}\n\tag{1}\n\tag{2}\n\tag{3}\n\tag{4}\n\tag{5}\n\tag{6}\n\tag{7}\n\tag{8}\n\tag{9}\n\tag{10}\n\tag{11}\n\n\begin{equation*}\n    \boldsymbol{F}_i^{\text{rep}} = k_s (d - d_{\text{init}}) + k_d (\boldsymbol{v}_{b} - \boldsymbol{v}_{a}) \\cdot \frac{\boldsymbol{u}}{d},\n\\end{equation*}\n\nwhere:\n- \\(k_s\\): stiffness coefficient of the spring.\n- \\(k_d\\): damping coefficient of the spring.\n- \\(\boldsymbol{v}_{a}\\), \\(\boldsymbol{v}_{b}\\): velocities at nodes `a` and `b`, respectively.\n- \\(\boldsymbol{u} = \boldsymbol{x}_2(b) - \boldsymbol{x}_1(a)\\): displacement vector between connected points.\n- \\(d\\): distance between the two connected points, given by \\( d = \norm{\boldsymbol{u}} \\).\n- \\(d_{\text{init}}\\): initial position value at which repulsion starts.\n\nThe force is applied in such a way that when \\(d < d_{\text{init}}\\), the repulsive force acts along the direction of \\(\boldsymbol{u}\\) and is proportional to both the displacement from the initial position and the relative velocity between the points. This ensures that forces are only active when nodes are closer than their initial separation.\n\n- **Tangent Stiffness Contribution**: The component also contributes to the tangent stiffness matrix, \\( K \\\\) by computing the derivative of the internal force with respect to displacements. In `addForce`, this is done using finite differences and stored in `this->dfdx` for each spring connection:\n\n\begin{equation}\n    K = \\frac{\text{d}f_{\text{int}}}{\text{d}u},\n\\end{equation}\n\nwhere the matrix elements are computed as follows, depending on whether the distance is less than `initpos` or not.\n\n### Constitutive and Kinematic Laws\n- **Repulsive Force Law**: The repulsive force law used by this component can be summarized as a linear combination of stiffness and damping terms. It effectively models a system where springs only exert forces when compressed, pushing connected points apart when they are closer than their initial separation distance.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: The internal forces calculated by `RepulsiveSpringForceField` contribute to the global force vector \\( f_{\text{int}} \\) and tangent stiffness matrix \\( K \\). It operates during the assembly phase, modifying the internal force contributions based on the positions and velocities of connected points.\n- **Time Integration**: During time integration, these forces are integrated implicitly using methods such as Backward Euler to advance the state of the system in time. The repulsive forces ensure that nodes move apart when they get too close.\n\n### Numerical Methods or Discretization Choices\nThe `RepulsiveSpringForceField` component uses explicit force calculations and finite differences for stiffness contributions, avoiding complex nonlinear solvers by assuming linear behavior around each node's current position.\n\n### Variational Mechanics Framework\nIn the broader variational mechanics framework, this component contributes to the internal forces (\\(f_{\text{int}}\\)) that affect the system dynamics. It modifies the potential energy landscape in such a way that nodes are repelled when they get too close, ensuring physical consistency and stability during simulation.\n\n### Summary\nThe `RepulsiveSpringForceField` component is a specialized force field within SOFA's SolidMechanics module designed to simulate repulsive forces between points. It modifies the behavior of traditional springs such that they only exert repulsion when compressed below an initial position, providing a mechanism for maintaining minimum distances in deformable systems.",
  "abstract": "The RepulsiveSpringForceField simulates repulsive forces between points in a mechanical system, contributing to the global force vector and tangent stiffness matrix during assembly.",
  "sheet": "# RepulsiveSpringForceField\n\n**Overview**\n\nRepulsiveSpringForceField is a specialized component within SOFA's SolidMechanics module that simulates repulsive forces between points. It inherits from `SpringForceField` but modifies its behavior to apply only repulsion when the distance between connected points is less than an initial position value (`initpos`). This force field contributes to the internal forces and tangent stiffness matrix during the assembly phase of a simulation.\n\n**Mathematical Model**\n\nThe internal force contribution, denoted as \\( f_{\\text{int}}^e \\), is computed in the `addForce` method. The repulsive force at each node is given by:\n\n\\[\n    \\boldsymbol{F}_i^{\\text{rep}} = k_s (d - d_{\\text{init}}) + k_d (\\boldsymbol{v}_{b} - \\boldsymbol{v}_{a}) \\cdot \\frac{\\boldsymbol{u}}{d},\n\\]\n\nwhere:\n- \\(k_s\\): stiffness coefficient of the spring.\n- \\(k_d\\): damping coefficient of the spring.\n- \\(\\boldsymbol{v}_{a}\\), \\(\\boldsymbol{v}_{b}\\): velocities at nodes `a` and `b`, respectively.\n- \\(\\boldsymbol{u} = \\boldsymbol{x}_2(b) - \\boldsymbol{x}_1(a)\\): displacement vector between connected points.\n- \\(d\\): distance between the two connected points, given by \\( d = \\|\\boldsymbol{u}\\| \\).\n- \\(d_{\\text{init}}\\): initial position value at which repulsion starts.\n\nThe force is applied in such a way that when \\(d < d_{\\text{init}}\\), the repulsive force acts along the direction of \\(\\boldsymbol{u}\\) and is proportional to both the displacement from the initial position and the relative velocity between the points. This ensures that forces are only active when nodes are closer than their initial separation.\n\nThe component also contributes to the tangent stiffness matrix, \\( K \\), by computing the derivative of the internal force with respect to displacements:\n\n\\[\n    K = \\frac{d f_{\\text{int}}}{d u}.\n\\]\n\n**Practical Notes**\n\nThe `RepulsiveSpringForceField` uses explicit force calculations and finite differences for stiffness contributions, avoiding complex nonlinear solvers by assuming linear behavior around each node's current position. The potential energy calculation is not implemented (`getPotentialEnergy` returns 0)."
}