{
  "name": "Hexa2TetraTopologicalMapping",
  "main": {
    "name": "Hexa2TetraTopologicalMapping",
    "namespace": "sofa::component::topology::mapping",
    "module": "Sofa.Component.Topology.Mapping",
    "include": "sofa/component/topology/mapping/Hexa2TetraTopologicalMapping.h",
    "doc": "Topological mapping where HexahedronSetTopology is converted to TetrahedronSetTopology\n\nThis class, called Hexa2TetraTopologicalMapping, is a specific implementation of the interface TopologicalMapping where :\nINPUT TOPOLOGY = HexahedronSetTopology\nOUTPUT TOPOLOGY = TetrahedronSetTopology\nTetra2TriangleTopologicalMapping class is templated by the pair (INPUT TOPOLOGY, OUTPUT TOPOLOGY)",
    "inherits": [
      "TopologicalMapping"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_swapping",
        "type": "bool",
        "xmlname": "swapping",
        "help": "Boolean enabling to swapp hexa-edges\\n in order to avoid bias effect"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateTopologicalMappingTopDown",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getFromIndex",
        "return_type": "int",
        "params": [
          {
            "name": "ind",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `Hexa2TetraTopologicalMapping` component is part of the SOFA framework and serves as a topological mapping that converts a HexahedronSetTopology to a TetrahedronSetTopology. This conversion allows for transforming hexahedral elements into tetrahedral elements, which can be useful in various computational biomechanics simulations where different mesh types are required.\n\nThe component implements the `TopologicalMapping` interface and initializes the target topology based on the source topology by tessellating each hexahedron into six tetrahedra. It provides a boolean data field `swapping` that can be enabled to swap hexa-edges in order to avoid bias effects during this conversion process.\n\nThe component has methods for initialization (`init`) and updating the topological mapping (`updateTopologicalMappingTopDown`). The method `getFromIndex` is implemented but currently returns an invalid index, indicating it may not be fully utilized. Additionally, the implementation of `updateTopologicalMappingTopDown` is marked as a TODO, suggesting that this functionality has yet to be completed.\n\nThis component interacts with various SOFA topology containers and modifiers, ensuring proper initialization and tessellation of the target tetrahedral mesh from the source hexahedral mesh."
  },
  "maths": {
    "maths": "The `Hexa2TetraTopologicalMapping` component in the SOFA framework performs topological mapping from a HexahedronSetTopology to a TetrahedronSetTopology. This transformation is essential for converting hexahedral elements into tetrahedral elements, which can be beneficial in various computational biomechanics simulations where different mesh types are required.\n\n### Mathematical Description:\n\n#### 1. **Hexahedron to Tetrahedra Tessellation:*\nEach hexahedron (hex) is tessellated into six tetrahedra (tets). The hex can be represented as a set of vertices \\(V = \\{v_0, v_1, v_2, v_3, v_4, v_5, v_6, v_7\\}\\), where each vertex \\(v_i\\) is associated with the coordinates in 3D space. The tessellation involves dividing these vertices into six tetrahedra as follows:\n\n- **Tetrahedron 1:** \\((v_0, v_5, v_1, v_6)\\)\n- **Tetrahedron 2:** \\((v_0, v_1, v_3, v_6)\\)\n- **Tetrahedron 3:** \\((v_1, v_3, v_6, v_2)\\)\n- **Tetrahedron 4:** \\((v_6, v_3, v_0, v_7)\\)\n- **Tetrahedron 5:** \\((v_6, v_7, v_0, v_5)\\)\n- **Tetrahedron 6:** \\((v_7, v_5, v_4, v_0)\\)\n\nIf the `swapping` parameter is enabled, the vertices are rearranged to avoid bias effects. The specific swapping operations involve:\n\n1. Swapping points on X-edges if the index condition `(i % nx)` is met.\n2. Swapping points on Y-edges if the index condition `((i / nx) % ny)` is met.\n3. Swapping points on Z-edges if the index condition `((i / (nx * ny))` is met.\n\n#### 2. **Initialization Process:*\nThe initialization process (`init`) involves:\n- Verifying the input topology types to ensure compatibility with HexahedronSetTopology and TetrahedronSetTopology containers/modifiers.\n- Clearing the output tetrahedral mesh.\n- Setting the same number of points in both topologies.\n- Reserving memory for the local-to-global index mapping vectors (`Loc2GlobVec`).\n- Iterating over each hexahedron, tessellating it into six tetrahedra, and adding these tets to the target topology container.\n\n#### 3. **Update Process:*\nThe `updateTopologicalMappingTopDown` method is currently marked as a TODO, indicating that its functionality has yet to be implemented. This method would typically handle dynamic updates in the topological mapping if necessary.\n\n### Physical Description:\n\nThe physical significance of this component lies in its ability to transform hexahedral meshes into tetrahedral ones, which can have several advantages:\n- **Mesh Compatibility:** Tetrahedra are more flexible and can conform better to complex geometries compared to hexahedra.\n- **Numerical Stability:** In some finite element simulations, tetrahedral elements might provide numerical stability benefits over hexahedral elements.\n- **Adaptivity:** Tetrahedral meshes can be more easily refined or coarsened in adaptive meshing schemes.\n\nThe tessellation process ensures that the connectivity and geometry of the original hexahedra are preserved while converting to tetrahedra. The `swapping` parameter helps mitigate any potential bias introduced by a fixed tessellation pattern, ensuring a more balanced distribution of elements."
  },
  "summary": {
    "abstract": "The `Hexa2TetraTopologicalMapping` component converts HexahedronSetTopology to TetrahedronSetTopology by tessellating each hexahedron into six tetrahedra, with an option to swap edges for bias mitigation.",
    "sheet": "\\# Hexa2TetraTopologicalMapping\n\n## Overview\nThe `Hexa2TetraTopologicalMapping` component is a topological mapping that converts HexahedronSetTopology to TetrahedronSetTopology. It tessellates each hexahedron into six tetrahedra and provides an option to swap edges to avoid bias effects.\n\n## Mathematical Model\nEach hexahedron (hex) is tessellated into six tetrahedra (tets). The vertices of a hex can be represented as \\(V = \\{v_0, v_1, v_2, v_3, v_4, v_5, v_6, v_7\\}\\), and the tessellation involves dividing these vertices into six tetrahedra as follows:\n\n- **Tetrahedron 1:** \\((v_0, v_5, v_1, v_6)\\)\n- **Tetrahedron 2:** \\((v_0, v_1, v_3, v_6)\\)\n- **Tetrahedron 3:** \\((v_1, v_3, v_6, v_2)\\)\n- **Tetrahedron 4:** \\((v_6, v_3, v_0, v_7)\\)\n- **Tetrahedron 5:** \\((v_6, v_7, v_0, v_5)\\)\n- **Tetrahedron 6:** \\((v_7, v_5, v_4, v_0)\\)\n\nIf the `swapping` parameter is enabled, vertices are rearranged to avoid bias effects by swapping points on X-, Y-, and Z-edges based on index conditions.\n\n## Parameters and Data\nThe component exposes a boolean data field:\n\n- **swapping:** Boolean enabling edge swapping to avoid bias effects. Default value: `false`."
  }
}