From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Tue, 22 Jul 2014 12:54:03 +0000 (-0500)
Subject: Add some documentation.
X-Git-Tag: v8.2.0-rc1~263^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=56442cc6076a2725297461595baba1c4afff5068;p=dealii.git

Add some documentation.
---

diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index 8e670a1283..d4c1604d43 100644
--- 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 e6aca82084..c2ba9e2d4a 100644
--- 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)