{
  "name": "GearSpringForceField",
  "main": {
    "name": "GearSpringForceField",
    "namespace": "sofa::component::solidmechanics::spring",
    "module": "Sofa.Component.SolidMechanics.Spring",
    "include": "sofa/component/solidmechanics/spring/GearSpringForceField.h",
    "doc": "Gear springs for Rigids.\n\nGearSpringForceField simulates 6D springs between Rigid DOFS\n  Use kst vector to specify the directionnal stiffnesses (on each local axe)\n  Use ksr vector to specify the rotational stiffnesses (on each local axe)",
    "inherits": [
      "PairInteractionForceField"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "data",
        "type": "DataTypes"
      },
      {
        "name": "d_period",
        "type": "Real",
        "xmlname": "period",
        "help": "period between outputs"
      },
      {
        "name": "d_reinit",
        "type": "bool",
        "xmlname": "reinit",
        "help": "flag enabling reinitialization of the output file at each timestep"
      },
      {
        "name": "d_showFactorSize",
        "type": "Real",
        "xmlname": "showFactorSize",
        "help": "modify the size of the debug information of a given factor"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "addSpringForce",
        "return_type": "void",
        "params": [
          {
            "name": "potentialEnergy",
            "type": "SReal &"
          },
          {
            "name": "f1",
            "type": "VecDeriv &"
          },
          {
            "name": "p1",
            "type": "const VecCoord &"
          },
          {
            "name": "v1",
            "type": "const VecDeriv &"
          },
          {
            "name": "f2",
            "type": "VecDeriv &"
          },
          {
            "name": "p2",
            "type": "const VecCoord &"
          },
          {
            "name": "v2",
            "type": "const VecDeriv &"
          },
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "spring",
            "type": "Spring &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addSpringDForce",
        "return_type": "void",
        "params": [
          {
            "name": "df1",
            "type": "VecDeriv &"
          },
          {
            "name": "dx1",
            "type": "const VecDeriv &"
          },
          {
            "name": "df2",
            "type": "VecDeriv &"
          },
          {
            "name": "dx2",
            "type": "const VecDeriv &"
          },
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "spring",
            "type": "Spring &"
          },
          {
            "name": "kFactor",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "getObject1",
        "return_type": "core::behavior::MechanicalState<DataTypes> *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getObject2",
        "return_type": "core::behavior::MechanicalState<DataTypes> *",
        "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": "reinit",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "bwdInit",
        "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 sofa::core::MechanicalParams *"
          },
          {
            "name": "data_f1",
            "type": "DataVecDeriv &"
          },
          {
            "name": "data_f2",
            "type": "DataVecDeriv &"
          },
          {
            "name": "data_x1",
            "type": "const DataVecCoord &"
          },
          {
            "name": "data_x2",
            "type": "const DataVecCoord &"
          },
          {
            "name": "data_v1",
            "type": "const DataVecDeriv &"
          },
          {
            "name": "data_v2",
            "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": "data_df1",
            "type": "DataVecDeriv &"
          },
          {
            "name": "data_df2",
            "type": "DataVecDeriv &"
          },
          {
            "name": "data_dx1",
            "type": "const DataVecDeriv &"
          },
          {
            "name": "data_dx2",
            "type": "const DataVecDeriv &"
          }
        ],
        "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 &"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSprings",
        "return_type": "int *",
        "params": [],
        "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": "clear",
        "return_type": "void",
        "params": [
          {
            "name": "reserve",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addSpring",
        "return_type": "void",
        "params": [
          {
            "name": "s",
            "type": "const Spring &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addSpring",
        "return_type": "void",
        "params": [
          {
            "name": "m1",
            "type": "int"
          },
          {
            "name": "m2",
            "type": "int"
          },
          {
            "name": "p1",
            "type": "int"
          },
          {
            "name": "p2",
            "type": "int"
          },
          {
            "name": "hardKst",
            "type": "Real"
          },
          {
            "name": "softKsr",
            "type": "Real"
          },
          {
            "name": "hardKsr",
            "type": "Real"
          },
          {
            "name": "kd",
            "type": "Real"
          },
          {
            "name": "ratio",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getAngleAroundAxis",
        "return_type": "typename GearSpringForceField<DataTypes>::Real",
        "params": [
          {
            "name": "p1",
            "type": "Coord"
          },
          {
            "name": "p2",
            "type": "Coord"
          },
          {
            "name": "axis",
            "type": "unsigned int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getVectorAngle",
        "return_type": "void",
        "params": [
          {
            "name": "u",
            "type": "Vector"
          },
          {
            "name": "v",
            "type": "Vector"
          },
          {
            "name": "w",
            "type": "Vector &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getVectorAngle",
        "return_type": "void",
        "params": [
          {
            "name": "p1",
            "type": "Coord"
          },
          {
            "name": "p2",
            "type": "Coord"
          },
          {
            "name": "axis",
            "type": "unsigned int"
          },
          {
            "name": "w",
            "type": "Vector &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `GearSpringForceField` component in the SOFA framework simulates 6D springs between Rigid DOFs, providing both translational and rotational stiffnesses across different local axes. This component inherits from `PairInteractionForceField`, enabling it to model interactions between two rigid objects. It supports defining directional stiffness using vectors for translational (`kst`) and rotational (`ksr`) components.\n\n`GearSpringForceField` interacts with other SOFA components through its API, specifically inheriting mechanical state management functions like `addForce`, `addDForce`, and `getPotentialEnergy`. These methods allow the component to compute forces and stiffness matrices based on input parameters such as positions, velocities, and displacements. Additionally, it supports initialization (`init`) and reinitialization (`reinit`) for setting up spring properties.\n\nThis component is used in simulations involving rigid bodies where precise control over rotational and translational interactions is required. Users can specify the stiffness coefficients, damping factors, and gear ratios to customize the behavior of the simulated springs. Data fields such as `d_period`, `d_reinit`, and `d_showFactorSize` allow for configuring periodic outputs, file reinitialization flags, and visual debug information size modifications, respectively."
  },
  "maths": {
    "maths": "## Mathematical and Physical Description of GearSpringForceField Component\n\n### Overview\nThe `GearSpringForceField` component in the SOFA framework models 6D springs between rigid bodies, allowing for both translational and rotational stiffnesses along different local axes. This model is particularly useful in simulations where precise control over the interactions between rigid objects is required.\n\n### Mathematical Formulation\n\n#### Spring Force Calculation\nThe force exerted by a spring connecting two rigid bodies can be decomposed into translational and rotational components:\n\n1. **Translational Component**\n   - Let \\(\\mathbf{p}_1\\) and \\(\\mathbf{p}_2\\) be the positions of two rigid bodies.\n   - The displacement vector is given by \\(\\mathbf{d} = \\mathbf{p}_2 - \\mathbf{p}_1\\).\n   - The translational force, \\(\\mathbf{F}_{t}\\), exerted on each body due to the spring can be defined as:\n     \n     \\[\n     \\mathbf{F}_{t} = -k_{st} \\cdot \\mathbf{d}\n     \\]\n\n2. **Rotational Component**\n   - Let \\(\\mathbf{R}_1\\) and \\(\\mathbf{R}_2\\) be the rotation matrices of the rigid bodies.\n   - The relative orientation can be described by a rotation vector \\(\\mathbf{w}\\), which is obtained from the difference in rotation matrices.\n   - The rotational force, \\(\tau\tau_{r}\\), exerted on each body due to the spring can be defined as:\n     \n     \\[\n     \\tau_{r} = -k_{sr} \\cdot \\mathbf{w}\n     \\]\n\n#### Potential Energy Calculation\nThe potential energy of a spring, which is essential for computing forces through gradient calculations, can be given by the sum of translational and rotational components:\n\n1. **Translational Potential Energy**\n   \n   \\[\n   U_t = \\frac{1}{2} k_{st} \\cdot |\\mathbf{d}|^2\n   \\]\n\n2. **Rotational Potential Energy**\n   \n   \\[\n   U_r = \\frac{1}{2} k_{sr} \\cdot |\\mathbf{w}|^2\n   \\]\n\nThe total potential energy, \\(U\\), is then:\n\n\\[\nU = U_t + U_r\n\\]\n\n#### Stiffness and Damping Matrices\n- The stiffness matrix, \\(\boldsymbol{K}\\), describes how the force changes with respect to small displacements or rotations. It can be expressed as a block diagonal matrix combining translational and rotational components.\n- The damping matrix, \\(\boldsymbol{D}\\), accounts for dissipative forces that reduce energy in the system over time.\n\n### Physical Description\nThe `GearSpringForceField` models a spring between two rigid bodies by considering both translational displacements and rotational differences. It allows users to specify stiffnesses along each local axis, enabling fine-grained control over how the objects interact.\n\n1. **Translational Stiffness**\n   - The translational stiffness \\(k_{st}\\) defines how strongly the spring resists displacement in a given direction.\n\n2. **Rotational Stiffness**\n   - The rotational stiffness \\(k_{sr}\\) dictates how strongly the spring resists changes in orientation.\n\n3. **Gear Ratios and Damping Factors**\n   - Users can define gear ratios to simulate complex mechanical interactions, where rotations of one body affect another according to a specified ratio.\n   - Damping factors control energy dissipation due to motion or rotation.\n\n### Usage Scenarios\nThe `GearSpringForceField` is particularly useful in simulations involving rigid bodies where precise interaction behavior needs to be modeled. Applications include mechanical systems, robotics, and any scenario requiring detailed simulation of translational and rotational interactions between objects.\n"
  },
  "summary": {
    "abstract": "`GearSpringForceField` simulates 6D springs between rigid bodies with specified translational and rotational stiffnesses, enabling precise control over interactions in SOFA simulations.",
    "sheet": "# GearSpringForceField\n\n## Overview\nThe `GearSpringForceField` component models 6D springs between rigid bodies, providing both translational and rotational stiffnesses. It inherits from `PairInteractionForceField`, allowing it to manage interactions between two rigid objects.\n\n## Mathematical Model\n### Spring Force Calculation\nThe force exerted by a spring connecting two rigid bodies can be decomposed into translational and rotational components:\n\n1. **Translational Component**\n   - Let \\(\\mathbf{p}_1\\) and \\(\\mathbf{p}_2\\) be the positions of two rigid bodies.\n   - The displacement vector is given by \\(\\mathbf{d} = \\mathbf{p}_2 - \\mathbf{p}_1\\).\n   - The translational force, \\(\\mathbf{F}_{t}\\), exerted on each body due to the spring can be defined as:\n     \n     \\[\n     \\mathbf{F}_{t} = -k_{st} \\cdot \\mathbf{d}\n     \\]\n\n2. **Rotational Component**\n   - Let \\(\\mathbf{R}_1\\) and \\(\\mathbf{R}_2\\) be the rotation matrices of the rigid bodies.\n   - The relative orientation can be described by a rotation vector \\(\\mathbf{w}\\), which is obtained from the difference in rotation matrices.\n   - The rotational force, \\(\tau_{r}\\), exerted on each body due to the spring can be defined as:\n     \n     \\[\n     \tau_{r} = -k_{sr} \\cdot \\mathbf{w}\n     \\]\n\n### Potential Energy Calculation\nThe potential energy of a spring, which is essential for computing forces through gradient calculations, can be given by the sum of translational and rotational components:\n\n1. **Translational Potential Energy**\n   \n   \\[\n   U_t = \\frac{1}{2} k_{st} \\cdot |\\mathbf{d}|^2\n   \\]\n\n2. **Rotational Potential Energy**\n   \n   \\[\n   U_r = \\frac{1}{2} k_{sr} \\cdot |\\mathbf{w}|^2\n   \\]\n\nThe total potential energy, \\(U\\), is then:\n\n\\[\nU = U_t + U_r\n\\]\n\n## Parameters and Data\n- **d_period**: Period between outputs (type: Real).\n- **d_reinit**: Flag enabling reinitialization of the output file at each timestep (type: bool).\n- **d_showFactorSize**: Modifies the size of the debug information for a given factor (type: Real).\n\n## Dependencies and Connections\n`GearSpringForceField` typically requires connections to rigid bodies and exchanges data with other components that manage mechanical states, such as `MechanicalState`. It fits into the scene graph by connecting two rigid objects and applying forces based on their relative positions and orientations.\n\n## Practical Notes\nUsers should carefully configure stiffness coefficients \\(k_{st}\\) and \\(k_{sr}\\) to ensure numerical stability. Gear ratios and damping factors can be adjusted for more complex mechanical interactions."
  }
}