Data Fields

Methods

{
  "name": "TorsionForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/TorsionForceField.h",
  "doc": "Applies a torque to specified degrees of freedom.\n\nTorsionForceField\nThis forcefield applies a torque to a set of selected nodes. The force is applied from a specified axis (origin and direction)\nand a torque value.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_indices",
      "type": "VecId",
      "xmlname": "indices",
      "help": "indices of the selected points"
    },
    {
      "name": "d_torque",
      "type": "Real",
      "xmlname": "torque",
      "help": "torque to apply"
    },
    {
      "name": "d_axis",
      "type": "Pos",
      "xmlname": "axis",
      "help": "direction of the axis (will be normalized)"
    },
    {
      "name": "d_origin",
      "type": "Pos",
      "xmlname": "origin",
      "help": "origin of the axis"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const 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 MechanicalParams *"
        },
        {
          "name": "df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "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": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `TorsionForceField` is a SOFA component under the `sofa::component::mechanicalload` namespace, which applies torque to specified degrees of freedom in a simulation. This force field is designed to apply rotational forces from a specified axis (defined by an origin and direction) with a given torque value.\n\n### Role and Purpose\nThe primary role of `TorsionForceField` is to introduce rotational dynamics into the mechanical system being simulated. It can be particularly useful in scenarios where rotation or twisting motions need to be incorporated, such as in simulations involving flexible structures or rigid bodies that undergo torsional deformation.\n\n### Interactions with Other Components\n- **Mechanical State**: `TorsionForceField` interacts with the mechanical state of the simulation by modifying forces and displacements via methods like `addForce`, `addDForce`, `buildStiffnessMatrix`, and `getPotentialEnergy`. It inherits from `sofa::core::behavior::ForceField`, which provides an interface for applying mechanical loads to nodes.\n- **Topology**: The indices of the selected points (nodes) are specified through the `d_indices` data field, allowing it to apply forces only to specific parts of a model.\n\n### Practical Usage Guidance and Data Fields\n- **indices (`Data<VecId> d_indices`)**: Indices of the nodes where the torque will be applied. This allows for selective application of rotational forces on particular regions or components within the simulation.\n- **torque (`Data<Real> d_torque`)**: The magnitude of the torque to apply, defining how strongly the selected nodes are rotated.\n- **axis (`Data<Pos> d_axis`)**: Direction vector of the axis around which the torque is applied. This vector will be normalized internally by the component.\n- **origin (`Data<Pos> d_origin`)**: The origin point from where the axis starts, defining the rotation's reference point.\n\n### Methods and Functionality\n- `addForce`: Adds rotational forces to the specified nodes based on the provided torque value and axis direction.\n- `addDForce`: Computes differential forces for numerical integration schemes, enabling more accurate time-stepping in simulations.\n- `buildStiffnessMatrix` and `addKToMatrix`: Construct stiffness matrices to handle the linearized effects of applied torques during implicit integration steps.\n\nOverall, `TorsionForceField` provides a versatile mechanism to introduce rotational dynamics into SOFA simulations, supporting both explicit force application and numerical stability in complex mechanical systems.",
  "maths": "The **TorsionForceField** component in the SOFA framework applies a torque to specified degrees of freedom within a mechanical system. This force field introduces rotational dynamics, which can be particularly useful for simulations involving flexible structures or rigid bodies that undergo torsional deformation.\n\n### Governing Equations and Operators\n- The primary contribution of this component is to add **internal forces** ($f_{int}$) due to the applied torque to specific degrees of freedom (DOFs). Mathematically, these internal forces can be expressed as:\n\n\begin{align*}\n    f^{e}_{int} &= \tau \\times r\n\\end{align*}\nwhere $\\tau$ is the torque vector and $r$ is the position vector from the origin of rotation to the point where the torque is applied.\n\n- The torque vector is defined along a specified axis ($d_{axis}$) with magnitude given by the data field $d_{torque}$. This results in the following force expression for each selected node $i$:\n\n\begin{align*}\n    f_i &= \\tau m_u \\times (q_i - o)\n\\end{align*}\nwhere $m_u$ is the normalized axis direction vector, and $o$ is the origin of rotation.\n\n### Constitutive Laws and Kinematics\n- The force field operates on a set of selected nodes specified by indices ($d_{indices}$). It introduces rotational kinematics into the system through the cross product operation between the torque vector and the position vector relative to the origin of rotation.\n\n### Role in Global FEM Pipeline\n1. **Assembly**: TorsionForceField contributes to the assembly phase by adding internal forces due to applied torques, as computed via `addForce` method:\n    \begin{align*}\n        f_i &= \\tau m_u \\times (q_i - o)\n    \\end{align*}\n2. **Time Integration**: The rotational forces are included in the dynamic equation during time integration:\n\n\begin{align*}\n   M\\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t)\n\\end{align*}\nwhere $f_{int}$ includes contributions from TorsionForceField.\n3. **Nonlinear Solve**: The forces are linearized and included in the tangent stiffness matrix, as computed via `addDForce` method:\n    \begin{align*}\n        df_i &= D \\cdot dq_i\n    \\end{align*}\nwhere $D$ is a rotation-dependent Jacobian matrix.\n4. **Linear Solve**: The linearized forces contribute to the stiffness matrix assembly, as computed via `buildStiffnessMatrix` and `addKToMatrix` methods:\n    \begin{align*}\n        K_e &= \\frac{\\partial f_{int}^e}{\\partial x_e}\n    \\end{align*}\n\n### Numerical Methods and Discretization Choices\n- The component uses a direct approach to compute the internal forces in `addForce` by applying the cross product operation between the torque vector and position vectors.\n- For numerical stability, the stiffness matrix is constructed using finite differences, as seen in the `buildStiffnessMatrix` method. This ensures that the rotational effects are properly captured during implicit time integration steps.\n\n### Variational/Lagrangian Mechanics Framework Fit\n- The TorsionForceField fits into the broader variational and Lagrangian mechanics framework by providing a mechanism to add specific types of external forces (torques) to the system. These forces contribute to the total potential energy of the system, which is then used in the variational formulation:\n    \begin{align*}\n        \\mathcal{L}(q,\\dot q) &= T(q,\\dot q) - V(q)\n    \\end{align*}\n- The applied torques modify the kinetic energy term $T$ due to rotational motion and can influence the potential energy term $V$, particularly in systems where rotation affects the configuration space.",
  "abstract": "The `TorsionForceField` applies torque to specified degrees of freedom in a mechanical system, introducing rotational dynamics through internal forces computed from the cross product between the torque vector and position vectors relative to an origin.",
  "sheet": "# TorsionForceField\n\n**Overview**\n\nThe `TorsionForceField` is a SOFA component that applies torque to specified degrees of freedom in a mechanical system, introducing rotational dynamics. It inherits from `sofa::core::behavior::ForceField`, providing an interface for applying mechanical loads to nodes.\n\n**Mathematical Model**\n\nThe primary contribution of this component is to add internal forces ($f_{int}$) due to the applied torque to specific degrees of freedom (DOFs). Mathematically, these internal forces can be expressed as:\n\n\\[ f^{e}_{int} = \\tau \\times r \\]\n\nwhere $\\tau$ is the torque vector and $r$ is the position vector from the origin of rotation to the point where the torque is applied. For each selected node $i$, the force expression is given by:\n\n\\[ f_i = \\tau m_u \\times (q_i - o) \\]\n\nwhere $m_u$ is the normalized axis direction vector, and $o$ is the origin of rotation.\n\n**Parameters and Data**\n\n- **indices (`Data<VecId> d_indices`)**: Indices of the nodes where the torque will be applied. This allows for selective application of rotational forces on particular regions or components within the simulation.\n- **torque (`Data<Real> d_torque`)**: The magnitude of the torque to apply, defining how strongly the selected nodes are rotated.\n- **axis (`Data<Pos> d_axis`)**: Direction vector of the axis around which the torque is applied. This vector will be normalized internally by the component.\n- **origin (`Data<Pos> d_origin`)**: The origin point from where the axis starts, defining the rotation's reference point."
}