Data Fields

Links

Methods

{
  "name": "QuadularBendingSprings",
  "namespace": "sofa::component::solidmechanics::spring",
  "module": "Sofa.Component.SolidMechanics.Spring",
  "include": "sofa/component/solidmechanics/spring/QuadularBendingSprings.h",
  "doc": "Springs added to a quad mesh to prevent bending.\n\nBending springs added between vertices of quads sharing a common edge.\nThe springs connect the vertices not belonging to the common edge. It compresses when the surface bends along the common edge.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "f_ks",
      "type": "SReal",
      "xmlname": "stiffness",
      "help": "uniform stiffness for the all springs"
    },
    {
      "name": "f_kd",
      "type": "SReal",
      "xmlname": "damping",
      "help": "uniform damping for the all springs"
    }
  ],
  "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": "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 core::MechanicalParams *"
        },
        {
          "name": "",
          "type": "const DataVecCoord &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getKs",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getKd",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setKs",
      "return_type": "void",
      "params": [
        {
          "name": "ks",
          "type": "const SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setKd",
      "return_type": "void",
      "params": [
        {
          "name": "kd",
          "type": "const SReal"
        }
      ],
      "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": "getEdgeInfo",
      "return_type": "int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyEdgeCreation",
      "return_type": "void",
      "params": [
        {
          "name": "edgeIndex",
          "type": "int"
        },
        {
          "name": "ei",
          "type": "EdgeInformation &"
        },
        {
          "name": "",
          "type": "const core::topology::BaseMeshTopology::Edge &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyQuadCreation",
      "return_type": "void",
      "params": [
        {
          "name": "quadAdded",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        },
        {
          "name": "",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyQuadDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "quadRemoved",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyPointDestruction",
      "return_type": "void",
      "params": [
        {
          "name": "pointIndices",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyPointRenumbering",
      "return_type": "void",
      "params": [
        {
          "name": "pointToRenumber",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeForce",
      "return_type": "ForceOutput",
      "params": [
        {
          "name": "v",
          "type": "const VecDeriv &"
        },
        {
          "name": "einfo",
          "type": "const EdgeInformation &"
        },
        {
          "name": "spring",
          "type": "const typename EdgeInformation::Spring &"
        },
        {
          "name": "direction",
          "type": "Coord"
        },
        {
          "name": "distance",
          "type": "Real"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeLocalJacobian",
      "return_type": "Mat",
      "params": [
        {
          "name": "einfo",
          "type": "EdgeInformation &"
        },
        {
          "name": "direction",
          "type": "const Coord &"
        },
        {
          "name": "force",
          "type": "const ForceOutput &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeSpringForce",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecDeriv &"
        },
        {
          "name": "x",
          "type": "const VecCoord &"
        },
        {
          "name": "v",
          "type": "const VecDeriv &"
        },
        {
          "name": "einfo",
          "type": "EdgeInformation &"
        },
        {
          "name": "spring",
          "type": "typename EdgeInformation::Spring &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `QuadularBendingSprings` is a SOFA component that adds springs to a quad mesh to prevent bending along common edges between quads. It inherits from the `ForceField` class and operates within the `sofa::component::solidmechanics::spring` namespace. The primary role of this component is to ensure that the surface remains relatively flat by applying forces when the surface bends. Springs are created between vertices not belonging to a common edge, which compresses as the surface bends along the edge.\n\n### Interactions with Other Components\n- **Topology Interaction**: It requires a link (`l_topology`) to a `BaseMeshTopology` component that provides information about quads and edges within the mesh. This topology container is essential for defining where springs should be added and updated during simulation.\n- **Mechanical State**: The mechanical state, such as positions and velocities, are provided by Data fields such as `d_x`, `d_v`, and `d_f` which represent positions, velocities, and forces respectively. These interactions occur through method calls like `addForce()` and `buildStiffnessMatrix()`.\n\n### Practical Usage Guidance\n- **Stiffness (`f_ks`) and Damping (`f_kd`)**: Uniform stiffness and damping can be set for all springs via the `stiffness` and `damping` data fields. Adjusting these values allows tuning of how strongly the mesh resists bending.\n- **Initialization**: The component requires proper initialization to link with a topology container, which ensures correct behavior by providing quad and edge information.\n\n### Data Fields\n- `f_ks`: Stiffness parameter for all springs (uniform).\n- `f_kd`: Damping factor for all springs (uniform).",
  "maths": "The `QuadularBendingSprings` component in the SOFA framework is designed to prevent bending along common edges between quads in a mesh. This component adds springs between vertices that do not belong to these common edges, thereby compressing when the surface bends along the edge. The primary role of this component is to maintain a relatively flat surface by applying forces when bending occurs.\n\n### Governing Equations and Operators\nThe `QuadularBendingSprings` component contributes to several components in the overall FEM pipeline:\n- **Internal Force**: The springs provide internal force contributions, which are added to the global force vector $f_{int}$.\n- **Stiffness Matrix**: The stiffness matrix $K$ is updated with the contribution of these bending springs.\n\nThe component implements the following mathematical operations:\n1. **Spring Stiffness and Damping**\n   - Each spring has a uniform stiffness parameter $k_s$ (f_ks) and damping factor $k_d$ (f_kd).\n2. **Force Calculation**: The force applied by each spring is given by the equation\n   \n   \\[ f = k_s (\text{current distance} - \text{rest length}) + k_d \text{(relative velocity)} \\]\n\n3. **Potential Energy**: The potential energy stored in a spring is calculated as\n   \n   \\[ V = \\frac{k_s}{2} (\text{current distance} - \text{rest length})^2 \\]\n\n4. **Local Jacobian**: For each spring, the local Jacobian $J$ is computed and added to the global stiffness matrix.\n\n### Constitutive Laws and Kinematic Models\n- The component primarily uses linear springs for bending resistance. Each spring connects vertices not belonging to a common edge between quads in the mesh.\n- When the surface bends along an edge, the distance between these non-edge vertices changes, and the spring force resists this change by compressing or stretching.\n\n### Numerical Methods and Discretization Choices\n- The component discretizes the bending resistance using linear springs. Each spring is defined between specific pairs of vertices based on the quad topology.\n- **Initialization**: During initialization (`init` method), the component sets up the necessary data structures to store edge information, stiffness matrices, and damping factors.\n- **Force Calculation**: In the `addForce` method, forces are computed for each spring and added to the global force vector $f_{int}$. The relative velocity and current distance between vertices are used to compute these forces.\n- **Stiffness Matrix Construction**: The `buildStiffnessMatrix` method updates the stiffness matrix by adding contributions from each spring's local Jacobian.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: The component contributes to the assembly of internal forces and the stiffness matrix during simulation steps. This is achieved through methods like `addForce`, `buildStiffnessMatrix`, and `buildDampingMatrix`.\n- **Time Integration**: During each time step, the component calculates the forces exerted by the springs using current positions and velocities, which are then integrated into the overall motion equations.\n- **Nonlinear Resolution**: The stiffness matrix contributions from these springs are included in the nonlinear system of equations solved at each iteration.\n\n### Constraint Handling and Mapping\n- The `QuadularBendingSprings` component interacts with the mesh topology to define where springs should be added or updated. This involves handling changes in quad structures due to topological events such as quad addition, deletion, point removal, and renumbering.\n\nOverall, the `QuadularBendingSprings` component provides a method for maintaining surface flatness through the use of linear springs between specific vertices in a quad mesh topology.",
  "abstract": "The `QuadularBendingSprings` component adds springs between vertices not belonging to common edges in quad meshes to prevent bending by applying compressive forces when the surface bends along these edges.",
  "sheet": "# QuadularBendingSprings\n\n## Overview\nThe `QuadularBendingSprings` component is a SOFA ForceField that prevents bending in quad meshes. It adds springs between vertices not belonging to common edges, which compress when the surface bends along these edges.\n\n## Mathematical Model\nEach spring has a uniform stiffness parameter $k_s$ (f_ks) and damping factor $k_d$ (f_kd). The force applied by each spring is given by:\n\\[ f = k_s (\\text{current distance} - \\text{rest length}) + k_d (\\text{relative velocity}) \\]\nThe potential energy stored in a spring is calculated as:\n\\[ V = \\frac{k_s}{2} (\\text{current distance} - \\text{rest length})^2 \\]\n\n## Parameters and Data\n- `f_ks`: Stiffness parameter for all springs (uniform).\n- `f_kd`: Damping factor for all springs (uniform).\n\n## Dependencies and Connections\nThe component requires a link (`l_topology`) to a `BaseMeshTopology` component that provides information about quads and edges within the mesh. This topology container is essential for defining where springs should be added and updated during simulation."
}