docs(domain/mesh): added doxygen comments throughout

This commit is contained in:
2026-10-05 08:09:59 -04:00
parent 0db22935b4
commit f1f3e77ea8

View File

@@ -1,56 +1,127 @@
#pragma once #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 <cstddef> #include <cstddef>
#include <vector> #include <vector>
namespace mfem { 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; class Mesh;
} }
// MeshTopology // MeshTopology
namespace serif::discretization::domain::mesh { 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 { struct FaceElements {
int firstElementID{-1}; int firstElementID{-1};
int secondElementID{-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 { class MeshTopology final {
public: 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); 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; [[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; [[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; [[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; [[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; [[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; [[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<int> &element_neighbors(int elementID) const; [[nodiscard]] const std::vector<int> &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; [[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<int> &boundary_elements_on_face(int faceID) const; [[nodiscard]] const std::vector<int> &boundary_elements_on_face(int faceID) const;
private: private:
std::vector<int> m_elementDomainIDs; std::vector<int> m_elementDomainIDs; ///< The domain IDs of the elements in the mesh.
std::vector<FaceElements> m_faceElements; std::vector<FaceElements> m_faceElements; ///< The elements sharing each face in the mesh.
std::vector<std::vector<int>> m_elementNeighbors; std::vector<std::vector<int>> m_elementNeighbors; ///< The elements sharing an interior face with each element in the mesh.
std::vector<int> m_boundaryElementBoundaryIDs; std::vector<int> m_boundaryElementBoundaryIDs; ///< The boundary IDs of the boundary elements in the mesh.
std::vector<int> m_boundaryElementFaceIDs; std::vector<int> m_boundaryElementFaceIDs; ///< The face IDs of the boundary elements in the mesh.
std::vector<std::vector<int>> m_boundaryElementsByFace; std::vector<std::vector<int>> m_boundaryElementsByFace; ///< The boundary elements on each face in the mesh.
static const std::vector<int> s_noElements; static const std::vector<int> s_noElements; ///< A static empty vector to return when an element has no neighbors or a face has no boundary elements.
}; };
} }