Data Fields

Methods

{
  "name": "UniformVelocityDampingForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/UniformVelocityDampingForceField.h",
  "doc": "Uniform 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_dampingCoefficient",
      "type": "Real",
      "xmlname": "dampingCoefficient",
      "help": "velocity damping coefficient"
    },
    {
      "name": "d_implicit",
      "type": "bool",
      "xmlname": "implicit",
      "help": "should it generate damping matrix df/dv? (explicit otherwise, i.e. only generating a force)"
    }
  ],
  "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": "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"
    }
  ],
  "description": "The `UniformVelocityDampingForceField` is a SOFA component that applies uniform velocity damping forces to given degrees of freedom within a simulation. It inherits from the `core::behavior::ForceField` class, allowing it to interact with other mechanical components in the scene graph architecture.\n\n### Role and Purpose:\nThis force field is designed to model viscous damping effects by applying a force that opposes motion proportional to velocity. The magnitude of this force can be controlled through the damping coefficient parameter. This component helps simulate realistic behavior for objects undergoing motion, such as soft tissues or deformable bodies in medical simulations.\n\n### Interactions with Other Components:\nThe `UniformVelocityDampingForceField` interacts with other components via its API methods such as `addForce`, `addDForce`, and matrix assembly routines like `addBToMatrix` and `buildDampingMatrix`. These methods enable the component to integrate into the overall mechanical simulation process. The force field can contribute to the system of equations, either implicitly by adding damping matrices or explicitly by generating forces directly.\n\n### Practical Usage Guidance:\n- **Data Fields:**\n  - `d_dampingCoefficient`: Controls the strength of the damping effect (velocity damping coefficient).\n  - `d_implicit`: Determines whether the force field should generate a damping matrix (`df/dv`) for implicit integration or operate in explicit mode, generating only forces.\n\n- **Usage Considerations:**\n  - The component supports various data types including rigid and vector-based representations.\n  - Adjusting the damping coefficient can significantly affect the behavior of simulated objects; lower values result in less resistance to motion, while higher values increase damping effects.\n  - Setting `d_implicit` to true is necessary for implicit integration schemes that require damping matrices.",
  "maths": "### Governing Equations and Operators\n\nThe `UniformVelocityDampingForceField` component implements velocity-dependent damping forces, which contribute to the overall mechanical system through various operators.\n\n#### Damping Force\n\nThe damping force \\\\( f_d \\\\), applied at each degree of freedom (DOF) is given by:\n\n\begin{equation}\n    f_d = - c \\dot{x},\n\tag{1}\n\text{}\n\text{where:}\n\text{}\n\\begin{aligned}\n    & c && : \text{damping coefficient} (\\mathbf{d_{dampingCoefficient}}),\\\\\n    & \\dot{x} && : \text{velocity vector}.\n\tag{2}\n\text{}\n\text{This force opposes the motion and is proportional to the velocity.}\n\n#### Role in FEM Pipeline\n\n1. **Force Contribution: ** The component contributes to the internal forces of the system by adding damping forces through the `addForce` method.\n\n2. **Implicit Damping Matrix:** When set implicitly (using \\\\( \\mathbf{d_{implicit}} = true \\\\)), the component generates a damping matrix \\\\( C \\\\), which is used in implicit time integration schemes to solve for accelerations. The damping matrix \\\\( C \\\\) has diagonal entries:\n\n\begin{equation}\n    (C)_{ii} = - c, \\quad i=1,2,...,N,\n\tag{3}\n\text{}\n\\end{aligned}\n\nwhere \\\\( N \\\\)",
  "abstract": "The `UniformVelocityDampingForceField` applies uniform velocity-dependent damping forces to degrees of freedom in a SOFA simulation, with options for explicit or implicit integration.",
  "sheet": "# UniformVelocityDampingForceField\n\n## Overview\n\nThe `UniformVelocityDampingForceField` is a force field component that applies uniform velocity-dependent damping forces to the degrees of freedom within a SOFA simulation. It inherits from the `core::behavior::ForceField` class and can operate in either explicit or implicit modes, depending on the setting of the `d_implicit` parameter.\n\n## Mathematical Model\n\nThe damping force \\( f_d \\) applied at each degree of freedom (DOF) is given by:\n\n\\[ \n    f_d = - c \\\\.x,\n\\]\n\nwhere:\n\n- \\( c \\): Damping coefficient (controlled by `d_dampingCoefficient`),\n- \\( \\\\.x \\): Velocity vector.\n\nThis force opposes the motion and is proportional to the velocity. When set implicitly (`d_implicit = true`), the component generates a damping matrix \\( C \\) with diagonal entries:\n\n\\[ \n    (C)_{ii} = - c, \\quad i=1,2,...,N,\n\\]\n\nwhere \\( N \\) is the number of degrees of freedom.\n\n## Parameters and Data\n\n- **d_dampingCoefficient**: Controls the strength of the damping effect. Type: `Real`, Default: Not specified.\n- **d_implicit**: Determines whether to generate a damping matrix for implicit integration or operate in explicit mode (only generating forces). Type: `bool`, Default: Not specified.\n\n## Practical Notes\n\nAdjusting the damping coefficient can significantly affect the behavior of simulated objects. Lower values result in less resistance to motion, while higher values increase damping effects. Setting `d_implicit` to true is necessary for implicit integration schemes that require damping matrices."
}