{
  "name": "DiagonalVelocityDampingForceField",
  "main": {
    "name": "DiagonalVelocityDampingForceField",
    "namespace": "sofa::component::mechanicalload",
    "module": "Sofa.Component.MechanicalLoad",
    "include": "sofa/component/mechanicalload/DiagonalVelocityDampingForceField.h",
    "doc": "Diagonal velocity damping.\n\nApply damping forces to given degrees of freedom.",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Rigid2Types",
      "sofa::defaulttype::Rigid3Types",
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_dampingCoefficients",
        "type": "VecDeriv",
        "xmlname": "dampingCoefficient",
        "help": "velocity damping coefficients (by cinematic dof)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "DataVecDeriv &"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          },
          {
            "name": "",
            "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": "d_df",
            "type": "DataVecDeriv &"
          },
          {
            "name": "d_dx",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "",
            "type": "SReal"
          },
          {
            "name": "",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "core::behavior::StiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addBToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mat",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "bFact",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildDampingMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "core::behavior::DampingMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "params",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `DiagonalVelocityDampingForceField` is a component in the SOFA framework designed to apply velocity damping forces to specified degrees of freedom, contributing to more realistic dynamics by simulating resistance proportional to velocity. This force field interacts with other components through its inheritance from the `core::behavior::ForceField`, providing methods like `addForce` and `getPotentialEnergy`. It supports various types such as Rigid2Types, Rigid3Types, and Vec3Types for different dimensions of mechanical systems.\n\nThe key data field is `d_dampingCoefficients`, which holds the damping coefficients for each degree of freedom. Practical usage involves setting appropriate damping coefficients to simulate friction or fluid resistance effects in simulations."
  },
  "maths": {
    "maths": "The `DiagonalVelocityDampingForceField` in the SOFA framework is designed to simulate forces that resist motion, specifically velocity damping. This type of force field introduces a resistance proportional to the velocity of the degrees of freedom (DOFs) within a mechanical system, which can be used to model phenomena such as fluid drag or frictional losses.\n\n### Mathematical Formulation:\n\n1. **Force Calculation**:\n    - The force applied by `DiagonalVelocityDampingForceField` is proportional to the velocity of each DOF and is given by:\n      \n      \\[ F_i = -c_{ij} v_j \\]\n      \n      where $F_i$ represents the damping force on the i-th component, $v_j$ is the velocity in the j-th direction, and $c_{ij}$ are the elements of a diagonal matrix that contains the damping coefficients. The matrix $C = diag(c_{ij})$ is constructed from the vector `d_dampingCoefficients`.\n\n2. **Damping Coefficients**:\n    - Each element in `d_dampingCoefficients` corresponds to a specific component or direction of the DOFs. If there are more DOFs than elements in this coefficient vector, the last coefficient is reused for the remaining components.\n      \n      For example, if `d_dampingCoefficients = [c_1, c_2, ..., c_n]` and there are more than n DOFs, the damping force calculation repeats the last coefficient $c_n$ for additional DOFs.\n\n3. **Influence on Dynamics**:\n    - The inclusion of this velocity-dependent force modifies the equations of motion, introducing a term that dissipates energy from the system proportional to velocity. This can be seen in the modified equation of motion:\n      \n      \\[ m_i \frac{d^2 x_i}{dt^2} = F_{\text{other}} - c_{ij} \frac{dx_j}{dt} + F_\text{external} \\]\n      \n      where $m_i$ is the mass, $x_i$ is the position in the i-th direction, and $F_{\text{other}}$ represents other forces acting on the system.\n\n4. **Potential Energy**:\n    - The `DiagonalVelocityDampingForceField` does not contribute to potential energy since it is purely dissipative. Therefore, the function `getPotentialEnergy()` returns 0, indicating that this force field only affects kinetic energy and energy dissipation through damping forces.\n\n### Practical Application:\n\nThis component can be used in simulations where realistic damping effects are needed, such as simulating objects moving through a viscous fluid or modeling mechanical systems with friction. The ability to specify different damping coefficients for each direction allows for the simulation of anisotropic damping behaviors, which can be particularly useful in complex geometries and materials.\n\n### Numerical Implementation:\n\nThe force calculations are performed within methods like `addForce` and `addDForce`, where the velocity is multiplied by the corresponding damping coefficient to generate the resisting force. The method `buildDampingMatrix()` constructs a matrix representation of these damping forces, which can be used in more complex solvers that require linearization or stiffness/damping matrices for solving differential equations.\n\nIn summary, the `DiagonalVelocityDampingForceField` is essential for simulating realistic physical behavior by introducing velocity-dependent damping forces into mechanical systems. This component enriches simulations with dissipative effects and can be tailored to different types of mechanical behaviors through the adjustment of damping coefficients."
  },
  "summary": {
    "abstract": "The `DiagonalVelocityDampingForceField` applies velocity-dependent damping forces to specified degrees of freedom in SOFA simulations, contributing to realistic dynamics by simulating resistance proportional to velocity.",
    "sheet": "# DiagonalVelocityDampingForceField\n\n**Overview**\n\nThis component is a force field that introduces velocity-dependent damping forces into mechanical systems. It inherits from `core::behavior::ForceField` and supports various types such as Rigid2Types, Rigid3Types, and Vec3Types.\n\n**Mathematical Model**\n\nThe force applied by the `DiagonalVelocityDampingForceField` is proportional to the velocity of each degree of freedom (DOF) and is given by:\n\n\\[ F_i = -c_{ij} v_j \\]\n\nwhere $F_i$ represents the damping force on the i-th component, $v_j$ is the velocity in the j-th direction, and $c_{ij}$ are elements of a diagonal matrix containing the damping coefficients. The matrix $C = diag(c_{ij})$ is constructed from the vector `d_dampingCoefficients`. This force modifies the equations of motion by introducing a term that dissipates energy proportional to velocity.\n\n**Parameters and Data**\n\n- **`d_dampingCoefficients`**: Velocity damping coefficients (by cinematic DOF). Type: VecDeriv. These coefficients control the resistance applied to each degree of freedom, with the last coefficient reused if there are more DOFs than elements in this vector."
  }
}