{
  "name": "HexahedronSetTopologyModifier",
  "main": {
    "name": "HexahedronSetTopologyModifier",
    "namespace": "sofa::component::topology::container::dynamic",
    "module": "Sofa.Component.Topology.Container.Dynamic",
    "include": "sofa/component/topology/container/dynamic/HexahedronSetTopologyModifier.h",
    "doc": "Topology modifier dedicated to an hexahedral topology.\n\nA class that modifies the topology by adding and removing hexahedra",
    "inherits": [
      "QuadSetTopologyModifier"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "removeIsolated",
        "type": "bool"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addHexahedra",
        "return_type": "void",
        "params": [
          {
            "name": "hexahedra",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addHexahedra",
        "return_type": "void",
        "params": [
          {
            "name": "hexahedra",
            "type": "const int &"
          },
          {
            "name": "ancestors",
            "type": "const int &"
          },
          {
            "name": "baryCoefs",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addHexahedronProcess",
        "return_type": "void",
        "params": [
          {
            "name": "e",
            "type": "Hexahedron"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeHexahedra",
        "return_type": "void",
        "params": [
          {
            "name": "hexahedraIds",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "removeItems",
        "return_type": "void",
        "params": [
          {
            "name": "items",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addHexahedraWarning",
        "return_type": "void",
        "params": [
          {
            "name": "nHexahedra",
            "type": "const int"
          },
          {
            "name": "hexahedraList",
            "type": "const int &"
          },
          {
            "name": "hexahedraIndexList",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addHexahedraWarning",
        "return_type": "void",
        "params": [
          {
            "name": "nHexahedra",
            "type": "const int"
          },
          {
            "name": "hexahedraList",
            "type": "const int &"
          },
          {
            "name": "hexahedraIndexList",
            "type": "const int &"
          },
          {
            "name": "ancestors",
            "type": "const int &"
          },
          {
            "name": "baryCoefs",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addHexahedraProcess",
        "return_type": "void",
        "params": [
          {
            "name": "hexahedra",
            "type": "const int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removeHexahedraWarning",
        "return_type": "void",
        "params": [
          {
            "name": "hexahedra",
            "type": "int &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removeHexahedraProcess",
        "return_type": "void",
        "params": [
          {
            "name": "indices",
            "type": "const int &"
          },
          {
            "name": "removeIsolatedItems",
            "type": "const bool"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addQuadsProcess",
        "return_type": "void",
        "params": [
          {
            "name": "quads",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removeQuadsProcess",
        "return_type": "void",
        "params": [
          {
            "name": "indices",
            "type": "const int &"
          },
          {
            "name": "removeIsolatedEdges",
            "type": "const bool"
          },
          {
            "name": "removeIsolatedPoints",
            "type": "const bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addEdgesProcess",
        "return_type": "void",
        "params": [
          {
            "name": "edges",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removeEdgesProcess",
        "return_type": "void",
        "params": [
          {
            "name": "indices",
            "type": "const int &"
          },
          {
            "name": "removeIsolatedItems",
            "type": "const bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addPointsProcess",
        "return_type": "void",
        "params": [
          {
            "name": "nPoints",
            "type": "const int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "removePointsProcess",
        "return_type": "void",
        "params": [
          {
            "name": "indices",
            "type": "const int &"
          },
          {
            "name": "removeDOF",
            "type": "const bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "renumberPointsProcess",
        "return_type": "void",
        "params": [
          {
            "name": "index",
            "type": "const int &"
          },
          {
            "name": "inv_index",
            "type": "const int &"
          },
          {
            "name": "renumberDOF",
            "type": "const bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "propagateTopologicalEngineChanges",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "HexahedronSetTopologyContainer",
    "description": "This is an advanced container for managing topological data in simulations involving hexahedral (3D cuboid) elements. It extends the QuadSetTopologyContainer to support not only quadrilateral but also hexahedral elements and their connectivity information.",
    "parameters": [
      {
        "name": "filename",
        "type": "string",
        "description": "The path of a file from which to load the initial mesh data. The format must be supported by SOFA's mesh loaders (e.g., .obj, .vtk)."
      },
      {
        "name": "position",
        "type": "Vec3d",
        "container": true,
        "description": "Initial positions of vertices in the topology."
      },
      {
        "name": "hexahedron",
        "type": "Hexahedron",
        "container": true,
        "description": "Initial hexahedral elements defined by 8 vertex indices. Each hexahedron is represented as a set of 8 integers, each corresponding to an index in the position array."
      }
    ],
    "functions": [
      {
        "name": "removeHexahedra",
        "parameters": [
          "hexahedraIds"
        ],
        "description": "Removes specified hexahedral elements from the container. It filters out invalid indices and updates the topology accordingly, removing any isolated vertices or edges that result from this operation."
      },
      {
        "name": "removeItems",
        "parameters": [
          "items"
        ],
        "description": "An alias for removeHexahedra function. It allows removing items of type hexahedron by providing their IDs."
      },
      {
        "name": "propagateTopologicalEngineChanges",
        "parameters": [],
        "description": "Applies the topological changes stored in an event queue to any connected topology handlers, ensuring that all dependent components are updated with the latest topology information."
      }
    ],
    "events": [
      {
        "name": "beginChange/endChange",
        "type": "EventIterator",
        "description": "Events marking the beginning and end of a batch of topological changes. These events help manage updates efficiently by grouping multiple operations together before propagating them to connected handlers."
      },
      {
        "name": "isHexahedronTopologyDirty/cleanHexahedronTopologyFromDirty",
        "type": "StateFlag",
        "description": "Flags indicating whether the hexahedral topology has been modified and needs to be updated in connected components. These flags are used internally by propagateTopologicalEngineChanges to determine which updates need to be applied."
      }
    ],
    "dependencies": [
      {
        "name": "QuadSetTopologyContainer",
        "description": "Inherits from this class, extending its functionality to support hexahedrons rather than just quadrilaterals."
      },
      {
        "name": "sofa::component::topology::container::dynamic namespace",
        "description": "Part of the SOFA (Simulation Of Fluids with Animated Boundaries) framework, providing dynamic topology management for simulations."
      }
    ],
    "example_use_cases": [
      "The HexahedronSetTopologyContainer is useful in finite element analysis and other physics-based simulations where 3D volumes need to be represented by hexahedral elements. For example, simulating the deformation of a solid object under stress or modeling porous media flow through a structured grid."
    ]
  },
  "maths": {
    "maths": "The `HexahedronSetTopologyModifier` in the SOFA framework is primarily responsible for modifying the topology of a hexahedral mesh by adding or removing hexahedra (cuboid elements). This modifier does not directly contribute to any governing equations such as mass matrix $M$, stiffness matrix $K$, internal force vector $\\mathbf{f}_{int}$, or residual vector $R$. Instead, it operates at a lower level by managing the connectivity and structure of the mesh. The mathematical description of its role in the FEM pipeline is as follows:\n\n1. **Topology Management**:\n   - This component maintains and modifies the topological data structure that describes how nodes (vertices) are connected to form hexahedral elements.\n   - It handles operations such as adding new hexahedra, removing existing ones, and ensuring consistency with other geometric entities like edges, quads, and vertices.\n\n2. **Connectivity Data Structures**:\n   - The topology of the mesh is stored in various data structures, including arrays that track which hexahedra are adjacent to each vertex, edge, or quad. These connectivity relationships are crucial for FEM discretization since they determine how shape functions and integrals are evaluated.\n\n3. **Adding Hexahedra**:\n   - When adding a new hexahedron with vertices $\\mathbf{v}_0, \\mathbf{v}_1, \\ldots, \\mathbf{v}_7$, the component ensures that these vertices form valid quadrilateral faces and edges.\n   - The component updates data structures like `m_hexahedraAroundVertex`, `m_hexahedraAroundEdge`, and `m_hexahedraAroundQuad` to reflect new connectivity information.\n\n4. **Removing Hexahedra**:\n   - When removing hexahedra, the component ensures that any dependent edges or quads are also removed if they become isolated.\n   - The removal process updates the same data structures mentioned above to ensure consistency in the mesh topology.\n\n5. **Numerical Methods and Discretization Choices**:\n   - Although `HexahedronSetTopologyModifier` itself does not involve numerical methods or discretization, it ensures that the topology is consistent for FEM discretization steps such as shape function evaluation and integration over elements.\n\n6. **Role in Variational Mechanics Framework**:\n   - This component fits into the broader variational mechanics framework by ensuring the mesh is correctly structured before performing weak form derivations, spatial discretizations (FEM), and subsequent nonlinear solve stages.\n   - Proper topology management is essential for accurate integration of internal forces and correct assembly of system matrices like $M$ and $K$, as well as enforcement of boundary conditions.\n\nIn summary, `HexahedronSetTopologyModifier` plays a critical role in maintaining the integrity and consistency of the mesh topology, which is foundational to the success of FEM simulations involving hexahedral elements."
  },
  "summary": {
    "abstract": "Modifies the topology by adding and removing hexahedral elements, ensuring consistent connectivity data structures for finite element simulations.",
    "sheet": "# HexahedronSetTopologyModifier\n\n## Overview\nThis component is a topology modifier dedicated to managing hexahedral (3D cuboid) elements. It extends `QuadSetTopologyModifier` to support operations such as adding and removing hexahedra, ensuring the mesh remains consistent for finite element simulations.\n\n## Parameters and Data\n- **removeIsolated**: A boolean parameter that controls whether isolated items should be removed when modifying the topology (default: false).\n\n## Dependencies and Connections\nThis component typically requires a `HexahedronSetTopologyContainer` to manage the connectivity data structures. It interacts with other components in the scene graph by updating the mesh topology, which affects subsequent FEM discretization steps."
  }
}