Data Fields

Links

Methods

{
  "name": "QuadPressureForceField",
  "namespace": "sofa::component::mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/QuadPressureForceField.h",
  "doc": "Pressure applied on a quadrangular geometry.\n\nQuadPressureForceField Class\nImplements a pressure force applied on a quad surface.\nThe force applied to each vertex of a quad is equal to the quad surface*Pressure/4.\nThe force is constant during animation.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_pressure",
      "type": "Deriv",
      "xmlname": "pressure",
      "help": "Pressure force per unit area"
    },
    {
      "name": "d_normal",
      "type": "Deriv",
      "xmlname": "normal",
      "help": "Normal direction for the plane selection of quads"
    },
    {
      "name": "d_dmin",
      "type": "Real",
      "xmlname": "dmin",
      "help": "Minimum distance from the origin along the normal direction"
    },
    {
      "name": "d_dmax",
      "type": "Real",
      "xmlname": "dmax",
      "help": "Maximum distance from the origin along the normal direction"
    },
    {
      "name": "d_showForces",
      "type": "bool",
      "xmlname": "showForces",
      "help": "draw quads which have a given pressure"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "init",
      "description": "Initializes the QuadPressureForceField by selecting quads along a plane or from an index list and setting up internal data structures for storing quad pressures."
    },
    {
      "name": "addForce",
      "parameters": [
        "mparams",
        "d_f",
        "d_x",
        "d_v"
      ],
      "description": "Adds pressure forces to each vertex of the quads in the simulation. The force applied is equal to (quad area * d_pressure) / 4."
    },
    {
      "name": "addDForce",
      "parameters": [
        "mparams",
        "d_df",
        "d_dx"
      ],
      "description": "Constant pressure has no variation with respect to position, so this method does nothing as the derivative of force is zero."
    },
    {
      "name": "buildStiffnessMatrix",
      "parameters": [
        "matrix"
      ],
      "description": "The stiffness matrix is set to null because the force does not depend on the position."
    },
    {
      "name": "buildDampingMatrix",
      "parameters": [
        "matrix"
      ],
      "description": "No damping is applied in this ForceField, so this method sets the damping matrix to zero."
    },
    {
      "name": "getPotentialEnergy",
      "parameters": [
        "mparams",
        "x"
      ],
      "description": "Returns 0 as the potential energy is not implemented yet for this force field."
    },
    {
      "name": "draw",
      "parameters": [
        "vparams"
      ],
      "description": "Visualizes quads which have pressure forces applied to them, if the d_showForces flag is set to true."
    }
  ],
  "description": "The QuadPressureForceField class is a force field component in the SOFA (Simulation Open-Framework Architecture) framework that applies pressure forces on quad surfaces in a simulation.",
  "parameters": [
    {
      "name": "d_pressure",
      "type": "Deriv",
      "description": "Pressure force per unit area applied to each quad surface."
    },
    {
      "name": "d_quadList",
      "type": "sofa::type::vector<Index>",
      "description": "Indices of quads where pressure is applied, separated by commas."
    },
    {
      "name": "d_normal",
      "type": "Deriv",
      "description": "The normal vector defining the direction and plane for applying the edge pressure forces."
    },
    {
      "name": "d_dmin",
      "type": "Real",
      "description": "Minimum distance from origin along the d_normal direction to apply pressure."
    },
    {
      "name": "d_dmax",
      "type": "Real",
      "description": "Maximum distance from origin along the d_normal direction to apply pressure."
    },
    {
      "name": "d_showForces",
      "type": "bool",
      "description": "A flag that, when set to true, draws quads which have a given pressure force applied to them during visualization."
    }
  ],
  "protected_methods": [
    {
      "name": "selectQuadsAlongPlane",
      "description": "Selects quads that intersect with a plane defined by normal and distance parameters (d_dmin and d_dmax)."
    },
    {
      "name": "selectQuadsFromString",
      "description": "Parses the quad indices from a string to select specific quads for applying pressure."
    },
    {
      "name": "updateQuadInformation",
      "description": "Updates internal data structures that store information about applied pressures on selected quads."
    },
    {
      "name": "initQuadInformation",
      "description": "Initializes the storage of quad area and force information for each selected quad."
    },
    {
      "name": "isPointInPlane",
      "parameters": [
        "p"
      ],
      "description": "Determines if a point lies within a specified range along the normal vector (between d_dmin and d_dmax)."
    }
  ],
  "note": "This component is primarily used in simulations involving quad-based surfaces such as cloth or thin shell structures where pressure forces need to be applied consistently across defined regions of the surface.",
  "maths": "### Mathematical and Physical Description of QuadPressureForceField\n\n#### Governing Equations and Operators:\n- **Pressure Force**: The force applied on each vertex of a quad is given by the product of the surface area of the quad, \\(A\\), and the pressure per unit area, \\(p\\). This total force is then distributed equally among the four vertices of the quad.\n  \n  For a given quad with indices \\((i_1, i_2, i_3, i_4)\\), the force applied at each vertex is:\n  \n  \\[ f_{quad} = p \\cdot A / 4 \\]\n  \n  where \\(A\\) is computed as:\n  \n  \\[ A = \\text{area}(P_{i_1}, P_{i_2}, P_{i_3}, P_{i_4}) \\]\n\n- **Force Contribution**: The force contribution of the pressure to the total internal forces in the system is added through the `addForce` method. This updates the global force vector, \\(f\\), by adding the computed per-vertex forces.\n  \n  In matrix form, if we denote the global force vector as \\(\\mathbf{F}\\) and the quad-specific contributions as \\(\bm{f}_{quad}\\):\n  \n  \\[ \\mathbf{F} = \\mathbf{F} + \bm{f}_{quad} \\]\n\n#### Constitutive or Kinematic Laws:\n- **Pressure Force Per Unit Area**: The pressure force per unit area, \\(p\\), is a prescribed parameter. This does not involve any constitutive law but rather represents an external loading condition.\n  \n  - `d_pressure`: Stores the value of \\(p\\).\n\n#### Role in the Global FEM Pipeline:\n- **Force Application**: The component contributes to the assembly phase by adding its force contributions to the internal forces vector, \\(\bm{f}_{int}\\). It operates during the `addForce` method invocation, which is part of the simulation loop.\n  \n  - **Assembly**: The contribution from each quad's vertices is added to the global internal force vector. This step occurs during the assembly phase of the FEM pipeline.\n\n#### Numerical Methods and Discretization Choices:\n- **Quad Area Computation**: The area of a quadrilateral \\(A\\) is computed using standard geometric methods (e.g., via the cross-product or determinant-based area formula).\n  \n  - `initQuadInformation`: Computes the quad areas during initialization.\n\n- **Force Distribution**: Each vertex receives an equal portion of the total pressure force, ensuring a uniform distribution across the vertices of each quad.\n  \n  - `addForce`: Adds the computed per-vertex forces to the global internal forces vector.\n\n#### Variational / Lagrangian Mechanics Framework:\n- **Weak Form**: This component directly contributes to the weak form by applying external pressure forces. These forces are added as part of the internal force term \\(\bm{f}_{int}\\) in the variational formulation:\n  \n  \\[ \begin{align*}\n  &\\int_\n{\text{domain}}\rho \n\frac{\n\text{d}^2u\n}{\n\text{dt}^2} w dV +\n  \\\n&\\quad+\\int_{\text{domain}}\n\bm{\tau}\n: \\varepsilon(w) dV =\n  \\\n&\\quad=\\int_{\text{domain}} p A/4 w dV\n  +\\int_{\n\text{boundary}\n} \n\bar{t}\nw dS\n  \\end{align*}\\]\n  where \\(pA/4\\) is the contribution from each vertex of a quad.\n",
  "abstract": "QuadPressureForceField applies a constant pressure force on quad surfaces in SOFA simulations, distributing the total force equally among the four vertices of each quad.",
  "sheet": "# QuadPressureForceField\n\n**Overview:**\nQuadPressureForceField is a component that applies a constant pressure force to quadrilateral surfaces within a simulation. It inherits from `ForceField` and requires linking to a topology container for geometric information.\n\n**Mathematical Model:*\nThe pressure force applied on each vertex of a quad surface is given by the product of the quad's area, \\(A\\), and the prescribed pressure per unit area, \\(p\\). The total force is then distributed equally among the four vertices:\n\n\begin{align*}\n  f_{quad} &= p \times A / 4 \\\\\n  A &= \\text{area}(P_{i_1}, P_{i_2}, P_{i_3}, P_{i_4})\n\tag{1}\n\\end{align*}\n\nThe force contribution is added to the global internal forces vector, \\(\\mathbf{F}\\), during the `addForce` method invocation.\n\n**Parameters and Data:*\nThe significant data fields are:\n- **pressure**: Pressure force per unit area (type: Deriv).\n- **normal**: Normal direction for plane selection of quads (type: Deriv).\n- **dmin**: Minimum distance from the origin along the normal direction (type: Real).\n- **dmax**: Maximum distance from the origin along the normal direction (type: Real).\n- **showForces**: Draw quads which have a given pressure (type: bool).\n\n**Dependencies and Connections:**\nThe component requires linking to a `BaseMeshTopology` for geometric information.\n\n**Practical Notes:**\nEnsure that the pressure value is set appropriately, as an incorrect value can lead to unrealistic force distributions. The normal direction should be correctly specified to ensure accurate plane selection."
}