Feature: Add face functionality to handle and convenient constructors

mesh_handle/competence_pack.hxx

@@ -45,7 +45,12 @@ struct competence_pack
 };
 
 /** Predefined competence pack combining all caching competences. */
-using cache_competences = competence_pack<cache_volume, cache_vertex_coordinates, cache_centroid, cache_neighbors>;
+using all_cache_competences = competence_pack<cache_volume, cache_diameter, cache_vertex_coordinates, cache_centroid,
+                                              cache_face_area, cache_face_centroid, cache_face_normal, cache_neighbors>;
+
+/** Predefined competence pack combining all competences related to faces. */
+using cache_face_competences
+  = competence_pack<cache_face_area, cache_face_centroid, cache_face_normal, cache_neighbors>;
 
 }  // namespace t8_mesh_handle
 #endif /* !T8_COMPETENCE_PACK_HXX */

mesh_handle/competences.hxx

@@ -71,6 +71,29 @@ struct cache_volume: public t8_crtp_operator<TUnderlying, cache_volume>
     m_volume; /**< Cache for the volume. Use optional to allow no value if cache is not filled. */
 };
 
+/**
+ * Competence to cache the diameter of an element at the first function call.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ */
+template <typename TUnderlying>
+struct cache_diameter: public t8_crtp_operator<TUnderlying, cache_diameter>
+{
+ public:
+  /**
+   * Function that checks if the cache for the diameter has been filled.
+   * \return true if the cache has been filled, false otherwise.
+   */
+  bool
+  diameter_cache_filled () const
+  {
+    return m_diameter.has_value ();
+  }
+
+ protected:
+  mutable std::optional<double>
+    m_diameter; /**< Cache for the diameter. Use optional to allow no value if cache is not filled. */
+};
+
 /**
  * Competence to cache the vertex coordinates of an element at the first function call.
  * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
@@ -117,12 +140,81 @@ struct cache_centroid: public t8_crtp_operator<TUnderlying, cache_centroid>
     m_centroid; /**< Cache for the coordinates of the centroid. Use optional to allow no value if cache is not filled. */
 };
 
+/**
+ * Competence to cache the area of a specific face at the first function call.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ */
+template <typename TUnderlying>
+struct cache_face_area: t8_crtp_operator<TUnderlying, cache_face_area>
+{
+ public:
+  /**
+   * Function that checks if the cache for a face has been filled.
+   * \param [in] face The face for which the cache should be checked.
+   * \return true if the cache has been filled, false otherwise.
+   */
+  bool
+  face_area_cache_filled (int face) const
+  {
+    return m_face_area[face].has_value ();
+  }
+
+ protected:
+  mutable std::vector<std::optional<double>> m_face_area; /**< Vector with the face area each face. */
+};
+
+/**
+ * Competence to cache the centroid of a specific face at the first function call.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ */
+template <typename TUnderlying>
+struct cache_face_centroid: t8_crtp_operator<TUnderlying, cache_face_centroid>
+{
+ public:
+  /**
+   * Function that checks if the cache for a face has been filled.
+   * \param [in] face The face for which the cache should be checked.
+   * \return true if the cache has been filled, false otherwise.
+   */
+  bool
+  face_centroid_cache_filled (int face) const
+  {
+    return m_face_centroid[face].has_value ();
+  }
+
+ protected:
+  mutable std::vector<std::optional<t8_3D_point>> m_face_centroid; /**< Vector with the face centroid each face. */
+};
+
+/**
+ * Competence to cache the normal of a specific face at the first function call.
+ * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
+ */
+template <typename TUnderlying>
+struct cache_face_normal: t8_crtp_operator<TUnderlying, cache_face_normal>
+{
+ public:
+  /**
+   * Function that checks if the cache for a face has been filled.
+   * \param [in] face The face for which the cache should be checked.
+   * \return true if the cache has been filled, false otherwise.
+   */
+  bool
+  face_normal_cache_filled (int face) const
+  {
+    return m_face_normal[face].has_value ();
+  }
+
+ protected:
+  mutable std::vector<std::optional<t8_3D_vec>> m_face_normal; /**< Vector with the face normal each face. */
+};
+
 /**
  * Competence to cache the neighbors of an element at a specific face at the first function call.
  * \tparam TUnderlying Use the \ref element with specified competences as template parameter.
  */
 template <typename TUnderlying>
-struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_centroid>
+struct cache_neighbors: t8_crtp_operator<TUnderlying, cache_neighbors>
 {
  public:
   /**

mesh_handle/constructor_wrapper.hxx

@@ -0,0 +1,99 @@
+/*
+  This file is part of t8code.
+  t8code is a C library to manage a collection (a forest) of multiple
+  connected adaptive space-trees of general element classes in parallel.
+
+  Copyright (C) 2025 the developers
+
+  t8code is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  t8code is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with t8code; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+*/
+
+/** \file constructor_wrapper.hxx
+ * Construct a mesh handle instance from a cmesh and some default mesh handles.
+ */
+
+#ifndef T8_CONSTRUCTOR_WRAPPER_HXX
+#define T8_CONSTRUCTOR_WRAPPER_HXX
+
+#include <t8.h>
+#include <t8_forest/t8_forest_general.h>
+#include <t8_cmesh/t8_cmesh.h>
+#include <t8_schemes/t8_default/t8_default.hxx>
+#include <t8_cmesh/t8_cmesh_examples.h>
+#include <memory>
+
+namespace t8_mesh_handle
+{
+
+/** Build a uniformly refined mesh handle on a coarse mesh using a default scheme.
+ * \param [in] cmesh         A coarse mesh.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle with coarse mesh \a cmesh and refinement level \a level.
+ */
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_new_uniform_default (const t8_cmesh_t cmesh, const int level, const sc_MPI_Comm comm,
+                            const bool do_face_ghost = false)
+{
+  const t8_scheme *scheme = t8_scheme_new_default ();
+  t8_forest_t forest = t8_forest_new_uniform (cmesh, scheme, level, do_face_ghost, sc_MPI_COMM_WORLD);
+  return std::make_unique<TMesh> (forest);
+}
+
+/** Hybercube with 6 Tets, 6 Prism, 4 Hex. Refined uniformly to given level using the default scheme.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_partition  If non-zero create a partitioned cmesh.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \param [in] periodic      If non-zero create a periodic cmesh in each direction.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle initially consisting of 6 Tets, 6 prism and 4 hex.
+ *         Together, they form a cube.
+*/
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_hybrid_hypercube_uniform_default (const int level, const sc_MPI_Comm comm, const bool do_partition = false,
+                                         const bool do_face_ghost = false, const bool periodic = false)
+{
+  t8_cmesh_t cmesh = t8_cmesh_new_hypercube_hybrid (comm, do_partition, periodic);
+  return handle_new_uniform_default<TMesh> (cmesh, level, comm, do_face_ghost);
+}
+
+/** Construct hybercube from one primitive tree class. Refined uniformly to given level using the default scheme.
+ * \param [in] eclass        This element class determines the dimension and the number of trees needed to construct a cube.
+ * \param [in] level         An initial uniform refinement level.
+ * \param [in] comm          MPI communicator to use.
+ * \param [in] do_partition  If non-zero create a partitioned cmesh.
+ * \param [in] do_face_ghost If true, a layer of ghost elements is created.
+ * \param [in] periodic      If non-zero create a periodic cmesh in each direction. Not possible with \a eclass pyramid.
+ * \tparam TMesh             The mesh handle class.
+ * \return Unique pointer to a uniformly refined mesh handle hypercube.
+*/
+template <typename TMesh>
+std::unique_ptr<TMesh>
+handle_hypercube_uniform_default (t8_eclass_t eclass, const int level, const sc_MPI_Comm comm,
+                                  const bool do_partition = false, const bool do_face_ghost = false,
+                                  const bool periodic = false)
+{
+  // Broadcast option is hidden from the user.
+  t8_cmesh_t cmesh = t8_cmesh_new_hypercube (eclass, comm, 0, do_partition, periodic);
+  return handle_new_uniform_default<TMesh> (cmesh, level, comm, do_face_ghost);
+}
+
+}  // namespace t8_mesh_handle
+#endif /* !T8_CONSTRUCTOR_WRAPPER_HXX */