Merge branch 'AMReX-Codes:development' into development

Author: ruohai0925

Docs/sphinx_documentation/source/Basics.rst

@@ -669,8 +669,9 @@ the parser.
    parser.registerVariables({"x","y","z"});
    auto f = parser.compile<3>();  // 3 because there are three variables.
 
-   // f can be used in both host and device code.  It takes 3 arguments in
-   // this example.  The parser object must be alive for f to be valid.
+   // ParserExecutor<3> f is thread-safe, and can be used in both host and
+   // device code. It takes 3 arguments in this example. The parser object
+   // must be alive for f to be valid.
    for (int k = 0; ...) {
      for (int j = 0; ...) {
        for (int i = 0; ...) {
@@ -685,8 +686,8 @@ Local automatic variables can be defined in the expression.  For example,
 
 ::
 
-   Parser parser("r2=x*x+y*y; r=sqrt(r2); cos(a+r2)*log(r)"
-   parser.setConstant(a, ...);
+   Parser parser("r2=x*x+y*y; r=sqrt(r2); cos(a+r2)*log(r)");
+   parser.setConstant("a", ...);
    parser.registerVariables({"x","y"});
    auto f = parser.compile<2>();  // 2 because there are two variables.
 

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