Add Build with Explicit Multi-Level Geometry for EB (#4714)

This PR adds a new `EB2::Build` variant that accepts a
`Vector<Geometry>` to explicitly specify the geometry at each AMR level.
Unlike the existing Build function that generates coarse levels through
automatic coarsening, this version constructs EB data directly from the
provided geometries at each level. This is useful for applications that
need precise control over domain specification at each AMR level or when
coarse levels are not simple coarsenings of the finest level.

Author: jmsexton03

Docs/sphinx_documentation/source/EB.rst

@@ -141,17 +141,23 @@ Given an implicit function object, say :cpp:`f`, we can make a
 :cpp:`EB2::IndexSpace`
 ----------------------
 
-We build :cpp:`EB2::IndexSpace` with a template function
+We build :cpp:`EB2::IndexSpace` with one of several functions depending
+on the application needs.
 
-.. highlight: c++
+**Standard Build with Automatic Coarsening**
+
+.. highlight:: c++
 
 ::
 
     template <typename G>
     void EB2::Build (const G& gshop, const Geometry& geom,
                      int required_coarsening_level,
                      int max_coarsening_level,
-                     int ngrow = 4);
+                     int ngrow = 4,
+                     bool build_coarse_level_by_coarsening = true,
+                     bool extend_domain_face = ExtendDomainFace(),
+                     int num_coarsen_opt = NumCoarsenOpt());
 
 Here the template parameter is a :cpp:`EB2::GeometryShop`. :cpp:`Geometry` (see
 section :ref:`sec:basics:geom`) describes the rectangular problem domain and the
@@ -173,12 +179,58 @@ ngrow` parameter specifies the number of ghost cells outside the domain on
 required levels. For levels coarser than the required level, no EB data are
 generated for ghost cells outside the domain.
 
-The newly built :cpp:`EB2::IndexSpace` is pushed on to a stack. Static function
+**Build with Explicit Multi-Level Geometry**
+
+For applications requiring explicit control over the geometry at each AMR level:
+
+.. highlight:: c++
+
+::
+
+    template <typename G>
+    void EB2::Build (const G& gshop, Vector<Geometry> geom,
+                     int ngrow = 4,
+                     bool extend_domain_face = ExtendDomainFace(),
+                     int num_coarsen_opt = NumCoarsenOpt());
+
+This version takes a :cpp:`Vector<Geometry>` where each element corresponds to
+the geometry of a specific AMR level. The Vector can be unordered, as it will be
+sorted based on :cpp:`numPts`.
+Unlike the standard :cpp:`Build` function, coarse level EB data is generated
+directly from the provided geometries rather than through automatic coarsening.
+This is useful when coarse level domains are not simple coarsenings of the fine
+level, or when you need precise control over the domain and mesh spacing at each
+level.
+
+**Build from STL File**
+
+As mentioned earlier, the EB information can alternatively be initialized from
+an STL file using:
+
+.. highlight:: c++
+
+::
+
+   void EB2::Build (const Geometry& geom,
+                    int required_coarsening_level,
+                    int max_coarsening_level,
+                    int ngrow = 4,
+                    bool build_coarse_level_by_coarsening = true,
+                    bool extend_domain_face = ExtendDomainFace(),
+                    int num_coarsen_opt = NumCoarsenOpt());
+
+This requires setting :cpp:`ParmParse` parameters ``eb2.geom_type = stl`` and
+``eb2.stl_file`` to specify the STL file path.
+
+**Managing IndexSpace Objects**
+
+Regardless of which :cpp:`Build` variant is used, the newly built
+:cpp:`EB2::IndexSpace` is pushed on to a stack. Static function
 :cpp:`EB2::IndexSpace::top()` returns a :cpp:`const &` to the new
 :cpp:`EB2::IndexSpace` object. We usually only need to build one
 :cpp:`EB2::IndexSpace` object. However, if your application needs multiple
 :cpp:`EB2::IndexSpace` objects, you can save the pointers for later use. For
-simplicity, we assume there is only one `EB2::IndexSpace` object for the rest of
+simplicity, we assume there is only one :cpp:`EB2::IndexSpace` object for the rest of
 this chapter.
 
 EBFArrayBoxFactory

Src/EB/AMReX_EB2.H

@@ -80,6 +80,10 @@ public:
                    int ngrow, bool build_coarse_level_by_coarsening,
                    bool extend_domain_face, int num_coarsen_opt);
 
+    IndexSpaceImp (const G& gshop, const Vector<Geometry>& geom,
+                   int ngrow,
+                   bool extend_domain_face, int num_coarsen_opt);
+
     IndexSpaceImp (IndexSpaceImp<G> const&) = delete;
     IndexSpaceImp (IndexSpaceImp<G> &&) = delete;
     void operator= (IndexSpaceImp<G> const&) = delete;
@@ -134,6 +138,21 @@ Build (const G& gshop, const Geometry& geom,
                                           num_coarsen_opt));
 } // NOLINT(clang-analyzer-cplusplus.NewDeleteLeaks)
 
+template <typename G>
+void
+Build (const G& gshop, Vector<Geometry> geom,
+       int ngrow = 4,
+       bool extend_domain_face = ExtendDomainFace(),
+       int num_coarsen_opt = NumCoarsenOpt())
+{
+    BL_PROFILE("EB2::Initialize()");
+    std::sort(geom.begin(), geom.end(), [] (Geometry const& a, Geometry const& b) { return a.Domain().numPts() > b.Domain().numPts(); });
+    IndexSpace::push(new IndexSpaceImp<G>(gshop, geom,
+                                          ngrow,
+                                          extend_domain_face,
+                                          num_coarsen_opt));
+} // NOLINT(clang-analyzer-cplusplus.NewDeleteLeaks)
+
 void Build (const Geometry& geom,
             int required_coarsening_level,
             int max_coarsening_level,

Src/EB/AMReX_EB2_IndexSpaceI.H

@@ -63,6 +63,32 @@ IndexSpaceImp<G>::IndexSpaceImp (const G& gshop, const Geometry& geom,
 }
 
 
+template <typename G>
+IndexSpaceImp<G>::IndexSpaceImp (const G& gshop, const Vector<Geometry>& geom,
+                                 int ngrow,
+                                 bool extend_domain_face, int num_coarsen_opt)
+    : m_gshop(gshop),
+      m_build_coarse_level_by_coarsening(false),
+      m_extend_domain_face(extend_domain_face),
+      m_num_coarsen_opt(num_coarsen_opt)
+{
+
+    auto nlevels = int(geom.size());
+    m_gslevel.reserve(nlevels);
+
+    for (int ilev = 0; ilev < nlevels; ++ilev)
+    {
+        int ng = ngrow;
+        Geometry cgeom = geom[ilev];
+        Box cdomain = cgeom.Domain();
+        m_gslevel.emplace_back(this, gshop, cgeom, EB2::max_grid_size, ng, extend_domain_face,
+                                           num_coarsen_opt-ilev);
+        m_geom.push_back(cgeom);
+        m_domain.push_back(cdomain);
+        m_ngrow.push_back(ng);
+    }
+}
+
 template <typename G>
 const Level&
 IndexSpaceImp<G>::getLevel (const Geometry& geom) const