Data Fields

Links

Methods

{
  "name": "LinearForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/LinearForceField.h",
  "doc": "Linearly-interpolated force applied to given degrees of freedom.\n\nApply forces changing to given degres of freedom. Some keyTimes are given\nand the force to be applied is linearly interpolated between keyTimes. */",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "data",
      "type": "DataTypes"
    },
    {
      "name": "d_force",
      "type": "Real",
      "xmlname": "force",
      "help": "applied force to all points"
    },
    {
      "name": "d_keyForces",
      "type": "VecDeriv",
      "xmlname": "forces",
      "help": "forces corresponding to the key times"
    },
    {
      "name": "d_arrowSizeCoef",
      "type": "SReal",
      "xmlname": "arrowSizeCoef",
      "help": "Size of the drawn arrows (0->no arrows, sign->direction of drawing"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "addPoint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removePoint",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "unsigned int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearPoints",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKeyForce",
      "return_type": "void",
      "params": [
        {
          "name": "time",
          "type": "Real"
        },
        {
          "name": "force",
          "type": "Deriv"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearKeyForces",
      "return_type": "void",
      "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": "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": "",
          "type": "DataVecDeriv &"
        },
        {
          "name": "",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "kFact",
          "type": "SReal"
        },
        {
          "name": "offset",
          "type": "unsigned int &"
        }
      ],
      "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": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "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"
    }
  ],
  "description": "The LinearForceField component in SOFA (Simulation Open-Framework Architecture) is designed to apply linear forces on selected points within a simulated environment.",
  "parameters": {
    "points": {
      "description": "Indices of the points where the force will be applied."
    },
    "force": {
      "description": "Magnitude of the force that will be applied to all specified points. Default value is 1.0."
    },
    "times": {
      "description": "Key times at which specific forces are defined for interpolation."
    },
    "forces": {
      "description": "Forces corresponding to each key time, used for linear interpolation between keyframes."
    },
    "arrowSizeCoef": {
      "description": "Coefficient that determines the size and direction of the arrows drawn representing the force. A value of 0 means no arrows will be drawn."
    },
    "topology": {
      "description": "Link to the topology container, which defines the structure of the simulated object (meshes, points, etc.). If not set explicitly, the component will try to find a topology in its context."
    }
  },
  "functionality": {
    "description": "This force field applies linear forces based on keyframes defined by times and corresponding forces. When the simulation time is between two keyframes, it interpolates the force linearly between those keyframes. The magnitude of these interpolated forces can be uniformly scaled using the 'force' parameter.",
    "methods": [
      {
        "name": "addPoint",
        "description": "Adds a new point index to the list where force will be applied."
      },
      {
        "name": "removePoint",
        "description": "Removes a specific point index from the list where force is being applied (currently not implemented)."
      },
      {
        "name": "clearPoints",
        "description": "Clears all point indices from the list where force is being applied."
      },
      {
        "name": "addKeyForce",
        "description": "Adds a new keyframe with specific time and corresponding force."
      },
      {
        "name": "clearKeyForces",
        "description": "Removes all defined keyframes and their forces, effectively resetting the interpolation data."
      }
    ]
  },
  "behavior": {
    "description": "During each simulation step, LinearForceField interpolates the force based on the current simulation time and applies this interpolated force to all specified points. It supports custom topology linking for more complex simulations.",
    "interaction_with_simulation": "It interacts directly with the mechanical state of the simulated object by modifying forces acting upon it."
  },
  "maths": "<maths_md_description>\n\nThe `LinearForceField` in the SOFA framework is designed to apply linearly-interpolated forces on specified degrees of freedom (DOFs) within a deformable system. The force applied at any given time is interpolated between predefined key times and corresponding forces.\n\n### Governing Equations or Operators\n- **Interpolated Force Calculation**:\nThe `LinearForceField` computes the force to be applied at a given simulation time $t$ by linearly interpolating between two nearest key times, $\\text{prevT}$ and $\\text{nextT}$. If the current time $cT$ is within these key times, the interpolation is performed as:\n\ntargetForce = slope \\cdot (cT - prevT) + prevF\n\nwhere `slope` is calculated as follows:\n\nslope = (nextF - prevF) \\cdot \\frac{1}{(nextT - prevT)}.\n\n- **Application of Force**:\nThe computed force `targetForce` is then applied to the selected DOFs at each time step. For a set of indices corresponding to these DOFs, $\\mathbf{index}$, and the global force vector $\\mathbf{f}$, the force update can be written as:\n\n_f1[index] += targetForce\n\n### Constitutive or Kinematic Laws Involved\n- **Key Times and Forces**: The interpolation depends on predefined key times ($d_keyTimes$) and forces ($d_keyForces$). These are stored in vectors where each entry corresponds to a specific time instance.\n\n### Role in the Global FEM Pipeline\n- **Force Application**:\nThe component implements the `addForce` method, which is part of the SOFA's force field interface. This method calculates and applies forces at specified DOFs during each simulation step. The `addKToMatrix`, `buildStiffnessMatrix`, and `buildDampingMatrix` methods are trivially implemented as this force field does not contribute to the stiffness or damping matrices.\n\n### Numerical Methods or Discretization Choices\n- **Interpolation**: Linear interpolation between predefined key times is used to compute the forces at each time step. This ensures a continuous change in applied forces throughout the simulation.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe `LinearForceField` fits into the broader variational mechanics framework by contributing to the external force term $f_{ext}$ in the equation of motion:\n\nM\\ddot{x} + f_{int}(x) = f_{ext}\n\nHere, the external forces include contributions from linearly-interpolated forces applied through `LinearForceField`. This component modifies the global residual vector by adding its contribution at specified DOFs.\n\n### Potential Energy Contribution\nThe potential energy associated with the applied forces can be computed as follows:\n\ne = - \\sum_{i=0}^{N-1} (ff \\cdot _x[i] \\cdot f)\n\nwhere $ff$ is the interpolated force, $_x[i]$ are the coordinates of the DOFs, and $f$ is a scaling factor for the applied forces.\n\n</maths_md_description>",
  "abstract": "The LinearForceField applies linearly-interpolated forces on selected degrees of freedom based on predefined key times and corresponding forces, modifying the global force vector during each simulation step.",
  "sheet": "# LinearForceField\n\n## Overview\nLinearForceField is a component in SOFA that applies linearly-interpolated forces to specified degrees of freedom (DOFs) within a deformable system. It interpolates between predefined key times and corresponding forces, modifying the global force vector during each simulation step.\n\n## Mathematical Model\nThe `LinearForceField` computes the force at any given time $t$ by linearly interpolating between two nearest key times, $\text{prevT}$ and $\text{nextT}$. If the current time $cT$ is within these key times, the interpolation is performed as:\n\n\\[ \\text{slope} = \\frac{(\\text{nextF} - \\text{prevF})}{(\\text{nextT} - \\text{prevT})} \\]\n\n\\[ \\text{targetForce} = \\text{slope} \\cdot (cT - \\text{prevT}) + \\text{prevF} \\]\n\nThe computed force `targetForce` is then applied to the selected DOFs at each time step. For a set of indices corresponding to these DOFs, $\\mathbf{index}$, and the global force vector $\\mathbf{f}$, the force update can be written as:\n\n\\[ \\mathbf{f}[\\text{index}] += \\text{targetForce} \\]\n\n## Parameters and Data\n- **force**: applied force to all points (type: Real)\n- **forces**: forces corresponding to the key times (type: VecDeriv)\n- **arrowSizeCoef**: Size of the drawn arrows (0->no arrows, sign->direction of drawing) (type: SReal)\n\n## Dependencies and Connections\nLinearForceField requires a link to the topology container (`BaseMeshTopology`) to determine which DOFs are affected by the applied forces.\n"
}