Data Fields

Links

Methods

{
  "name": "OscillatingTorsionPressureForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/OscillatingTorsionPressureForceField.h",
  "doc": "OscillatingTorsionPressure.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_moment",
      "type": "Real",
      "xmlname": "moment",
      "help": "Moment force applied on the entire surface"
    },
    {
      "name": "d_axis",
      "type": "Deriv",
      "xmlname": "axis",
      "help": "Axis of rotation and normal direction for the plane selection of triangles"
    },
    {
      "name": "d_center",
      "type": "Coord",
      "xmlname": "center",
      "help": "Center of rotation"
    },
    {
      "name": "d_penalty",
      "type": "Real",
      "xmlname": "penalty",
      "help": "Strength of the penalty force"
    },
    {
      "name": "d_frequency",
      "type": "Real",
      "xmlname": "frequency",
      "help": "frequency of oscillation"
    },
    {
      "name": "d_dmin",
      "type": "Real",
      "xmlname": "dmin",
      "help": "Minimum distance from the origin along the normal direction"
    },
    {
      "name": "d_dmax",
      "type": "Real",
      "xmlname": "dmax",
      "help": "Maximum distance from the origin along the normal direction"
    },
    {
      "name": "d_showForces",
      "type": "bool",
      "xmlname": "showForces",
      "help": "draw triangles which have a given pressure"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single"
    }
  ],
  "methods": [
    {
      "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": "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": "",
          "type": "DataVecDeriv &"
        },
        {
          "name": "",
          "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": "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": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDminAndDmax",
      "return_type": "void",
      "params": [
        {
          "name": "_dmin",
          "type": "const SReal"
        },
        {
          "name": "_dmax",
          "type": "const SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setAxis",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "const Coord"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMoment",
      "return_type": "void",
      "params": [
        {
          "name": "x",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getAmplitude",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRotationAngle",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "selectTrianglesAlongPlane",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "selectTrianglesFromString",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initTriangleInformation",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "isPointInPlane",
      "return_type": "bool",
      "params": [
        {
          "name": "p",
          "type": "Coord"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getVecFromRotAxis",
      "return_type": "Coord",
      "params": [
        {
          "name": "x",
          "type": "const Coord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getAngle",
      "return_type": "Real",
      "params": [
        {
          "name": "v1",
          "type": "const Coord &"
        },
        {
          "name": "v2",
          "type": "const Coord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `OscillatingTorsionPressureForceField` is a force field in the SOFA framework designed to apply oscillatory torsional forces on specific regions defined by triangles within a mesh. It inherits from `core::behavior::ForceField`, which indicates it directly influences mechanical properties like position and velocity of points in a simulation.\n\nThis component interacts with other components through its API, particularly requiring access to topology data via the `l_topology` link. The force field relies on various fields such as `d_moment` (torsional moment), `d_axis` (axis of rotation), `d_center` (center of rotation), and `d_penalty` (strength of penalty forces). It also supports customization through parameters like oscillation frequency (`d_frequency`) and distance thresholds (`d_dmin`, `d_dmax`).\n\nThe force field calculates torsional pressure based on the current state, applying these forces to active points identified by their distances from a defined axis and center. The component can visualize selected triangles with pressures using its drawing capabilities.\n\nPractical usage involves setting up topology links, specifying necessary parameters like rotation axis, center, and moment of force, and optionally configuring oscillation frequency and penalty strength for precise control over the simulation dynamics.",
  "maths": "The `OscillatingTorsionPressureForceField` is a force field that applies oscillatory torsional forces to specific regions within a mesh, defined by triangles. It contributes directly to the internal force vector $f_{int}$ in the global mechanical system of equations. The governing equation for this component can be summarized as follows:\n\n### Governing Equations and Operators\nThe component calculates both penalty forces and additional moment forces based on the current configuration. These forces are added to the total internal force vector:\n\n\begin{equation}\n f_{int} = f_{penalty} + f_{moment}\n\\end{equation}\n\nwhere $f_{penalty}$ represents the penalty forces and $f_{moment}$ represents the additional moment forces.\n\n### Constitutive Laws\nThe force field does not follow a standard constitutive law but instead applies custom torsional pressure based on user-defined parameters. The internal forces are computed as follows:\n\n1. **Penalty Forces**\nFor each point $i$ where `pointActive[i]` is true, the penalty force is calculated as:\n\n\\begin{equation}\n f_{penalty,i} = δ⟹_i \\cdot d_{penalty},\n\\end{equation}\nwhere $d_{penalty}$ is the strength of the penalty force, and $δ⟹_i$ is the displacement from the ideal position defined by:\n\n\\begin{equation}\n δ⟹_i = x^{○}_i - x_i,\n\\end{equation}\nwhere $x^{○}_i$ is the rotated and translated ideal position, given by:\n\n\\begin{equation}\n x^{○}_i = αΔ_{axis} (Χ_i - φ_i) + φ_i,\n\\end{equation}\nwith $Q$ being the rotation quaternion defined by `d_axis` and `avgRotAngle`, $Χ_i = x_i - d_{center}$, and $φ_i$ is the original position relative to the center.\n\n2. **Moment Forces**\nThe remaining moment force $f_{moment,i}$ is calculated as:\n\n\\begin{equation}\n f_{moment,i} = Δ⟹_i \\cdot d_moment,\n\\end{equation}\nwhere $Δ⟹_i$ is the normalized direction vector, and $d_moment$ is the oscillating moment force.\n\n### Role in the Global FEM Pipeline\nThe `OscillatingTorsionPressureForceField` operates within the assembly phase of the global FEM pipeline. Specifically, it contributes to the internal force term during the nonlinear solve step by adding forces to $f_{int}$. This component also handles constraints and mappings to ensure that only specified triangles contribute to the force field.\n\n### Numerical Methods and Discretization Choices\nThe component uses a custom numerical method for calculating torsional pressure based on user-defined parameters. It employs implicit time integration through `addForce` to compute forces at each timestep, and it handles constraints such as distance thresholds (`d_dmin`, `d_dmax`) and the selection of active triangles.\n\n### Variational / Lagrangian Mechanics Framework\nWhile this component does not directly stem from a variational principle or Lagrangian mechanics, its internal force calculations are consistent with the overall framework by contributing to $f_{int}$ in the nonlinear solve step. The penalty forces ensure mechanical consistency through an energy minimization approach, while the moment forces provide a custom oscillatory behavior.\n\n### Summary\nThe `OscillatingTorsionPressureForceField` implements torsional pressure forces that are added to the internal force vector $f_{int}$ within the global FEM simulation pipeline. It uses custom numerical methods for calculating these forces and ensures mechanical consistency through penalty forces.",
  "abstract": "The `OscillatingTorsionPressureForceField` applies oscillatory torsional forces to specified triangular regions in a mesh, contributing to the internal force vector $f_{int}$ through penalty and moment forces.",
  "sheet": "# OscillatingTorsionPressureForceField\n\n## Overview\nThe `OscillatingTorsionPressureForceField` is a force field component that applies oscillatory torsional forces to specific regions within a mesh, defined by triangles. It inherits from the `core::behavior::ForceField` class and requires topology data via the `l_topology` link.\n\n## Mathematical Model\nThe governing equations for this component are as follows:\n\n### Internal Forces\nThe internal force vector $f_{int}$ is composed of penalty forces $f_{penalty}$ and moment forces $f_{moment}$:\n\\[ f_{int} = f_{penalty} + f_{moment} \\]\n\n#### Penalty Forces\nFor each active point $i$, the penalty force is calculated as:\n\\[ f_{penalty,i} = δ⟹_i \\\\cdot d_{penalty}, \\]\nwhere $d_{penalty}$ is the strength of the penalty force, and $δ⟹_i$ is the displacement from the ideal position defined by:\n\\[ δ⟹_i = x^{○}_i - x_i. \\]\nThe rotated and translated ideal position $x^{○}_i$ is given by:\n\\[ x^{○}_i = αΔ_{axis} (Χ_i - φ_i) + φ_i, \\]\nwith $Q$ being the rotation quaternion defined by `d_axis` and `avgRotAngle`, $Χ_i = x_i - d_{center}$, and $φ_i$ is the original position relative to the center.\n\n#### Moment Forces\nThe moment force for each point $i$ is calculated as:\n\\[ f_{moment,i} = Δ⟹_i \\\\cdot d_moment, \\]\nwhere $Δ⟹_i$ is the normalized direction vector, and $d_moment$ is the oscillating moment force.\n\n## Parameters and Data\nThe significant data fields exposed by this component are:\n\n- `moment`: Moment force applied on the entire surface (`Real`)\n- `axis`: Axis of rotation and normal direction for the plane selection of triangles (`Deriv`)\n- `center`: Center of rotation (`Coord`)\n- `penalty`: Strength of the penalty force (`Real`)\n- `frequency`: Frequency of oscillation (`Real`)\n- `dmin`: Minimum distance from the origin along the normal direction (`Real`)\n- `dmax`: Maximum distance from the origin along the normal direction (`Real`)\n- `showForces`: Draw triangles which have a given pressure (`bool`)\n\n## Dependencies and Connections\nThis component requires topology data via the `l_topology` link to identify active points within the mesh.\n"
}