diff --git a/src/include/serif/discretization/domain/mesh/topology.hpp b/src/include/serif/discretization/domain/mesh/topology.hpp index 87ddb315..d016b5c2 100644 --- a/src/include/serif/discretization/domain/mesh/topology.hpp +++ b/src/include/serif/discretization/domain/mesh/topology.hpp @@ -1,56 +1,127 @@ #pragma once +/** + * @file topology.hpp + * @author Emily M. Boudreaux + * + * @brief This file defines the MeshTopology class, which provides a convenient interface for querying the topological relationships between elements, faces, and boundaries in a mesh. + */ + #include #include namespace mfem { + /** + * @brief Forward declaration of the mfem::Mesh class to avoid including the entire MFEM header. + * + * @todo We should probably consider doing this more often and in some central location since ideally we would avoid including MFEM headers in our own headers. Due to how + * heavily templated our code is that wont always be possible, but there are many places where we could. This has the potential to dramatically reduce compile times + * since our compile time is primarily limited by parsing through the MFEM headers at the moment. + */ class Mesh; } // MeshTopology namespace serif::discretization::domain::mesh { + /** + * @struct FaceElements + * @brief A simple struct to hold the IDs of the two elements that share a face. If the face is a boundary face, one of the element IDs will be -1. + */ struct FaceElements { int firstElementID{-1}; int secondElementID{-1}; }; + /** + * @class MeshTopology + * @brief Provides a convenient interface for querying the topological relationships between elements, faces, and boundaries in a mesh. + */ class MeshTopology final { public: + + /** + * @brief Constructs a MeshTopology object from an MFEM mesh. Note that MeshTopology does not own the mesh; + * @param mesh The MFEM mesh from which to extract topological information. + */ explicit MeshTopology(const mfem::Mesh &mesh); + /** + * @brief Returns the number of elements in the mesh. + * @return The number of elements in the mesh. + */ [[nodiscard]] int element_count() const noexcept; + + /** + * @brief Returns the number of faces in the mesh. + * @return The number of faces in the mesh. + */ [[nodiscard]] int face_count() const noexcept; + + /** + * @brief Returns the number of boundary elements in the mesh. + * @return The number of boundary elements in the mesh. + */ [[nodiscard]] int boundary_element_count() const noexcept; - // The MFEM element attribute of a volume element, i.e. which DomainID - // the mesh claims this element belongs to. + /** + * @brief Returns the domain ID of the specified element. + * @param elementID The ID of the element for which to retrieve the domain ID. + * @return The domain ID of the specified element. + * + * @note The domain ID is the MFEM element attribute (often called the material attribute) of a volume element, i.e. which DomainID the mesh claims this element belongs to. + */ [[nodiscard]] int element_domain_id(int elementID) const; - // The MFEM boundary attribute of a boundary element, i.e. which - // BoundaryID the mesh claims this boundary element belongs to. + /** + * @brief Returns the boundary ID of the specified boundary element. + * @param boundaryElementID The ID of the boundary element for which to retrieve the boundary ID. + * @return The boundary ID of the specified boundary element. + * + * @note The boundary ID is the MFEM boundary attribute of a boundary element, i.e. which BoundaryID the mesh claims this boundary element belongs to. + */ [[nodiscard]] int boundary_element_boundary_id(int boundaryElementID) const; + /** + * @brief Returns the elements sharing the specified face. + * @param faceID The ID of the face for which to retrieve the elements. + * @return A FaceElements struct containing the IDs of the elements sharing the face. + */ [[nodiscard]] FaceElements face_elements(int faceID) const; - // Elements sharing an interior face with elementID. Not filtered by - // domain: callers that care about one domain filter as they walk. + /** + * @brief Returns the elements sharing an interior face with the specified element. + * @param elementID The ID of the element for which to retrieve the neighboring elements. + * @return A vector containing the IDs of the elements sharing an interior face with the specified element. + * + * @note The returned elements are not filtered by domain. Callers that care about one domain should filter as they walk. + */ [[nodiscard]] const std::vector &element_neighbors(int elementID) const; - // The face a boundary element sits on, or -1 if MFEM reports none. + /** + * @brief Returns the face a boundary element sits on. + * @param boundaryElementID The ID of the boundary element for which to retrieve the face. + * @return The ID of the face the boundary element sits on, or -1 if MFEM reports none. + */ [[nodiscard]] int boundary_element_face(int boundaryElementID) const; - // A face may carry more than one boundary element + /** + * @brief Returns the boundary elements on the specified face. + * @param faceID The ID of the face for which to retrieve the boundary elements. + * @return A vector containing the IDs of the boundary elements on the specified face. + * + * @note A face may carry more than one boundary element. + */ [[nodiscard]] const std::vector &boundary_elements_on_face(int faceID) const; private: - std::vector m_elementDomainIDs; - std::vector m_faceElements; - std::vector> m_elementNeighbors; + std::vector m_elementDomainIDs; ///< The domain IDs of the elements in the mesh. + std::vector m_faceElements; ///< The elements sharing each face in the mesh. + std::vector> m_elementNeighbors; ///< The elements sharing an interior face with each element in the mesh. - std::vector m_boundaryElementBoundaryIDs; - std::vector m_boundaryElementFaceIDs; - std::vector> m_boundaryElementsByFace; + std::vector m_boundaryElementBoundaryIDs; ///< The boundary IDs of the boundary elements in the mesh. + std::vector m_boundaryElementFaceIDs; ///< The face IDs of the boundary elements in the mesh. + std::vector> m_boundaryElementsByFace; ///< The boundary elements on each face in the mesh. - static const std::vector s_noElements; + static const std::vector s_noElements; ///< A static empty vector to return when an element has no neighbors or a face has no boundary elements. }; }