Rework docs of GridCreator and re-enable parallel check

'check_parallel_allowed' is now public, returns a boolean and only
issues a warning if incompatibilities are detected

dune/dorie/solver/util_grid_creator.hh

@@ -34,7 +34,7 @@ namespace Dorie {
 /// Type of grid loading mode. Defines how parameters are read from the grid.
 enum class GridMode {
     gmsh, //!< Read a GMSH file containing parameter and boundary mappings
-    regular //!< Build a grid internally and read parameter mappings from files
+    rectangular //!< Build a grid internally and read parameter mappings from files
 };
 
 /// This class builds grids by reading GMSH files or using the Dune GridFactory.
@@ -69,20 +69,20 @@ public:
     {
         const auto grid_type = _config.get<std::string>("grid.gridType");
         if (grid_type == "rectangular")
-            _grid_mode = GridMode::regular;
+            _grid_mode = GridMode::rectangular;
         else if (grid_type == "gmsh")
             _grid_mode = GridMode::gmsh;
         else
             DUNE_THROW(IOError, "Unsupported grid type!");
 
-        // this->check_parallel_allowed();
+        check_parallel_allowed();
     }
 
     /// Return the creared grid and the parameter mapping
     /** Building the grid and subsequently the GridMapper ensures that the grid
      *  and the mapping data are properly load-balanced. The GridMapper manages
      *  load-balancing and data broadcasting in its constructor.
-     *  \return Shared pointer to GridMapper.
+     *  \return Shared pointer to Dorie::GridMapper.
      */
     std::shared_ptr<GridMapper> get_mapper ()
     {
@@ -115,22 +115,30 @@ public:
         }
     }
 
-private:
-
-    /// Check if parallel execution is allowed
+    /// Return true if parallel execution is allowed. Issue a warning if not.
     /** Currently, we only allow parallel execution on YaspGrid due to
-     *  constraints imposed by the linear solver
+     *  constraints imposed by the linear solver.
      */
-    void check_parallel_allowed () const
+    bool check_parallel_allowed () const
     {
         if (_helper.size() > 1
             && not std::is_same_v<YaspGrid<Grid::dimension>, Grid>) {
-            DUNE_THROW(Dune::Exception,"DORiE does not support parallel "
-                "execution with this grid configuration!");
+            std::cout << "WARNING! DORiE's solver does not support parallel "
+                << "execution on unstructured grids. This will likely result "
+                << "in a fatal exception." << std::endl;
+            return false;
         }
+
+        return true;
     }
 
-    /// Create a GMSH grid from a file and the element and boundary index maps.
+private:
+
+    /// Create an unstructured grid from a GMSH file
+    /**
+     *  \return Tuple: Shared pointer to grid; Element index map;
+     *      Boundary index map
+     */
     std::tuple<std::shared_ptr<Grid>, std::vector<int>, std::vector<int>>
         create_gmsh_grid () const
     {
@@ -176,12 +184,14 @@ private:
         return std::make_tuple(grid, element_index_map, boundary_index_map);
     }
 
-    /// Read parameter file specifications, create a grid, and return a shared pointer to the grid
+    /// Create a rectangular grid from config file specifications
+    /** Creates a cell and boundary mapping after building the grid.
+     *  \return Tuple: Shared pointer to grid; Element index map;
+     *      Boundary index map; Number of cells in each direction
+     */
     std::tuple<std::shared_ptr<Grid>, std::vector<int>, std::vector<int>, std::vector<int>>
         create_rect_grid () const
     {
-        // check_parallel_allowed<GridType>(helper);
-
         Dune::Timer timer;
         ios_base_all_saver restore(std::cout);
         const auto level = _config.get<int>("grid.initialLevel");
@@ -256,6 +266,10 @@ private:
     }
 
     /// Read the element mapping from an H5 file
+    /** This reads the "grid.mappingFile" if given and returns the resulting
+     *  map. If not given, "grid.globalIndex" is read and broadcast to the map.
+     *  \return Tuple: Element index map; number of cells in each direction.
+     */
     std::tuple<std::vector<int>, std::vector<int>>
         read_element_index_map_from_file () const
     {