Data Fields

Links

Methods

{
  "name": "TopologyChecker",
  "namespace": "sofa::component::topology::utility",
  "module": "Sofa.Component.Topology.Utility",
  "include": "sofa/component/topology/utility/TopologyChecker.h",
  "doc": "Read topological Changes and process them.\n\nThe class TopologyChecker represents a SOFA component which can be added in a scene graph to test a given Topology.\nThe topology component to be tested need to be linked using @sa l_topology.\nIf the Data @sa d_eachStep is set to true, the topology will be tested at each step using the generic method @sa checkTopology\nOtherwise each method can be called manually:\n@CheckTopology will call the appropriate Check{TopologyType}Topology then call the lower level of CheckTopology.\n  - i.e for a Tetrahedron Topology, CheckTopology with call @sa checkTetrahedronTopology then @sa checkTriangleTopology and finally @sa checkEdgeTopology\n  - At each level the topology is checked through the main element container and also the cross topology containers\n  - Each method return a bool and will display msg_error if problems are detected.",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_eachStep",
      "type": "bool",
      "xmlname": "eachStep",
      "help": "Check topology at each step"
    }
  ],
  "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": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "sofa::core::objectmodel::Event *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkEdgeTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkEdgeContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkEdgeToVertexCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTriangleTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTriangleContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTriangleToEdgeCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTriangleToVertexCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkQuadTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkQuadContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkQuadToEdgeCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkQuadToVertexCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTetrahedronTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTetrahedronContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTetrahedronToTriangleCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTetrahedronToEdgeCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkTetrahedronToVertexCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkHexahedronTopology",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkHexahedronContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkHexahedronToQuadCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkHexahedronToEdgeCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "checkHexahedronToVertexCrossContainer",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `TopologyChecker` is a SOFA component designed to validate the integrity and consistency of a mesh's topology within a simulation scene graph. It can be linked to any `BaseMeshTopology` container, allowing it to test topologies for various elements such as edges, triangles, quads, tetrahedrons, and hexahedra. The checker ensures that all topological relationships are correctly defined and maintained by verifying containers and cross-referencing them with adjacent elements (vertices, edges, etc.).\n\nThe component provides several methods to check different types of topology, including `checkEdgeTopology`, `checkTriangleTopology`, `checkQuadTopology`, `checkTetrahedronTopology`, and `checkHexahedronTopology`. Each method recursively checks the lower levels of topology as well. For example, `checkTetrahedronTopology` will also check its underlying triangle, edge, and vertex topologies.\n\nThe checker is initialized by linking to a topology container through the `l_topology` link. The boolean data field `d_eachStep`, if set to true, enables continuous topology checks at every simulation step, otherwise manual invocation of individual methods is required.\n\nIt integrates into SOFA's event-driven architecture and can respond to specific events such as keypresses or animation end events by triggering a topology check.\n\nOverall, the `TopologyChecker` is a useful tool for debugging topological issues in simulations, ensuring that no invalid elements are present and that all connections are correctly defined.",
  "maths": "The `TopologyChecker` is not directly involved in the mathematical or physical formulations typically associated with finite element analysis, such as mass matrices, stiffness matrices, internal forces, and residuals. Instead, it serves a crucial role in ensuring that the topological data used for meshing is consistent and valid, thereby supporting the proper application of FEM principles to deformable systems within SOFA's simulation framework.\n\n### Topology Validation\nThe `TopologyChecker` verifies the integrity of the topology by checking various aspects of the elements it contains. The core methods include:\n- **Edge Checking (`checkEdgeTopology`, `checkEdgeContainer`, `checkEdgeToVertexCrossContainer`)**: Validates that edges do not have repeated vertices and are correctly referenced in cross-containers.\n  \n    - **Consistency Check**: Ensures each edge connects two distinct vertices (no self-loops).\n        \\[ \\forall i, j \\quad (i < j) \\implies \\text{edge}[i] \neq \\text{edge}[j] \\]\n\n    - **Cross-Container Consistency**: Ensures all edges are referenced correctly in cross-containers such as `m_edgesAroundVertex`.\n        \\[ \\forall i, j \\quad (\\text{EdgesAV}[i][j] \neq \\text{sofa::InvalidID}) \\implies (\\exists k, l: \\text{edge}[k][l] = i) \\]\n\n- **Triangle Checking (`checkTriangleTopology`, `checkTriangleContainer`, `checkTriangleToEdgeCrossContainer`, `checkTriangleToVertexCrossContainer`)**: Ensures that triangles do not have repeated vertices and are correctly referenced in cross-containers.\n  \n    - **Consistency Check**: Ensures each triangle has three distinct vertices (no self-loops).\n        \\[ \\forall i, j, k \\quad (i < j < k) \\implies \\text{triangle}[i] \neq \\text{triangle}[j] \\wedge \\text{triangle}[j] \neq \\text{triangle}[k] \\wedge \\text{triangle}[i] \neq \\text{triangle}[k] \\]\n\n    - **Cross-Container Consistency**: Ensures all triangles are referenced correctly in cross-containers such as `m_trianglesAroundVertex` and `m_trianglesInEdge`.\n        \\[ \\forall i, j \\quad (\\text{TAV}[i][j] \neq \\text{sofa::InvalidID}) \\implies (\\exists k: \\text{triangle}[k][0..2] = i) \\]\n\n- **Quad Checking (`checkQuadTopology`, `checkQuadContainer`, `checkQuadToEdgeCrossContainer`, `checkQuadToVertexCrossContainer`)**: Ensures that quads do not have repeated vertices and are correctly referenced in cross-containers.\n  \n    - **Consistency Check**: Ensures each quad has four distinct vertices (no self-loops).\n        \\[ \\forall i, j, k, l \\quad (i < j < k < l) \\implies \\text{quad}[i] \neq \\text{quad}[j] \\wedge \\ldots \\]\n\n    - **Cross-Container Consistency**: Ensures all quads are referenced correctly in cross-containers such as `m_quadsAroundVertex` and `m_quadsInEdge`.\n        \\[ \\forall i, j \\quad (\\text{QAV}[i][j] \neq \\text{sofa::InvalidID}) \\implies (\\exists k: \\text{quad}[k][0..3] = i) \\]\n\n- **Tetrahedron Checking (`checkTetrahedronTopology`, `checkTetrahedronContainer`, `checkTetrahedronToTriangleCrossContainer`, `checkTetrahedronToEdgeCrossContainer`, `checkTetrahedronToVertexCrossContainer`)**: Ensures that tetrahedra do not have repeated vertices and are correctly referenced in cross-containers.\n  \n    - **Consistency Check**: Ensures each tetrahedron has four distinct vertices (no self-loops).\n        \\[ \\forall i, j, k, l \\quad (i < j < k < l) \\implies \\text{tetra}[i] \neq \\text{tetra}[j] \\wedge \\ldots \\]\n\n    - **Cross-Container Consistency**: Ensures all tetrahedra are referenced correctly in cross-containers such as `m_tetrasAroundVertex` and `m_tetrasInTriangle`.\n        \\[ \\forall i, j \\quad (\\text{TAV}[i][j] \neq \\text{sofa::InvalidID}) \\implies (\\exists k: \\text{tetra}[k][0..3] = i) \\]\n\n- **Hexahedron Checking (`checkHexahedronTopology`, `checkHexahedronContainer`, `checkHexahedronToQuadCrossContainer`, `checkHexahedronToEdgeCrossContainer`, `checkHexahedronToVertexCrossContainer`)**: Ensures that hexahedra do not have repeated vertices and are correctly referenced in cross-containers.\n  \n    - **Consistency Check**: Ensures each hexahedron has eight distinct vertices (no self-loops).\n        \\[ \\forall i, j, k, l, m, n, o, p \\quad (i < j < k < l < m < n < o < p) \\implies \\text{hexa}[i] \neq \\text{hexa}[j] \\wedge \\ldots \\]\n\n    - **Cross-Container Consistency**: Ensures all hexahedra are referenced correctly in cross-containers such as `m_hexasAroundVertex` and `m_hexasInQuad`.\n        \\[ \\forall i, j \\quad (\\text{HAV}[i][j] \neq \\text{sofa::InvalidID}) \\implies (\\exists k: \\text{hexa}[k][0..7] = i) \\]\n\n### Integration into the Global FEM Pipeline\nThe `TopologyChecker` plays a critical role in the early stages of the FEM pipeline, specifically during mesh generation and spatial discretization. It ensures that the topology used for defining elements (edges, triangles, quads, tetrahedra, hexahedra) is consistent with expected properties:\n- **Mesh Generation**: Ensures no invalid or duplicated elements are present in the mesh.\n- **Spatial Discretization**: Verifies correct mapping and interpolation functions based on valid topological relationships.\n\n### Numerical Methods and Discretization Choices\nThe `TopologyChecker` itself does not employ numerical methods or discretization schemes directly. However, by ensuring that all topological elements are correctly defined, it indirectly supports the application of various FEM operators (mass matrix \\(M\\), stiffness matrix \\(K\\), internal forces \\(f_{int}\\)) and facilitates proper constraint handling and mapping.\n\n### Role in Variational Mechanics Framework\nThe `TopologyChecker` is a key component for ensuring that the variational mechanics formulation used in SOFA simulations is based on a valid topological structure. By validating the mesh topology, it supports the consistency required for variational formulations to accurately represent physical phenomena (e.g., deformation and stress) within deformable systems.\n\n### Summary\nThe `TopologyChecker` ensures that the mesh topology is consistent and valid, which is essential for the correct application of FEM principles in SOFA's simulation framework. It supports various checks on different topological elements and their cross-referencing relationships to ensure no invalid or duplicated entities are present, thereby facilitating proper spatial discretization and subsequent numerical analysis.",
  "abstract": "The `TopologyChecker` validates the integrity of mesh topology by checking various elements (edges, triangles, quads, tetrahedra, hexahedra) and their cross-referencing relationships to ensure no invalid or duplicated entities are present.",
  "sheet": "# TopologyChecker\n\n## Overview\nThe `TopologyChecker` is a SOFA component that validates the integrity of mesh topology within a simulation scene graph. It can be linked to any `BaseMeshTopology` container and checks topologies for various elements such as edges, triangles, quads, tetrahedra, and hexahedra.\n\n## Parameters and Data\n- **d_eachStep**: A boolean parameter that enables continuous topology checks at every simulation step if set to true. Default value is false.\n\n## Dependencies and Connections\nThe `TopologyChecker` requires a link (`l_topology`) to the `BaseMeshTopology` container it needs to test. It fits into the scene graph by being added as a child of the node containing the topology component to be tested.\n\n## Practical Notes\n- If `d_eachStep` is set to true, the topology will be checked at each simulation step using the generic method `checkTopology`. Otherwise, individual methods can be called manually for specific checks.\n- The checker ensures that all topological relationships are correctly defined and maintained by verifying containers and cross-referencing them with adjacent elements (vertices, edges, etc.)."
}