{
  "name": "AngularSpringForceField",
  "main": {
    "name": "AngularSpringForceField",
    "namespace": "sofa::component::solidmechanics::spring",
    "module": "Sofa.Component.SolidMechanics.Spring",
    "include": "sofa/component/solidmechanics/spring/AngularSpringForceField.h",
    "doc": "Angular springs applied to rotational degrees of freedom of a rigid body or frame.\n\nThis class describes a simple elastic springs ForceField between DOFs positions and rest positions.\nSprings are applied to given degrees of freedom between their current positions and their rest shape positions.\nAn external MechanicalState reference can also be passed to the ForceField as rest shape position.",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "d_angularStiffness",
        "type": "VecReal",
        "xmlname": "angularStiffness",
        "help": "angular stiffness for the controlled nodes"
      },
      {
        "name": "d_angularLimit",
        "type": "VecReal",
        "xmlname": "limit",
        "help": "angular limit (max; min) values where the force applies"
      },
      {
        "name": "d_drawSpring",
        "type": "bool",
        "xmlname": "drawSpring",
        "help": "draw Spring"
      },
      {
        "name": "d_springColor",
        "type": "type::RGBAColor",
        "xmlname": "springColor",
        "help": "spring color"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "bwdInit",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "reinit",
        "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": "df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "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": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "matrix",
            "type": "const sofa::core::behavior::MultiMatrixAccessor *"
          }
        ],
        "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"
      }
    ]
  },
  "desc": {
    "description": "The `AngularSpringForceField` is a force field in SOFA that applies elastic angular springs to the rotational degrees of freedom of rigid bodies or frames. It computes forces based on the deviation from rest positions for specified nodes, using predefined stiffness values and optional angular limits. This component inherits from `core::behavior::ForceField`, enabling integration into mechanical simulations by contributing to force calculations and matrix assembly.\n\n**Interactions with other SOFA components:**\n- **MechanicalState**: The component relies on an external MechanicalState for rest positions, which can be set via the API. This allows it to interact with different parts of a simulation's mechanical state.\n- **Data Fields**: It interacts with various Data fields, including stiffness values (`angularStiffness`), angular limits (`limit`), and drawing parameters (`drawSpring`, `springColor`).\n\n**Practical Usage Guidance:**\n- Define the nodes to be controlled by setting the `indices` field.\n- Specify the stiffness for each node through the `angularStiffness` field. If not defined, a default value of 100 is assumed.\n- Optionally set angular limits using the `limit` field.\n- Use `drawSpring` and `springColor` to visualize the springs in the simulation.\n\n**Data Fields:**\n- **indices**: Indexes of nodes controlled by the angular springs.\n- **angularStiffness**: Angular stiffness values for each node.\n- **limit**: Angular limits where force application is bounded (max, min).\n- **drawSpring**: Boolean to enable drawing of the springs.\n- **springColor**: Color used for visualizing the springs."
  },
  "maths": {
    "response": "The `AngularSpringForceField` in SOFA is designed to apply elastic forces on rigid bodies or frames based on their rotational deviations from predefined rest positions. This force field operates by using angular springs that connect specified nodes, ensuring the simulation captures realistic rotational behaviors influenced by stiffness and optional angular limits. Below is a detailed mathematical and physical description of this component.\n\n### Mathematical Formulation\n\n#### Angular Deviation Calculation:\n\nFor each pair of consecutive nodes indexed from 1 to N (where N is the number of specified indices), the angular deviation between their orientations is calculated using quaternions. Given two quaternions representing the orientations of the current node `q_i` and the previous node `q_{i-1}`, the relative quaternion `dq` is computed as:\n\n\ndq = q_i * conj(q_{i-1})\n\nwhere `conj(q)` represents the conjugate of the quaternion `q`. The relative orientation `dq` can be decomposed into an axis-angle representation where `axis` and `angle` are derived from `dq`.\n\n#### Axis-Angle Decomposition:\n\nThe angle between the orientations is extracted by normalizing the quaternion and applying trigonometric functions. Specifically, if `dq = (x, y, z, w)` represents a unit quaternion with components `(x, y, z)` for the imaginary part and `w` for the real part, the angle of rotation `θ` can be computed as follows:\n\n1. Compute `sin_half_theta`, the sine of half the angle of rotation:\n\n   \nsin_half_theta = sqrt(x^2 + y^2 + z^2)\n\n2. Determine `θ` using either `acos` or a fallback for small angles (to avoid numerical instability):\n\n   - For large angles: θ = 2 * acos(w) where `w` is the real part of the quaternion.\n   - For small angles (where `|w| > 0.999999`): Use a Taylor series approximation for `sin(θ/2)` and calculate θ accordingly.\n\nThe axis of rotation, denoted as `axis`, can be obtained by normalizing the imaginary part of the quaternion:\n\n   \naxis = (x, y, z) / sin_half_theta\n\n#### Force Calculation:\n\nGiven the angle `θ` and the axis of rotation `axis`, the force applied to each node due to its deviation from rest position is calculated as follows. For a stiffness coefficient `k_i` associated with the i-th pair of nodes, the torque (rotational force) `τ` is given by:\n\n   \nτ = -k_i * axis * θ\n\nThis torque is applied in the negative direction to counteract the deviation from the rest position.\n\n#### Damping and Stiffness Matrix Contributions:\n\nThe damping term, which accounts for energy dissipation due to rotational motion, is typically included as part of `core::mechanicalparams`. The stiffness matrix contribution represents how changes in orientation affect the forces applied. For each node `i`, the diagonal elements of the stiffness matrix are updated by adding `-k_i` multiplied by a scaling factor that includes Rayleigh damping.\n\n### Physical Interpretation:\n\nThe force field emulates elastic rotational constraints between rigid bodies or frames, simulating behaviors such as torsional springs found in mechanical systems. These constraints ensure that nodes maintain predefined angular relationships with each other. The stiffness `k_i` determines the rigidity of these connections, while optional limits can restrict the range of permissible rotations.\n\n### Visualization:\n\nThe force field can be visualized by drawing lines between specified node pairs, allowing users to observe how rotational forces influence the simulation's behavior. This is enabled through parameters like `drawSpring` and `springColor`, which control whether springs are drawn and their color in the visualization."
  },
  "summary": {
    "abstract": "The `AngularSpringForceField` applies elastic angular springs to the rotational degrees of freedom of rigid bodies or frames, contributing forces based on deviation from rest positions using predefined stiffness values and optional angular limits.",
    "sheet": "# AngularSpringForceField\n\n## Overview\nThe `AngularSpringForceField` is a force field that applies elastic angular springs to the rotational degrees of freedom of rigid bodies or frames. It inherits from `core::behavior::ForceField`, enabling integration into mechanical simulations by contributing to force calculations and matrix assembly.\n\n## Mathematical Model\nThe component computes forces based on the deviation from rest positions for specified nodes, using predefined stiffness values and optional angular limits. The potential energy function is given by:\n\\[ U(\\theta) = \\frac{1}{2} k (\\theta - \\theta_0)^2 \\]\nwhere \\(k\\) is the angular stiffness, \\(\\theta\\) is the current angle, and \\(\\theta_0\\) is the rest angle. The force applied to each node is:\n\\[ f = -k (\\theta - \\theta_0) \\]\nThe component also supports angular limits where the force application is bounded by specified maximum and minimum values.\n\n## Parameters and Data\n- **angularStiffness**: Angular stiffness values for each node. Type: `VecReal`. Default value not explicitly defined, but a default of 100 can be assumed if not set.\n- **limit**: Angular limits where force application is bounded (max; min) values. Type: `VecReal`.\n- **drawSpring**: Boolean to enable drawing of the springs. Type: `bool`. Default value: `false`.\n- **springColor**: Color used for visualizing the springs. Type: `type::RGBAColor`. Default value not explicitly defined."
  }
}