Methods

{
  "name": "PenalityContactForceField",
  "namespace": "sofa::component::collision::response::contact",
  "module": "Sofa.Component.Collision.Response.Contact",
  "include": "sofa/component/collision/response/contact/PenalityContactForceField.h",
  "doc": "Contact using repulsive springs.\n\nDistance-based, frictionless penalty force. The force is applied to vertices attached to collision elements.",
  "inherits": [
    "PairInteractionForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "clear",
      "return_type": "void",
      "params": [
        {
          "name": "reserve",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addContact",
      "return_type": "void",
      "params": [
        {
          "name": "m1",
          "type": "int"
        },
        {
          "name": "m2",
          "type": "int"
        },
        {
          "name": "index1",
          "type": "int"
        },
        {
          "name": "index2",
          "type": "int"
        },
        {
          "name": "norm",
          "type": "const Deriv &"
        },
        {
          "name": "dist",
          "type": "Real"
        },
        {
          "name": "ks",
          "type": "Real"
        },
        {
          "name": "mu_s",
          "type": "Real"
        },
        {
          "name": "mu_v",
          "type": "Real"
        },
        {
          "name": "oldIndex",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "data_f1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_f2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_x2",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_v1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_v2",
          "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 sofa::core::MechanicalParams *"
        },
        {
          "name": "data_df1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_df2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_dx1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_dx2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "matrix",
          "type": "const sofa::core::behavior::MultiMatrixAccessor *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "matrix",
          "type": "core::behavior::StiffnessMatrix *"
        }
      ],
      "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 sofa::core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getContact",
      "return_type": "const int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "grabPoint",
      "return_type": "void",
      "params": [
        {
          "name": "tool",
          "type": "const core::behavior::MechanicalState<defaulttype::Vec3Types> *"
        },
        {
          "name": "index",
          "type": "const int &"
        },
        {
          "name": "result",
          "type": "int &"
        },
        {
          "name": "triangle",
          "type": "int &"
        },
        {
          "name": "index_point",
          "type": "int &"
        }
      ],
      "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"
    }
  ],
  "description": "The PenalityContactForceField is designed to model contact forces between two mechanical objects in the Sofa framework, which is used for real-time simulation and surgery training. This component applies penalty forces to prevent inter-penetration of the objects by adding a repulsive force when the distance between two points on different objects becomes less than zero (i.e., they overlap). The force's magnitude depends on the penetration depth, stiffness coefficient, and damping coefficient.",
  "parameters": [
    {
      "name": "stiffness",
      "type": "real",
      "description": "Defines how strongly the system resists inter-penetration. Higher values result in a stronger repulsive force when objects overlap."
    },
    {
      "name": "damping",
      "type": "real",
      "description": "Controls the damping effect applied to the contact forces, reducing the oscillations that can occur due to the repulsive force."
    },
    {
      "name": "frictionCoeff",
      "type": "real",
      "description": "Determines the friction between contacting objects. This parameter affects how forces are transmitted tangentially at the point of contact."
    }
  ],
  "methods_and_behavior": [
    {
      "name": "draw",
      "description": "Renders the contact points and normals between the two mechanical models, providing visual feedback on where and how the contacts occur during the simulation.",
      "parameters": []
    },
    {
      "name": "grabPoint",
      "description": "Allows the component to interact with a tool (another mechanical model) by identifying points of contact and associating them with specific triangles or vertices for precise control in simulations requiring user interaction."
    }
  ],
  "inputs_and_connections": [
    {
      "name": "mstate1",
      "type": "MechanicalState",
      "description": "The first mechanical state object representing one of the interacting models. This is typically a deformable object like a tetrahedral mesh or a triangular surface."
    },
    {
      "name": "mstate2",
      "type": "MechanicalState",
      "description": "The second mechanical state object representing the other interacting model, often a rigid object that the deformable model contacts with during simulation."
    }
  ],
  "maths": "<maths_md_description>\n\nThe PenalityContactForceField in the SOFA framework models contact forces between two mechanical objects using penalty-based repulsive forces. The governing equations and concepts are summarized as follows:\n\n### Governing Equations\n\n1. **Repulsive Force Calculation**\n   - For each pair of vertices $(m_1, m_2)$ on different collision elements with normal vector $\boldsymbol{n}$,\n     the repulsive force is calculated if their distance $u$ (from object 1 to object 2) becomes less than a predefined distance threshold $d$. The penetration depth $p$ is defined as:\n   \\[\n   p = d - \boldsymbol{u} \bullet \boldsymbol{n}\n   \\]\n\n2. **Repulsive Force**\n   - If the penetration depth $p > 0$, a repulsive force $\boldsymbol{f}$ is applied to vertex $m_1$ and an equal and opposite force is applied to vertex $m_2$. The magnitude of this force depends on the stiffness coefficient $k_s$:\n   \\[\n   \boldsymbol{f} = - k_s p \boldsymbol{n}\n   \\]\n\n### Constitutive Laws and Kinematic Models\n\n- **Penalty-Based Contact Force**: This approach uses a penalty method to enforce non-penetration constraints. The force is modeled as an elastic spring with stiffness $k_s$.\n  - No damping forces are explicitly included in the repulsive force calculation, but they can be indirectly incorporated through other components or parameters if needed.\n\n### Role in the Global FEM Pipeline\n\n1. **Contact Handling**: This component handles contact detection and response by applying penalty-based repulsive forces to prevent inter-penetration between objects.\n2. **Force Contribution**: The repulsive force calculated is added to the internal forces ($f_{int}$) of each object during assembly, contributing to the nonlinear residual $R$ in the overall system:\n   \\[\n   R = M \frac{\boldsymbol{x}_{n+1} - \boldsymbol{x}_n}{\triangle t} + f_{int}(x_{n+1}) - \triangle t f_{ext}\n   \\]\n3. **Nonlinear Solve**: The nonlinear residual is solved using the Newton-Raphson iteration method.\n4. **Linear Solve**: During each iteration, a linear system is solved to update the state of the mechanical objects:\n   \\[\n   J(x_k) \boldsymbol{\triangle x}_k = - R(x_k)\n   \\]\n\n### Numerical Methods and Discretization Choices\n\n- The penalty method enforces contact constraints by adding a repulsive force, which can be interpreted as a stiff spring. This approach is computationally efficient but may introduce numerical stiffness if the penalty factor $k_s$ is too large.\n- No damping forces are explicitly included in the calculation of the repulsive force, though they can be added through other components or parameters if needed for stability.\n\n### Variational / Lagrangian Mechanics Framework Fit\n\nThis component fits into the broader variational and Lagrangian mechanics framework by enforcing contact constraints using penalty-based forces. The repulsive forces are derived from a potential energy function that penalizes inter-penetration, ensuring mechanical invariants such as non-interpenetration are preserved.\n\nThe mathematical formulation ensures consistency with the overall FEM pipeline, allowing for real-time or high-fidelity simulation of nonlinear deformable bodies while remaining mathematically rigorous and extensible.</maths_md_description>",
  "abstract": "PenalityContactForceField models contact forces using penalty-based repulsive springs to prevent inter-penetration of mechanical objects in SOFA simulations.",
  "sheet": "# PenalityContactForceField\n\n## Overview\n\nThe `PenalityContactForceField` is a component that handles contact interactions between pairs of mechanical objects by applying penalty-based repulsive forces. It inherits from the `PairInteractionForceField`, indicating its role in managing pairwise interactions within SOFA simulations.\n\n## Mathematical Model\n\n### Governing Equations\n\n1. **Repulsive Force Calculation**\n   - For each pair of vertices $(m_1, m_2)$ on different collision elements with normal vector $\\boldsymbol{n}$, the repulsive force is calculated if their distance $u$ (from object 1 to object 2) becomes less than a predefined distance threshold $d$. The penetration depth $p$ is defined as:\n   \\[\n   p = d - \\boldsymbol{u} \\cdot \\boldsymbol{n}\n   \\]\n\n2. **Repulsive Force**\n   - If the penetration depth $p > 0$, a repulsive force $\\boldsymbol{f}$ is applied to vertex $m_1$ and an equal and opposite force is applied to vertex $m_2$. The magnitude of this force depends on the stiffness coefficient $k_s$:\n   \\[\n   \\boldsymbol{f} = - k_s p \\boldsymbol{n}\n   \\]\n\n### Constitutive Laws and Kinematic Models\n\n- **Penalty-Based Contact Force**: This approach uses a penalty method to enforce non-penetration constraints. The force is modeled as an elastic spring with stiffness $k_s$.\n  - No damping forces are explicitly included in the repulsive force calculation, but they can be indirectly incorporated through other components or parameters if needed."
}