{
  "name": "DampVelocitySolver",
  "main": {
    "name": "DampVelocitySolver",
    "namespace": "sofa::component::odesolver::forward",
    "module": "Sofa.Component.ODESolver.Forward",
    "include": "sofa/component/odesolver/forward/DampVelocitySolver.h",
    "doc": "Reduce the velocities.\n\nVelocity damping and thresholding.\nThis is not an ODE solver, but it can be used as a post-process after a real ODE solver.",
    "inherits": [
      "OdeSolver"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_rate",
        "type": "SReal",
        "xmlname": "rate",
        "help": "Factor used to reduce the velocities. Typically between 0 and 1."
      },
      {
        "name": "d_threshold",
        "type": "SReal",
        "xmlname": "threshold",
        "help": "Threshold under which the velocities are canceled."
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "solve",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const core::ExecParams *"
          },
          {
            "name": "dt",
            "type": "SReal"
          },
          {
            "name": "xResult",
            "type": "sofa::core::MultiVecCoordId"
          },
          {
            "name": "vResult",
            "type": "sofa::core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getIntegrationFactor",
        "return_type": "SReal",
        "params": [
          {
            "name": "inputDerivative",
            "type": "int"
          },
          {
            "name": "outputDerivative",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSolutionIntegrationFactor",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The **DampVelocitySolver** is not an ODE solver but serves as a post-processing tool to reduce and threshold velocities in SOFA simulations. It inherits from `OdeSolver`, facilitating its integration into the simulation pipeline.\n\n### Role and Purpose\n- The primary role of this component is to dampen the velocities of objects within the simulation, which can help stabilize simulations by reducing oscillations or other high-frequency behaviors. \n- Additionally, it sets a velocity threshold below which velocities are canceled, effectively stopping motion when it falls below certain thresholds.\n\n### Interactions with Other Components\n- It interacts primarily through its `solve` method, inherited from the `OdeSolver` interface, allowing it to process results after other ODE solvers have computed new states.\n- Through methods like `getIntegrationFactor`, it integrates into SOFA's broader framework for handling differential equations and updating physical state over time.\n\n### Practical Usage Guidance\n- **Data Fields**:\n  - `rate`: A factor used to reduce velocities. Typically a value between 0 (no damping) and 1 (maximum damping).\n  - `threshold`: Threshold under which the velocities are canceled, effectively stopping motion below this value.\n\n- The component processes velocity vectors by multiplying them with an exponential reduction factor based on the specified rate and time step (`dt`). If a threshold is set, velocities below that threshold are then canceled.\n"
  },
  "maths": {
    "maths": "<p>The <strong>DampVelocitySolver</strong> is not an ODE solver but serves as a post-processing tool to reduce and threshold velocities in simulations. It operates by modifying the velocity vectors of the objects within the simulation.</p>\n\n<h3 id=\"mathematical-description\">Mathematical Description</h3>\n\n<p>The <code>DampVelocitySolver</code> applies two key operations on the velocity vector <span class=\"math-inline\"><strong>v</strong></span>:</p>\n\n<ol type=\"1\">\n<li><strong>Exponential Damping:</strong> The velocities are reduced by multiplying them with an exponential factor. Given a damping rate \\(r\\) and time step \\(dt\\), the new velocity vector <span class=\"math-inline\"><strong>v</strong><sub>new</sub></span> is computed as:</li>\n</ol>\n\n<p><span class=\"math-display\">\\[ \\textbf{v}_{new} = e^{-r \times dt} \\cdot \\textbf{v}_{old} \\]</span></p>\n\n<ol start=\"2\" type=\"1\">\n<li><strong>Thresholding:</strong> Velocities below a specified threshold are canceled. If the magnitude of any velocity component <span class=\"math-inline\">v_i</span> is less than or equal to a threshold value \\(T\\), then that component is set to zero.</li>\n</ol>\n\n<p>The mathematical formulation can be written as:</p>\n\n<p><span class=\"math-display\">\\[ v_{i, new} = \n\\begin{cases}\n    0 &amp; \\text{if } |v_i| \\leq T \\\\\n    e^{-r \\times dt} \\cdot v_i &amp; \\text{otherwise}\n\\end{cases}\\]</span></p>\n\n<h3 id=\"integration-factor\">Integration Factor</h3>\n\n<p>The component also defines the integration factor, which describes how different orders of derivatives (position, velocity, acceleration) affect each other. Specifically:</p>\n\n<ul>\n<li>Position does not change.</li>\n<li>Velocity is damped by an exponential factor \\(e^{-r \times dt}\\).</li>\n<li>Acceleration is not considered directly and remains zero in this context.</li>\n</ul>\n\n<p>The integration factors are represented as follows:</p>\n\n<p><span class=\"math-display\">\\[ M = \\begin{pmatrix}\n    1 &amp; 0 \\\\\n    0 &amp; e^{-r \\times dt} \\\\\n    0 &amp; 0\n\\end{pmatrix}\\]</span></p>\n\n<p>This matrix indicates how derivatives are integrated into the new state. For instance:</p>\n\n<ul>\n<li>The position remains unchanged.</li>\n<li>The velocity is reduced by an exponential factor.</li>\n<li>Acceleration is not affected directly (set to zero).</li>\n</ul>\n\n<h3 id=\"practical-implications\">Practical Implications</h3>\n\n<ul>\n<li><strong>Damping:</strong> The damping effect helps stabilize simulations by reducing high-frequency oscillations or other unstable behaviors.</li>\n<li><strong>Thresholding:</strong> Setting a velocity threshold below which motion is stopped can help prevent unnecessary small movements and further stabilize the simulation.</li>\n</ul>"
  },
  "summary": {
    "abstract": "The DampVelocitySolver reduces and thresholds velocities in SOFA simulations by applying an exponential damping factor and canceling velocities below a specified threshold.",
    "sheet": "# DampVelocitySolver\n\n## Overview\nThe DampVelocitySolver is not an ODE solver but serves as a post-processing tool to reduce and threshold velocities in SOFA simulations. It inherits from `OdeSolver`, facilitating its integration into the simulation pipeline.\n\n## Mathematical Model\nThe DampVelocitySolver applies two key operations on the velocity vector \\(\\textbf{v}\\):\n\n1. **Exponential Damping:** The velocities are reduced by multiplying them with an exponential factor. Given a damping rate \\(r\\) and time step \\(dt\\), the new velocity vector \\(\\textbf{v}_{new}\\) is computed as:\n   \n   \\[ \\textbf{v}_{new} = e^{-r \\times dt} \\cdot \\textbf{v}_{old} \\]\n\n2. **Thresholding:** Velocities below a specified threshold are canceled. If the magnitude of any velocity component \\(v_i\\) is less than or equal to a threshold value \\(T\\), then that component is set to zero.\n   \n   The mathematical formulation can be written as:\n\n   \\[ v_{i, new} = \n   \\begin{cases}\n       0 & \\text{if } |v_i| \\leq T \\\\\n       e^{-r \\times dt} \\cdot v_i & \\text{otherwise}\n   \\end{cases}\\]\n\n## Parameters and Data\nThe significant Data fields exposed by the component are:\n\n- `rate`: A factor used to reduce velocities. Typically a value between 0 (no damping) and 1 (maximum damping).\n- `threshold`: Threshold under which the velocities are canceled, effectively stopping motion below this value."
  }
}