Add some documentation.

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 8e670a1283611e198ab185bc15e7b49fe7118fd5..d4c1604d430d7696a4bf1be4ef576fe637c329b0 100644 (file)
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -935,10 +935,10 @@ namespace GridTools
 
 
   /**
-   * This function returns a list of all the neighbor cells of the given cell.
-   * Here, a neighbor is defined as one having at least part of a face in common
-   * with the given cell, but not edge (in 3d) or vertex neighbors (in 2d and
-   * 3d).
+   * This function returns a list of all the active neighbor cells of the
+   * given, active cell.  Here, a neighbor is defined as one having at least
+   * part of a face in common with the given cell, but not edge (in 3d) or
+   * vertex neighbors (in 2d and 3d).
    *
    * The first element of the returned list is the cell provided as
    * argument. The remaining ones are neighbors: The function loops over all
@@ -962,6 +962,13 @@ namespace GridTools
    * with the cells of a patch. To this end, there are further functions working
    * on patches in namespace DoFTools.
    *
+   * @note In the context of a parallel distributed computation, it only makes
+   * sense to call this function on locally owned cells. This is because the
+   * neighbors of locally owned cells are either locally owned themselves, or
+   * ghost cells. For both, we know that these are in fact the real cells of
+   * the complete, parallel triangulation. We can also query the degrees of
+   * freedom on these.
+   *
    * @author Arezou Ghesmati, Wolfgang Bangerth, 2014
    */
   template <class Container>

diff --git a/source/grid/grid_tools.cc b/source/grid/grid_tools.cc
index e6aca8208406905648621adfb5395bffc14f38e3..c2ba9e2d4a4e3b54681219d54374e8546cb38043 100644 (file)
--- a/source/grid/grid_tools.cc
+++ b/source/grid/grid_tools.cc
@@ -2094,6 +2094,11 @@ next_cell:
   std::vector<typename Container::active_cell_iterator>
   get_patch_around_cell(const typename Container::active_cell_iterator &cell)
   {
+    Assert (cell->is_locally_owned(),
+           ExcMessage ("This function only makes sense if the cell for "
+                       "which you are asking for a patch, is locally "
+                       "owned."));
+    
     std::vector<typename Container::active_cell_iterator> patch;
     patch.push_back (cell);
     for (unsigned int face_number=0; face_number<GeometryInfo<Container::dimension>::faces_per_cell; ++face_number)