Data Fields

Methods

{
  "name": "RegularGridSpringForceField",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/RegularGridSpringForceField.h",
  "doc": "Spring acting on the edges and faces of a regular grid.",
  "inherits": [
    "SpringForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_linesStiffness",
      "type": "Real",
      "xmlname": "linesStiffness",
      "help": "Lines Stiffness"
    },
    {
      "name": "d_linesDamping",
      "type": "Real",
      "xmlname": "linesDamping",
      "help": "Lines Damping"
    },
    {
      "name": "d_quadsStiffness",
      "type": "Real",
      "xmlname": "quadsStiffness",
      "help": "Quads Stiffness"
    },
    {
      "name": "d_quadsDamping",
      "type": "Real",
      "xmlname": "quadsDamping",
      "help": "Quads Damping"
    },
    {
      "name": "d_cubesStiffness",
      "type": "Real",
      "xmlname": "cubesStiffness",
      "help": "Cubes Stiffness"
    },
    {
      "name": "d_cubesDamping",
      "type": "Real",
      "xmlname": "cubesDamping",
      "help": "Cubes Damping"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "getStiffness()",
      "return_type": "Real",
      "description": "Returns the overall stiffness (defaulting to lines stiffness)."
    },
    {
      "name": "setStiffness(val: Real)",
      "return_type": "void",
      "description": "Sets the stiffness for all types of springs (lines, quads and cubes) to val."
    },
    {
      "name": "addForce(mparams: MechanicalParams, f1: DataVecDeriv&, f2: DataVecDeriv&, x1: DataVecCoord&, x2: DataVecCoord&, v1: DataVecDeriv&, v2: DataVecDeriv&)",
      "return_type": "void",
      "description": "Calculates and adds the force due to all springs between the nodes in the regular grid topology, using the current positions and velocities."
    },
    {
      "name": "addDForce(mparams: MechanicalParams, df1: DataVecDeriv&, df2: DataVecDeriv&, dx1: DataVecDeriv&, dx2: DataVecDeriv&)",
      "return_type": "void",
      "description": "Calculates and adds the derivative of force with respect to position due to all springs between nodes, using the current displacements."
    },
    {
      "name": "draw(vparams: VisualParams)",
      "return_type": "void",
      "description": "Renders the lines representing the springs in the regular grid topology for visualization purposes."
    }
  ],
  "description": "This is a force field that applies spring forces between nodes in a regular grid topology, such as those found in voxelized or lattice structures. It provides three types of springs: lines (1D), quads (2D) and cubes (3D). Each type has its own stiffness and damping parameters which can be set independently.",
  "properties": [
    {
      "name": "linesStiffness",
      "type": "Real",
      "description": "The stiffness coefficient for the one-dimensional line springs connecting adjacent nodes in a regular grid along each axis (x, y, z)."
    },
    {
      "name": "linesDamping",
      "type": "Real",
      "description": "The damping coefficient for the one-dimensional line springs connecting adjacent nodes in a regular grid along each axis."
    },
    {
      "name": "quadsStiffness",
      "type": "Real",
      "description": "The stiffness coefficient for two-dimensional quad springs that connect nodes forming square faces between parallel planes of the 3D grid."
    },
    {
      "name": "quadsDamping",
      "type": "Real",
      "description": "The damping coefficient for two-dimensional quad springs that connect nodes forming square faces between parallel planes of the 3D grid."
    },
    {
      "name": "cubesStiffness",
      "type": "Real",
      "description": "The stiffness coefficient for three-dimensional cube springs that connect all corner nodes of each cubic cell in the regular grid structure."
    },
    {
      "name": "cubesDamping",
      "type": "Real",
      "description": "The damping coefficient for three-dimensional cube springs that connect all corner nodes of each cubic cell in the regular grid structure."
    }
  ],
  "notes": [
    "This component requires a RegularGridTopology as its associated topology container.",
    "The spring forces are computed based on Hooke's law and dampened according to a linear damping model.",
    "Setting stiffness or damping values too high can lead to numerical instability. Care should be taken when tuning these parameters."
  ],
  "maths": "The `RegularGridSpringForceField` in the SOFA framework is designed to simulate spring forces between nodes in a regular grid topology. It provides three types of springs: lines (1D), quads (2D), and cubes (3D). Each type has its own stiffness and damping parameters that can be set independently, as detailed below.\n\n### Governing Equations:\n- **Spring Force:** The spring force between two nodes is calculated using Hooke's law with the addition of a damping term. Given two points \\(\\mathbf{p}_1\\) and \\(\\mathbf{p}_2\\), the spring force \\(\\mathbf{f}\\) can be expressed as:\n  \n  \\[\\mathbf{f} = -k_s (\\|\\mathbf{p}_2 - \\mathbf{p}_1\\| - l_0) \\frac{(\\mathbf{p}_2 - \\mathbf{p}_1)}{\\|\\mathbf{p}_2 - \\mathbf{p}_1\\|} - k_d (\\dot{\\mathbf{p}}_2 - \\dot{\\mathbf{p}}_1)\\]\n  where:\n  - \\(k_s\\): Stiffness of the spring\n  - \\(l_0\\): Initial rest length of the spring\n  - \\(k_d\\): Damping coefficient\n\n- **Constitutive Law:** The constitutive law for each type of spring (lines, quads, cubes) is determined by setting up individual springs between nodes in the grid topology. For example:\n  - **Lines:** Springs are placed along each edge connecting neighboring nodes.\n  - **Quads:** Springs are placed along diagonals within faces of the grid.\n  - **Cubes:** Springs are placed along space diagonals spanning across the grid cells.\n\n### Role in the FEM Pipeline:\n- The `RegularGridSpringForceField` contributes to the internal forces \\(\\mathbf{f}_{int}\\) for the system. These forces are added to the global residual and Jacobian matrices during the assembly phase of the nonlinear solve.\n- It handles the computation of force contributions (both in terms of \\(\\mathbf{f}\\) and its derivatives with respect to nodal displacements) within the `addForce` and `addDForce` methods, which are essential for updating the system state during time integration steps.\n\n### Numerical Methods and Discretization:\n- The component uses a regular grid topology, where each node has well-defined connections to its neighboring nodes. This enables efficient enumeration of all relevant spring interactions without requiring complex neighbor queries.\n- Stiffness and damping parameters can be configured independently for lines, quads, and cubes, allowing the user to specify anisotropic behavior in different directions within the grid structure.\n\n### Variational Mechanics Framework:\n- In a broader variational mechanics context, this component contributes to the potential energy function \\(V\\) of the system. The spring potential energy is given by:\n  \n  \\[V = \\frac{1}{2} k_s (\\|\\mathbf{p}_2 - \\mathbf{p}_1\\| - l_0)^2 + \\frac{1}{2} k_d (\\dot{\\mathbf{p}}_2 - \\dot{\\mathbf{p}}_1)^2\\]\n  The internal forces are then derived from the negative gradient of this potential energy, consistent with Lagrangian mechanics.\n\n### Summary:\n- `RegularGridSpringForceField` is designed to simulate elastic and damping interactions within a regular grid topology using Hooke's law-based springs. It contributes to the total internal force \\(\\mathbf{f}_{int}\\) in the global residual equation, which is solved as part of the nonlinear dynamics simulation pipeline.\n- The stiffness and damping parameters can be configured independently for different types of connections (lines, quads, cubes), allowing for anisotropic material behavior within the grid structure.",
  "abstract": "The `RegularGridSpringForceField` applies spring forces between nodes in a regular grid topology, supporting lines (1D), quads (2D), and cubes (3D) with independent stiffness and damping parameters. It contributes to the internal forces \\(\\mathbf{f}_{int}\\) for nonlinear dynamics simulation.",
  "sheet": "# RegularGridSpringForceField\n\n## Overview\nThe `RegularGridSpringForceField` is a force field component that applies spring forces between nodes in a regular grid topology, such as those found in voxelized or lattice structures. It supports three types of springs: lines (1D), quads (2D), and cubes (3D). Each type has its own stiffness and damping parameters which can be set independently.\n\n## Mathematical Model\nThe spring force between two nodes is calculated using Hooke's law with the addition of a damping term. Given two points \\(\\mathbf{p}_1\\) and \\(\\mathbf{p}_2\\), the spring force \\(\\mathbf{f}\\) can be expressed as:\n\n\begin{equation}\n    \\mathbf{f} = -k_s (\\|\\mathbf{p}_2 - \\mathbf{p}_1\\| - l_0) \\frac{(\\mathbf{p}_2 - \\mathbf{p}_1)}{\\|\\mathbf{p}_2 - \\mathbf{p}_1\\|} - k_d (\\dot{\\mathbf{p}}_2 - \\dot{\\mathbf{p}}_1)\n\tag{1}\n\ndot{equation}\n\nwhere:\n- \\(k_s\\): Stiffness of the spring\n- \\(l_0\\): Initial rest length of the spring\n- \\(k_d\\): Damping coefficient\n\nThe potential energy function \\(V\\) for each type of spring is given by:\n\n\begin{equation}\n    V = \\frac{1}{2} k_s (\\|\\mathbf{p}_2 - \\mathbf{p}_1\\| - l_0)^2 + \\frac{1}{2} k_d (\\dot{\\mathbf{p}}_2 - \\dot{\\mathbf{p}}_1)^2\n\tag{2}\n\ndot{equation}\n\nThe internal forces are then derived from the negative gradient of this potential energy.\n\n## Parameters and Data\n- **linesStiffness**: Stiffness for lines (default: not specified)\n- **linesDamping**: Damping for lines (default: not specified)\n- **quadsStiffness**: Stiffness for quads (default: not specified)\n- **quadsDamping**: Damping for quads (default: not specified)\n- **cubesStiffness**: Stiffness for cubes (default: not specified)\n- **cubesDamping**: Damping for cubes (default: not specified)"
}