{
  "name": "CompareTopology",
  "main": {
    "name": "CompareTopology",
    "namespace": "sofa::component::playback",
    "module": "Sofa.Component.Playback",
    "include": "sofa/component/playback/CompareTopology.h",
    "doc": "Compare Topology containers from a reference frame to the associated Topology.\n\nCompare Topology vectors from file at each timestep",
    "inherits": [
      "ReadTopology"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "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": "processCompareTopology",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "canCreate",
        "return_type": "bool",
        "params": [
          {
            "name": "obj",
            "type": "T *&"
          },
          {
            "name": "context",
            "type": "core::objectmodel::BaseContext *"
          },
          {
            "name": "arg",
            "type": "core::objectmodel::BaseObjectDescription *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "getTotalError",
        "return_type": "unsigned int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getErrors",
        "return_type": "const int &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `CompareTopology` component in the SOFA framework is designed to compare topology containers from a reference frame to an associated Topology at each timestep. It extends the functionality provided by `ReadTopology`, inheriting its behavior and adding specific comparison logic.\n\n### Role and Purpose:\nThe primary role of `CompareTopology` is to validate the consistency between the current simulation state's topology and a predefined or recorded reference topology, ensuring that elements like edges, triangles, quads, tetrahedra, and hexahedra match the expected structure. This can be particularly useful for debugging simulations, validating data integrity, and comparing results from different runs.\n\n### Interactions with Other Components:\n- **Inheritance:** It inherits from `ReadTopology`, which provides basic functionality to read topology information.\n- **Event Handling:** The component overrides the `handleEvent` method to process specific events during simulation, particularly at the beginning of a timestep (`AnimateBeginEvent`).\n- **Mechanical State and Topology Access:** It accesses the current mechanical state and associated topology via the SOFA context.\n\n### Practical Usage:\nThe component compares various elements (edges, triangles, quads, tetrahedra, hexahedra) from a file to the current simulation's topology. Errors are counted for each type of element and stored in `listError`, which can be retrieved using the `getErrors` method. The total number of errors is available through the `getTotalError` method.\n\n### Data Fields:\nThe internal state includes counters (`EdgesError`, `TrianglesError`, etc.) that track discrepancies between the reference topology and the current simulation topology."
  },
  "maths": {
    "maths": "# Mathematical Description of the CompareTopology Component\n\n## Overview\nThe `CompareTopology` component in the SOFA framework is designed to compare and validate the topological structure between a recorded reference state (from a file) and the current simulation's topology. This validation process can be crucial for ensuring data integrity, debugging simulations, and comparing results from different runs.\n\n## Mathematical Formulation\n### Topology Representation\nIn computational geometry and simulation frameworks like SOFA, topologies are often represented as collections of elements such as edges, triangles (2D), quads (2D), tetrahedra (3D), and hexahedra (3D). These elements form the basis for defining shapes and structures in simulations.\n\n### Elements Comparison\nThe `CompareTopology` component compares these topological elements between two states:\n1. **Reference State**: This is read from a file, containing predefined topology information.\n2. **Current Simulation State**: This is the topology of the current simulation step.\n\n#### Edge Comparisons\n- **Edges**: An edge is represented as an unordered pair of vertices \\((v_i, v_j)\\). The component compares the set of edges from both states and counts mismatches (i.e., edges present in one state but not the other).\n  - Mathematically: If \\(E_{\text{ref}} = \\\\{e_1^{\text{ref}}, e_2^{\text{ref}}, ..., e_n^{\text{ref}}\\\\}\\) is the set of edges from the reference state and \\(E_{\text{sim}} = \\\\{e_1^{\text{sim}}, e_2^{\text{sim}}, ..., e_m^{\text{sim}}\\\\}\\) is the set from the current simulation, then mismatches are counted as:\n  \\[ E_{\text{mismatch}} = (E_{\text{ref}} \\\\setminus E_{\text{sim}}) \\\\cup (E_{\text{sim}} \\\\setminus E_{\text{ref}}) \\]\n\n#### Triangle Comparisons\n- **Triangles**: A triangle is represented by three vertices forming a simplex \\(T = [v_i, v_j, v_k]\\). The component compares the set of triangles from both states and counts mismatches similarly to edges.\n  - Mathematically: If \\(T_{\text{ref}} = \\\\{t_1^{\text{ref}}, t_2^{\text{ref}}, ..., t_n^{\text{ref}}\\\\}\\) is the set of triangles from the reference state and \\(T_{\text{sim}} = \\\\{t_1^{\text{sim}}, t_2^{\text{sim}}, ..., t_m^{\text{sim}}\\\\}\\), then mismatches are counted as:\n  \\[ T_{\text{mismatch}} = (T_{\text{ref}} \\\\setminus T_{\text{sim}}) \\\\cup (T_{\text{sim}} \\\\setminus T_{\text{ref}}) \\]\n\n#### Quad Comparisons\n- **Quads**: A quad is a four-sided polygon represented by four vertices forming a quadrilateral. The component compares the set of quads from both states and counts mismatches similarly to edges and triangles.\n  - Mathematically: If \\(Q_{\text{ref}} = \\\\{q_1^{\text{ref}}, q_2^{\text{ref}}, ..., q_n^{\text{ref}}\\\\}\\) is the set of quads from the reference state and \\(Q_{\text{sim}} = \\\\{q_1^{\text{sim}}, q_2^{\text{sim}}, ..., q_m^{\text{sim}}\\\\}\\), then mismatches are counted as:\n  \\[ Q_{\text{mismatch}} = (Q_{\text{ref}} \\\\setminus Q_{\text{sim}}) \\\\cup (Q_{\text{sim}} \\\\setminus Q_{\text{ref}}) \\]\n\n#### Tetrahedron Comparisons\n- **Tetrahedra**: A tetrahedron is represented by four vertices forming a 3D simplex. The component compares the set of tetrahedra from both states and counts mismatches similarly to edges, triangles, and quads.\n  - Mathematically: If \\(K_{\text{ref}} = \\\\{k_1^{\text{ref}}, k_2^{\text{ref}}, ..., k_n^{\text{ref}}\\\\}\\) is the set of tetrahedra from the reference state and \\(K_{\text{sim}} = \\\\{k_1^{\text{sim}}, k_2^{\text{sim}}, ..., k_m^{\text{sim}}\\\\}\\), then mismatches are counted as:\n  \\[ K_{\text{mismatch}} = (K_{\text{ref}} \\\\setminus K_{\text{sim}}) \\\\cup (K_{\text{sim}} \\\\setminus K_{\text{ref}}) \\]\n\n#### Hexahedron Comparisons\n- **Hexahedra**: A hexahedron is a six-faced polyhedron represented by eight vertices forming a 3D prism. The component compares the set of hexahedra from both states and counts mismatches similarly to other elements.\n  - Mathematically: If \\(H_{\text{ref}} = \\\\{h_1^{\text{ref}}, h_2^{\text{ref}}, ..., h_n^{\text{ref}}\\\\}\\) is the set of hexahedra from the reference state and \\(H_{\text{sim}} = \\\\{h_1^{\text{sim}}, h_2^{\text{sim}}, ..., h_m^{\text{sim}}\\\\}\\), then mismatches are counted as:\n  \\[ H_{\text{mismatch}} = (H_{\text{ref}} \\\\setminus H_{\text{sim}}) \\\\cup (H_{\text{sim}} \\\\setminus H_{\text{ref}}) \\]\n\n### Error Counting and Reporting\nThe component maintains counters (`EdgesError`, `TrianglesError`, etc.) for each type of mismatch. These counters are summed up to report the total number of errors.\n- Total error count: \\( E_{\\text{total}} = |E_{\text{mismatch}}| + |T_{\text{mismatch}}| + |Q_{\text{mismatch}}| + |K_{\text{mismatch}}| + |H_{\text{mismatch}}| \\)\n\n## Conclusion\nThe `CompareTopology` component systematically compares and validates the topology elements between a reference state and the current simulation, providing a detailed error count to help ensure data integrity and correctness."
  },
  "summary": {
    "abstract": "The `CompareTopology` component compares the topology of a simulation at each timestep with a predefined reference topology, counting mismatches in edges, triangles, quads, tetrahedra, and hexahedra.",
    "sheet": "# CompareTopology\n\n## Overview\nThe `CompareTopology` component is designed to validate the consistency between the current simulation state's topology and a predefined or recorded reference topology. It inherits from `ReadTopology`, which provides basic functionality for reading topology information.\n\n## Parameters and Data\n- **EdgesError**: Counter for mismatched edges.\n- **TrianglesError**: Counter for mismatched triangles.\n- **QuadsError**: Counter for mismatched quads.\n- **TetrahedraError**: Counter for mismatched tetrahedra.\n- **HexahedraError**: Counter for mismatched hexahedra.\n\n## Dependencies and Connections\nThe component typically requires a `ReadTopology` instance to provide the reference topology information. It fits into the scene graph by processing events at each timestep, particularly during the `AnimateBeginEvent`, to compare the current simulation's topology with the reference topology.\n\n## Practical Notes\n- The component counts mismatches between the reference and current topologies for various elements (edges, triangles, quads, tetrahedra, hexahedra).\n- Errors are stored in counters (`EdgesError`, `TrianglesError`, etc.), which can be retrieved using methods like `getErrors`.\n- Total errors can be obtained via the `getTotalError` method."
  }
}