From baf940a8eaec3fced3496cedf3d8ac33376a1cd3 Mon Sep 17 00:00:00 2001
From: Timo Heister <timo.heister@gmail.com>
Date: Thu, 16 Apr 2020 17:45:52 -0400
Subject: [PATCH] documentation: workload_imbalance and assert valid

---
 include/deal.II/multigrid/mg_tools.h | 9 +++++++++
 source/multigrid/mg_tools.cc         | 5 +++++
 2 files changed, 14 insertions(+)

diff --git a/include/deal.II/multigrid/mg_tools.h b/include/deal.II/multigrid/mg_tools.h
index 1d3f6240d5..c57546fa1d 100644
--- a/include/deal.II/multigrid/mg_tools.h
+++ b/include/deal.II/multigrid/mg_tools.h
@@ -290,6 +290,15 @@ namespace MGTools
    * globally refined meshes). Values greater than 1 estimate the slowdown
    * one should see in a geometric multigrid v-cycle as compared with the same
    * computation on a perfectly distributed mesh hierarchy.
+   *
+   * This function is a collective MPI call between all ranks of the
+   * Triangulation and therefore needs to be called from all ranks.
+   *
+   * @note This function requires that
+   * parallel::TriangulationBase::is_multilevel_hierarchy_constructed()
+   * is true, which can be controlled by setting the
+   * construct_multigrid_hierarchy flag when constructing the
+   * Triangulation.
    */
   template <int dim, int spacedim>
   double
diff --git a/source/multigrid/mg_tools.cc b/source/multigrid/mg_tools.cc
index 70a3fa81d8..9dac385c63 100644
--- a/source/multigrid/mg_tools.cc
+++ b/source/multigrid/mg_tools.cc
@@ -1668,6 +1668,11 @@ namespace MGTools
           dynamic_cast<const parallel::TriangulationBase<dim, spacedim> *>(
             &tria))
       {
+        Assert(
+          tr->is_multilevel_hierarchy_constructed(),
+          ExcMessage(
+            "We can only compute the workload imbalance if the multilevel hierarchy has been constructed!"));
+
         const unsigned int n_proc =
           Utilities::MPI::n_mpi_processes(tr->get_communicator());
         const unsigned int n_global_levels = tr->n_global_levels();
-- 
2.39.5