Methods

{
  "name": "TopologyData",
  "namespace": "sofa::core::topology",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/topology/TopologyData.h",
  "doc": "A class for storing topology related data. Automatically manages topology changes.\nThis class is a wrapper of class type::vector that is made to take care transparently of all topology changes that might\nhappen (non exhaustive list: element added, removed, fused, renumbered).",
  "inherits": [],
  "templates": [
    "core::topology::BaseMeshTopology::Point, type::vector<Index>"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "createTopologyHandler",
      "return_type": "void",
      "params": [
        {
          "name": "_topology",
          "type": "sofa::core::topology::BaseMeshTopology *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToPointDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToEdgeDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToTriangleDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToQuadDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToTetrahedronDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToHexahedronDataArray",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "swap",
      "return_type": "void",
      "params": [
        {
          "name": "i1",
          "type": "int"
        },
        {
          "name": "i2",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "remove",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "add",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        },
        {
          "name": "elems",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        },
        {
          "name": "ancestorElems",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "renumber",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "move",
      "return_type": "void",
      "params": [
        {
          "name": "indexList",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addOnMovedPosition",
      "return_type": "void",
      "params": [
        {
          "name": "indexList",
          "type": "const int &"
        },
        {
          "name": "elems",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeOnMovedPosition",
      "return_type": "void",
      "params": [
        {
          "name": "indices",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setDestructionCallback",
      "return_type": "void",
      "params": [
        {
          "name": "func",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setCreationCallback",
      "return_type": "void",
      "params": [
        {
          "name": "func",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addTopologyEventCallBack",
      "return_type": "void",
      "params": [
        {
          "name": "type",
          "type": "core::topology::TopologyChangeType"
        },
        {
          "name": "callback",
          "type": "TopologyChangeCallback"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Point *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Edge *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Triangle *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Quad *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Tetrahedron *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "linkToElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Hexahedron *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Point *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Edge *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Triangle *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Quad *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Tetrahedron *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "unlinkFromElementDataArray",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "sofa::core::topology::BaseMeshTopology::Hexahedron *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TopologyData` class in SOFA's framework is designed for storing topology-related data and automatically managing changes to the topology (such as adding, removing, fusing, or renumbering elements). It acts as a wrapper around a vector-like container (`type::vector<Index>`), handling all necessary adjustments when topological modifications occur. The class provides methods for linking data arrays to different types of geometric elements such as points, edges, triangles, quads, tetrahedra, and hexahedra. Additionally, it allows registration of callbacks for topology changes (additions, removals, movements) and manages these through a `TopologyDataHandler`. This class is particularly useful in maintaining consistent data during simulations involving dynamic topological changes.",
  "maths": "The `TopologyData` class in the SOFA framework is designed to manage topology-related data for various geometric elements within a simulation, ensuring consistency and handling dynamic topological changes such as adding, removing, fusing, or renumbering elements. This class acts as a wrapper around a vector-like container (`type::vector<Index>`) that stores the indices of these geometric elements. The methods provided by `TopologyData` facilitate linking data arrays to different types of geometric elements (points, edges, triangles, quads, tetrahedra, and hexahedra) and managing callbacks for topology changes.\n\n### Governing Equations or Operators:\n\n- **Mass Matrix** (\boldsymbol{M}): The mass matrix is not directly implemented by `TopologyData`. Instead, it is managed in other components like the Mass component of a FEM simulation.\n- **Stiffness Matrix** (\boldsymbol{K}): Similarly, the stiffness matrix is derived from constitutive laws and is handled by elements such as TetrahedronForceField or HexahedronForceField. `TopologyData` does not directly contribute to these matrices but ensures their consistency through topology management.\n- **Internal Force Vector** (\\(\boldsymbol{f}_{int}\\)): The internal force vector, derived from the weak form of the equilibrium equation and constitutive models, is also managed by other components like ForceFields. `TopologyData` does not directly influence this vector but ensures its consistency through topology changes.\n- **Residual Vector** (\\(\boldsymbol{R}\\)): The residual vector in nonlinear FEM simulations is derived from the difference between internal and external forces. While `TopologyData` itself does not contribute to the residual, it ensures that the system's state remains consistent by managing topological changes.\n\n### Constitutive or Kinematic Laws Involved:\n\n- **Strain Measures**: The strain measures are typically computed within the elements (e.g., TetrahedronForceField) based on displacement fields. `TopologyData` does not directly compute strains but ensures that these computations remain consistent with topological changes.\n- **Stress Tensors**: Stress tensors are derived from constitutive laws and are managed by force field components, not by `TopologyData`. However, the consistency of stress calculations is maintained through proper topology management.\n- **Hyperelastic Potentials**: Hyperelastic potentials are used in material models (e.g., St-Venant–Kirchhoff, Neo-Hookean) to derive stress-strain relationships. These are computed within specific force field components rather than `TopologyData` itself.\n\n### Role in the Global FEM Pipeline:\n\n- **Assembly**: During assembly, `TopologyData` ensures that topological changes (such as addition or removal of elements) do not affect the consistency of the global system matrices and vectors. It manages these changes through a `TopologyHandler`, which updates the system accordingly.\n- **Time Integration**: While time integration schemes such as Backward Euler are managed by solver components, `TopologyData` ensures that topological consistency is maintained throughout each time step.\n- **Nonlinear Solve**: The nonlinear solve involves evaluating residuals and Jacobians. Although `TopologyData` does not directly participate in these evaluations, it ensures that the system's topology remains consistent during these computations.\n- **Linear Solve**: Linear solvers operate on matrices derived from element contributions. `TopologyData` indirectly supports this by ensuring topological consistency of elements used to build those matrices.\n- **Constraint Handling and Mapping**: Constraints and mappings are handled in other components, but `TopologyData` ensures that the topology remains consistent for these operations.\n\n### Numerical Methods or Discretization Choices:\n\n- **Vector Management**: The class manages a vector-like container (`type::vector<Index>`) to store indices of geometric elements. It provides methods like `add`, `remove`, and `swap` to manage changes to this vector, ensuring consistency with topological modifications.\n- **Callback Registration**: Methods such as `setDestructionCallback` and `setCreationCallback` allow the registration of custom behavior for element creation or destruction, which can be used in conjunction with other components to maintain system consistency during topology changes.\n\n### Variational / Lagrangian Mechanics Framework:\n\nThe broader framework is grounded in variational mechanics and Lagrangian formalism. While `TopologyData` does not directly contribute to the derivation of governing equations or constitutive laws, it ensures that these principles are consistently applied by maintaining topological consistency across simulations.\n\n### Summary:\n`TopologyData` serves as a critical support component within the SOFA framework, ensuring the consistency and integrity of topology-related data during dynamic changes. It acts as an intermediary between high-level simulation components (such as force fields and solvers) and low-level geometric elements, enabling robust and accurate simulations of complex deformable systems.",
  "abstract": "`TopologyData` manages topology-related data and automatically handles changes such as adding or removing elements to maintain consistency during simulations.",
  "sheet": "# TopologyData\n\n## Overview\nThe `TopologyData` class in SOFA is designed for storing and managing topology-related data. It automatically handles dynamic topological changes, including element addition, removal, fusion, and renumbering, ensuring the simulation remains consistent.\n\n## Parameters and Data\nThere are no significant Data fields exposed by this component as it primarily manages internal state through its methods.\n\n## Dependencies and Connections\n`TopologyData` typically requires a `BaseMeshTopology` to manage topology changes. It interacts with other components that rely on topological consistency, such as force fields and solvers.\n\n## Practical Notes\nEnsure proper registration of callbacks for topology changes to maintain simulation integrity during dynamic modifications."
}