Data Fields

Methods

{
  "name": "SphereForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/SphereForceField.h",
  "doc": "Outward repulsion applied by a sphere geometry",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "data",
      "type": "DataTypes"
    },
    {
      "name": "d_sphereCenter",
      "type": "Coord",
      "xmlname": "center",
      "help": "sphere center"
    },
    {
      "name": "d_sphereRadius",
      "type": "Real",
      "xmlname": "radius",
      "help": "sphere radius"
    },
    {
      "name": "d_stiffness",
      "type": "Real",
      "xmlname": "stiffness",
      "help": "force stiffness"
    },
    {
      "name": "d_damping",
      "type": "Real",
      "xmlname": "damping",
      "help": "force damping"
    },
    {
      "name": "d_color",
      "type": "sofa::type::RGBAColor",
      "xmlname": "color",
      "help": "sphere color. (default=[0,0,1,1])"
    },
    {
      "name": "d_localRange",
      "type": "type::Vec<2, int>",
      "xmlname": "localRange",
      "help": "optional range of local DOF indices. Any computation involving only indices outside of this range are discarded (useful for parallelization using mesh partitioning)"
    },
    {
      "name": "d_bilateral",
      "type": "bool",
      "xmlname": "bilateral",
      "help": "if true the sphere force field is applied on both sides"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "setSphere",
      "return_type": "void",
      "params": [
        {
          "name": "center",
          "type": "const Coord &"
        },
        {
          "name": "radius",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "stiff",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDamping",
      "return_type": "void",
      "params": [
        {
          "name": "damp",
          "type": "Real"
        }
      ],
      "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": "d_f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "d_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": "d_df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "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 &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "x",
          "type": "const VecCoord &"
        }
      ],
      "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": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "",
          "type": "SReal"
        },
        {
          "name": "",
          "type": "unsigned int &"
        }
      ],
      "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"
    }
  ],
  "description": "The `SphereForceField` is a component in the SOFA framework that applies an outward repulsion force based on a sphere geometry. It inherits from the `ForceField` class and provides functionality to define the center, radius, stiffness, and damping parameters for the spherical force field.\n\n### Role and Purpose:\nThe `SphereForceField` is used to simulate forces that push objects away from a specified spherical region in space. This can be useful for simulating various physical scenarios where objects need to maintain a minimum distance from a certain area or object.\n\n### Interactions with Other Components:\nThe `SphereForceField` interacts with other SOFA components through its API, specifically by using methods like `addForce`, `getPotentialEnergy`, and the `draw` method for visualization. It also utilizes internal fields such as `d_sphereCenter`, `d_sphereRadius`, `d_stiffness`, and `d_damping` to define its behavior.\n\n### Practical Usage Guidance:\nThe component can be configured by setting the sphere's center (`center`) and radius (`radius`). The force parameters are defined via stiffness (`stiffness`) and damping (`damping`). An optional range of local DOF indices can be specified using `localRange`, which is useful for parallelization. Additionally, a `bilateral` flag controls whether the force field acts on both sides of the sphere.\n\n### Data Fields:\n- **center:** Sphere center coordinate (type: Coord).\n- **radius:** Radius of the sphere (type: Real).\n- **stiffness:** Force stiffness parameter (type: Real).\n- **damping:** Force damping parameter (type: Real).\n- **color:** Color for visualization purposes (type: RGBAColor).\n- **localRange:** Optional range of local DOF indices to control computations.\n- **bilateral:** Boolean flag indicating whether the force field is applied on both sides.",
  "maths": "The `SphereForceField` in the SOFA framework implements an outward repulsion force based on a spherical geometry. The governing equations and operators for this component are as follows:\n\n### Governing Equations\n\n#### Force Contribution\nThe force contribution from the sphere is given by:\n\begin{equation}\n\\mathbf{f}_i = -k (\\mathbf{x}_i - \\mathbf{c}) \\frac{|\\mathbf{x}_i - \\mathbf{c}| - r}{|\\mathbf{x}_i - \\mathbf{c}|} + d \\dot{\\mathbf{x}}_i\n\tag{1}\n\\end{equation}\nwhere:\n- $k$ is the stiffness parameter,\n- $d$ is the damping coefficient,\n- $r$ is the radius of the sphere,\n- $\\mathbf{c}$ is the center coordinate of the sphere.\n\n#### Potential Energy\nThe potential energy associated with this force field is:\n\begin{equation}\nU(\\mathbf{x}) = \\sum_{i} k (r - |\\mathbf{x}_i - \\mathbf{c}|)^2 \\quad \\text{for } |\\mathbf{x}_i - \\mathbf{c}| > r\n\tag{2}\n\\end{equation}\n\n### Constitutive or Kinematic Laws Involved\nThe force field is based on the Euclidean distance from a given point $\\mathbf{x}_i$ to the center of the sphere $\\mathbf{c}$. The stiffness and damping parameters control the repulsion strength and dissipation, respectively.\n\n#### Strain Measures\nThere are no explicit strain measures involved; the force is based directly on position and velocity differences.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: This component contributes to the internal force $\\mathbf{f}_{int}$ by adding its repulsive forces as per equation (1).\n- **Nonlinear Resolution**: The nonlinear residual $R$ includes contributions from this force field.\n- **Linear Solve**: The Jacobian of the internal forces involves computing the derivative of the force with respect to position and velocity, which is handled through the `addKToMatrix` method.\n\n### Numerical Methods or Discretization Choices\nThe component discretizes the continuous force expression by evaluating it at discrete nodal positions. It does not involve any special mesh-based discretizations but rather operates on individual points within a specified range.\n\n### Fit into the Broader Variational / Lagrangian Mechanics Framework\nThis component fits into the broader framework as an external force term that can be considered part of the total potential energy $U$ and kinetic energy terms in the Lagrangian. The repulsive force derived from this potential energy is added to the overall mechanical system.\n\n### Visualization\nThe `draw` method visualizes the sphere geometry in the simulation environment, allowing for easy identification of its spatial influence.",
  "abstract": "The `SphereForceField` applies an outward repulsion force based on a spherical geometry defined by its center, radius, stiffness, and damping parameters.",
  "sheet": "# SphereForceField\n\n## Overview\nThe `SphereForceField` is a component in the SOFA framework that applies an outward repulsion force based on a sphere geometry. It inherits from the `ForceField` class and provides functionality to define the center, radius, stiffness, and damping parameters for the spherical force field.\n\n## Mathematical Model\nThe governing equations for the `SphereForceField` are as follows:\n\n### Force Contribution\nThe force contribution from the sphere is given by:\n\\begin{equation}\n  \\mathbf{f}_i = -k (\\mathbf{x}_i - \\mathbf{c}) \\frac{|\\mathbf{x}_i - \\mathbf{c}| - r}{|\\mathbf{x}_i - \\mathbf{c}|} + d \\dot{\\mathbf{x}}_i\n  \\label{eq:force}\n\\end{equation}\nwhere:\n- $k$ is the stiffness parameter,\n- $d$ is the damping coefficient,\n- $r$ is the radius of the sphere,\n- $\\mathbf{c}$ is the center coordinate of the sphere.\n\n### Potential Energy\nThe potential energy associated with this force field is:\n\\begin{equation}\n  U(\\mathbf{x}) = \\sum_{i} k (r - |\\mathbf{x}_i - \\mathbf{c}|)^2 \\quad \\text{for } |\\mathbf{x}_i - \\mathbf{c}| > r\n  \\label{eq:potential}\n\\end{equation}\n\n## Parameters and Data\nThe significant data fields exposed by the component are:\n- **center:** Sphere center coordinate (type: Coord).\n- **radius:** Radius of the sphere (type: Real).\n- **stiffness:** Force stiffness parameter (type: Real).\n- **damping:** Force damping parameter (type: Real).\n- **color:** Color for visualization purposes (type: RGBAColor, default=[0,0,1,1]).\n- **localRange:** Optional range of local DOF indices to control computations.\n- **bilateral:** Boolean flag indicating whether the force field is applied on both sides."
}