Data Fields

Links

Methods

{
  "name": "TrianglePressureForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/TrianglePressureForceField.h",
  "doc": "Pressure applied on a triangular geometry.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_pressure",
      "type": "Deriv",
      "xmlname": "pressure",
      "help": "Pressure force per unit area"
    },
    {
      "name": "d_cauchyStress",
      "type": "MatSym3",
      "xmlname": "cauchyStress",
      "help": "Cauchy Stress applied on the normal of each triangle"
    },
    {
      "name": "d_showForces",
      "type": "bool",
      "xmlname": "showForces",
      "help": "draw triangles which have a given pressure"
    },
    {
      "name": "d_useConstantForce",
      "type": "bool",
      "xmlname": "useConstantForce",
      "help": "applied force is computed as the pressure vector times the area at rest"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "init",
      "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": "d_f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "d_x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "d_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": "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": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "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 &"
        }
      ],
      "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": "setPressure",
      "return_type": "void",
      "params": [
        {
          "name": "_pressure",
          "type": "Deriv"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateTriangleInformation",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initTriangleInformation",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TrianglePressureForceField` is a force field component in SOFA that applies pressure on triangular geometries. It inherits from the `core::behavior::ForceField` class and operates within the mechanical load module (`Sofa.Component.MechanicalLoad`). This component calculates forces based on the specified pressure or Cauchy stress applied to specific triangles, which are defined by their indices in the topology container.\n\n### Interactions with Other Components:\n- **Topology Link**: It requires a link to a `BaseMeshTopology` object for access to triangle information and vertex positions. This ensures that the component can compute forces on the correct geometric elements.\n- **Mechanical State**: The force field interacts with the mechanical state (positions, velocities) of the system through callbacks like `addForce`, which modifies the forces acting on the nodes based on the pressure applied.\n\n### Data Fields:\n- **Pressure (`pressure`)**: A vector specifying the pressure force per unit area to be applied.\n- **Cauchy Stress (`cauchyStress`)**: Symmetric 3x3 matrix representing the Cauchy stress tensor, which influences the direction and magnitude of forces on triangular elements.\n- **Triangle List (`triangleList`)**: A list of triangle indices where pressure is to be applied. This allows selective application of pressure to specific parts of a mesh.\n- **Show Forces (`showForces`)**: Boolean flag for visualizing triangles with the applied pressure, useful for debugging and visualization purposes.\n- **Constant Force Usage (`useConstantForce`)**: Boolean that determines whether the force is computed as a constant value based on the rest area or dynamically.\n\n### Practical Usage:\nThe `TrianglePressureForceField` is typically used in simulations involving triangular meshes where localized pressure needs to be applied, such as in surgical simulation scenarios. Users configure the pressure and triangle indices via XML parameters or through API calls, ensuring that the correct mechanical load is applied during a simulation.",
  "maths": "The `TrianglePressureForceField` component in the SOFA framework applies pressure forces on triangular geometries. This force field contributes to the internal force vector $\\mathbf{f}_{int}$, which is added to the system's equations of motion during each time step.\n\n### Governing Equations and Operators:\n- **Internal Force ($\\mathbf{f}_{int}$)**: The component calculates the pressure-induced forces on each node. These forces are computed based on either a constant force or a dynamic Cauchy stress tensor, as specified by the user.\n\n### Constitutive Laws Involved:\n- **Pressure Force**: The applied pressure $p$ is a vector per unit area. If `useConstantForce` is set to true, the internal force for each triangle is computed as:\n  \n  \\[ \\mathbf{f}_{int} = p \\cdot A \\]\n\n  where $A$ is the rest area of the triangle.\n- **Cauchy Stress**: If `useConstantForce` is set to false, the force is derived from a Cauchy stress tensor $\\boldsymbol{\\sigma}$:\n  \n  \\[ \\mathbf{f}_{int} = \\boldsymbol{\\sigma} \\cdot A \\]\n\n  where $A$ is computed as the area vector of the triangle in its current configuration.\n\n### Role in Global FEM Pipeline:\n- **Assembly**: The internal forces are assembled into the global force vector via the `addForce` method, which iterates over specified triangles and distributes the pressure-induced forces to the nodes that form these triangles.\n- **Time Integration**: During each time step of the implicit integration scheme, the component contributes to the residual equation:\n  \n  \\[ R(\\mathbf{x}_{n+1}) = M \\frac{\\mathbf{x}_{n+1} - \\mathbf{x}_n}{\\Delta t} + f_{int}(\\mathbf{x}_{n+1}) - f_{ext} \\]\n\n### Numerical Methods and Discretization:\n- The force distribution is performed at each node of the specified triangles, with contributions divided by three to account for the triangular geometry.\n\n### Variational Mechanics Framework:\n- The component implements a variational formulation where pressure forces are integrated over the area of triangular elements. This ensures consistency with the weak form and variational principles underlying FEM simulations.\n\nThe `TrianglePressureForceField` enables users to apply localized pressures in a physically consistent manner, which is particularly useful for simulating contact forces or internal tissue compression scenarios.",
  "abstract": "The `TrianglePressureForceField` applies pressure forces on triangular geometries within a SOFA simulation, contributing to internal force calculations based on specified pressures or Cauchy stress tensors.",
  "sheet": "# TrianglePressureForceField\n\n## Overview\nThe `TrianglePressureForceField` is a component that applies pressure forces on triangular geometries. It inherits from the `core::behavior::ForceField` class and operates within the mechanical load module (`Sofa.Component.MechanicalLoad`). This force field calculates internal forces based on specified pressures or Cauchy stress tensors applied to specific triangles, which are defined by their indices in a linked topology container.\n\n## Mathematical Model\nThe `TrianglePressureForceField` contributes to the internal force vector $\\mathbf{f}_{int}$, which is added to the system's equations of motion during each time step. The internal forces are computed based on either a constant pressure or a dynamic Cauchy stress tensor:\n- **Constant Pressure**: If `useConstantForce` is set to true,\n  \\[ \\mathbf{f}_{int} = p \\cdot A, \\]\n  where $p$ is the applied pressure and $A$ is the rest area of the triangle.\n- **Cauchy Stress**: If `useConstantForce` is set to false,\n  \\[ \\mathbf{f}_{int} = \\boldsymbol{\\sigma} \\cdot A, \\]\n  where $\\boldsymbol{\\sigma}$ is the Cauchy stress tensor and $A$ is computed as the area vector of the triangle in its current configuration.\n\n## Parameters and Data\n- **Pressure (`pressure`)**: Vector specifying the pressure force per unit area to be applied. Type: `Deriv`, Default: Not specified.\n- **Cauchy Stress (`cauchyStress`)**: Symmetric 3x3 matrix representing the Cauchy stress tensor, which influences the direction and magnitude of forces on triangular elements. Type: `MatSym3`, Default: Not specified.\n- **Show Forces (`showForces`)**: Boolean flag for visualizing triangles with applied pressure. Useful for debugging and visualization purposes. Type: `bool`, Default: Not specified.\n- **Constant Force Usage (`useConstantForce`)**: Boolean that determines whether the force is computed as a constant value based on the rest area or dynamically. Type: `bool`, Default: Not specified.\n\n## Dependencies and Connections\nThe component requires a link to a `BaseMeshTopology` object for access to triangle information and vertex positions, ensuring it can compute forces on the correct geometric elements."
}