From 03304a1942f275f857796423349d20e216d13c0f Mon Sep 17 00:00:00 2001
From: David Wells <wellsd2@rpi.edu>
Date: Wed, 20 Jan 2016 23:42:46 -0500
Subject: [PATCH] Merge GlossMeshAsAContainer and ConceptMeshType.

This moves the discussion completely into concepts.h.
---
 doc/doxygen/headers/concepts.h        | 62 +++++++++++++++++++++++----
 doc/doxygen/headers/glossary.h        | 28 ------------
 doc/news/changes.h                    |  2 +-
 include/deal.II/distributed/tria.h    |  5 +--
 include/deal.II/dofs/dof_handler.h    |  5 ++-
 include/deal.II/grid/grid_generator.h | 19 ++++----
 include/deal.II/grid/grid_tools.h     | 30 ++++++-------
 include/deal.II/grid/intergrid_map.h  |  2 +-
 include/deal.II/grid/tria.h           |  9 ++--
 include/deal.II/hp/dof_handler.h      |  4 +-
 10 files changed, 90 insertions(+), 76 deletions(-)

diff --git a/doc/doxygen/headers/concepts.h b/doc/doxygen/headers/concepts.h
index 86f13ba994..4488cec3df 100644
--- a/doc/doxygen/headers/concepts.h
+++ b/doc/doxygen/headers/concepts.h
@@ -108,13 +108,36 @@
  * <dt class="concepts">@anchor ConceptMeshType <b>MeshType</b></dt>
  *
  * <dd>
- * There are several algorithms (e.g.,
- * GridTools::find_active_cell_around_point) in deal.II that can operate on
- * either a Triangulation or a DoFHandler, as both classes may be considered
- * to be collections of cells: see the @ref GlossMeshAsAContainer
- * "glossary entry" for a further discussion of this idea. %Functions that may
- * be called with either class indicate this by accepting a template parameter
- * like
+ * Meshes can be thought of as arrays of vertices and connectivities, but a
+ * more fruitful view is to consider them as <i>collections of cells</i>. In
+ * C++, collections are often called <i>containers</i> (typical containers are
+ * std::vector, std::list, etc.) and they are characterized by the ability to
+ * iterate over the elements of the collection. The <tt>MeshType</tt> concept
+ * refers to any container which defines appropriate methods (such as
+ * DoFHandler::begin_active()) and <tt>typedefs</tt> (such as
+ * DoFHandler::active_cell_iterator) for managing collections of cells.
+ *
+ * Triangulation&nnbsp;s, DoFHandler&nnbsp;s, and hp::DoFHandler&nnbsp;s may
+ * all be considered as containers of cells. In fact, the most important parts
+ * of the public interface of these classes consists simply of the ability to
+ * get iterators to their elements. Since these parts of the interface are
+ * generic, i.e., the functions have the same name in all classes, it is
+ * possible to write operations that do not actually care whether they work on
+ * a triangulation or a DoF handler object. Examples abound, for example, in
+ * the GridTools namespace, underlining the power of the abstraction that
+ * meshes and DoF handlers can all be considered simply as collections
+ * (containers) of cells.
+ *
+ * On the other hand, meshes are non-standard containers unlike std::vector or
+ * std::list in that they can be sliced several ways. For example, one can
+ * iterate over the subset of active cells or over all cells; likewise, cells
+ * are organized into levels and one can get iterator ranges for only the
+ * cells on one level. Generally, however, all classes that implement the
+ * containers-of-cells concept use the same function names to provide the same
+ * functionality.
+ *
+ * %Functions that may be called with either class indicate this by accepting
+ * a template parameter like
  * @code
  * template <template <int, int> class MeshType>
  * @endcode
@@ -122,8 +145,29 @@
  * @code
  * template <typename MeshType>
  * @endcode
- * which is usually required to have a <code>typedef</code> named
- * <code>active_cell_iterator</code>.
+ * The classes that satisfy this concept are collectively referred to as
+ * <em>mesh classes</em>. The exact definition of <tt>MeshType</tt> relies a
+ * lot on library internals, but it can be summarized as any class with the
+ * following properties:
+ * <ol>
+ *   <li>A <tt>typedef</tt> named <tt>active_cell_iterator</tt>.
+ *   </li>
+ *   <li>A method <tt>get_triangulation()</tt> which returns a reference to
+ *   the underlying geometrical description (one of the Triangulation classes)
+ *   of the collection of cells. If the mesh happens to be a Triangulation,
+ *   then the mesh just returns a reference to itself.
+ *   </li>
+ *   <li>A method <tt>begin_active()</tt> which returns an iterator pointing
+ *   to the first active cell.
+ *   </li>
+ *   <li>A static member value <tt>dimension</tt> containing the dimension in
+ *       which the object lives.
+ *   </li>
+ *   <li>A static member value <tt>space_dimension</tt> containing the dimension
+ *       of the object (e.g., a 2D surface in a 3D setting would have
+ *       <tt>space_dimension = 2</tt>).
+ *   </li>
+ * </ol>
  * </dd>
  *
  * <dt class="concepts">@anchor ConceptNumber <b>Number</b></dt>
diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index a02db66a2f..59b441aff0 100644
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -1131,34 +1131,6 @@
  * </dd>
  *
  *
- * <dt class="glossary">@anchor GlossMeshAsAContainer <b>Meshes as containers</b></dt>
- * <dd>
- * Meshes can be thought of as arrays of vertices and connectivities, but a
- * more fruitful view is to consider them as <i>collections of cells</i>. In C++,
- * collections are often called <i>containers</i> (typical containers are std::vector,
- * std::list, etc.) and they are characterized by the ability iterate over the
- * elements of the collection.
- *
- * Triangulations and objects of type DoFHandler or hp::DoFHandler can all be
- * considered as containers of cells. In fact, the most important parts of the
- * public interface of these classes consists simply of the ability to get
- * iterators to their elements, using functions such as Triangulation::begin_active(),
- * Triangulation::end() and their counterparts in DoFHandler and hp::DoFHandler. Since
- * these parts of the interface are generic, i.e., the functions have the same name
- * in all classes, it is possible to write operations that do not actually care whether
- * they work on a triangulation or a DoF handler object. Examples about, for example,
- * in the GridTools namespace, underlining the power of the abstraction that meshes
- * and DoF handlers can all be considered simply as collections (containers) of cells.
- *
- * On the other hand, meshes are non-standard containers unlike std::vector or std::list
- * in that they can be sliced several ways. For example, one can iterate over the
- * subset of active cells or over all cells; likewise, cells are organized into levels
- * and one can get iterator ranges for only the cells on one level. Generally, however,
- * all classes that implement the containers-of-cells concept use the same function
- * names to provide the same functionality.
- * </dd>
- *
- *
  * <dt class="glossary">@anchor GlossMPICommunicator <b>MPI Communicator</b></dt>
  * <dd>
  * In the language of the Message Passing Interface (MPI), a communicator
diff --git a/doc/news/changes.h b/doc/news/changes.h
index 571f51156b..468089cf23 100644
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -308,7 +308,7 @@ inconvenience this causes.
   shadow class names. Additionally, template type names are now much more
   consistent across deal.II.
   <br>
-  (David Wells, 2015/10/18 - 2015/12/09)
+  (David Wells, 2015/10/18 - 2016/01/23)
   </li>
 
   <li> New: The WorkStream class's design and implementation are now much
diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h
index adec7a7511..cb45c7eff7 100644
--- a/include/deal.II/distributed/tria.h
+++ b/include/deal.II/distributed/tria.h
@@ -178,9 +178,8 @@ namespace parallel
      * @ref distributed
      * documentation module, as well as the
      * @ref distributed_paper.
-     * See there for more information. This class satisfies the requirements
-     * outlined in
-     * @ref GlossMeshAsAContainer "Meshes as containers".
+     * See there for more information. This class satisfies the
+     * @ref ConceptMeshType "MeshType concept".
      *
      * @note This class does not support anisotropic refinement, because it
      * relies on the p4est library that does not support this. Attempts to
diff --git a/include/deal.II/dofs/dof_handler.h b/include/deal.II/dofs/dof_handler.h
index 7e9466a66c..60310810a8 100644
--- a/include/deal.II/dofs/dof_handler.h
+++ b/include/deal.II/dofs/dof_handler.h
@@ -66,8 +66,9 @@ namespace internal
 
 /**
  * Manage the distribution and numbering of the degrees of freedom for non-
- * multigrid algorithms. This class satisfies the requirements outlined in
- * @ref GlossMeshAsAContainer "Meshes as containers".
+ * multigrid algorithms. This class satisfies the
+ * @ref ConceptMeshType "MeshType concept" requirements.
+ *
  * It is first used in the step-2 tutorial program.
  *
  * For each vertex, line, quad, etc, this class stores a list of the indices
diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h
index 61b4bc3b7c..362666fc88 100644
--- a/include/deal.II/grid/grid_generator.h
+++ b/include/deal.II/grid/grid_generator.h
@@ -970,17 +970,16 @@ namespace GridGenerator
    * boundary object you may want to use to determine the location of new
    * vertices.
    *
+   * @tparam MeshType A type that satisfies the requirements of the
+   * @ref ConceptMeshType "MeshType concept". The map that is returned will be
+   * between cell iterators pointing into the container describing the surface
+   * mesh and face iterators of the volume mesh container. If MeshType is
+   * DoFHandler or hp::DoFHandler, then the function will re-build the
+   * triangulation underlying the second argument and return a map between
+   * appropriate iterators into the MeshType arguments. However, the function
+   * will not actually distribute degrees of freedom on this newly created
+   * surface mesh.
    *
-   * @tparam MeshType A type that satisfies the requirements of a mesh
-   * container (see @ref GlossMeshAsAContainer "meshes as containers").
-   * The map that is returned will be between cell iterators pointing into the
-   * container describing the surface mesh and face iterators of the volume
-   * mesh container. If the MeshType argument is DoFHandler of
-   * hp::DoFHandler, then the function will re-build the triangulation
-   * underlying the second argument and return a map between appropriate
-   * iterators into the MeshType arguments. However, the function will not
-   * actually distribute degrees of freedom on this newly created surface
-   * mesh.
    * @tparam dim The dimension of the cells of the volume mesh. For example, if
    *   dim==2, then the cells are quadrilaterals that either live in the
    *   plane, or form a surface in a higher-dimensional space. The dimension
diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h
index a95ffdf4a5..2ddb7af1c2 100644
--- a/include/deal.II/grid/grid_tools.h
+++ b/include/deal.II/grid/grid_tools.h
@@ -343,7 +343,7 @@ namespace GridTools
    * located closest to a given point.
    *
    * @param mesh A variable of a type that satisfies the requirements of
-   * a mesh container (see @ref GlossMeshAsAContainer).
+   * the @ref ConceptMeshType "MeshType concept".
    * @param p The point for which we want to find the closest vertex.
    * @return The index of the closest vertex found.
    *
@@ -363,7 +363,7 @@ namespace GridTools
    * vertex of a cell or be a hanging node located on a face or an edge of it.
    *
    * @param mesh A variable of a type that satisfies the requirements of
-   * the @ref GlossMeshAsAContainer "MeshType concept".
+   * the @ref ConceptMeshType "MeshType concept".
    * @param vertex_index The index of the vertex for which we try to find
    * adjacent cells.
    * @return A vector of cells that lie adjacent to the given vertex.
@@ -400,7 +400,7 @@ namespace GridTools
    * additional computational cost.
    *
    * @param mesh A variable of a type that satisfies the requirements of
-   * the @ref GlossMeshAsAContainer "MeshType concept".
+   * the @ref ConceptMeshType "MeshType concept".
    * @param p The point for which we want to find the surrounding cell.
    * @return An iterator into the mesh that points to the surrounding cell.
    *
@@ -448,7 +448,7 @@ namespace GridTools
    * @param mapping The mapping used to determine whether the given point is
    * inside a given cell.
    * @param mesh A variable of a type that satisfies the requirements of
-   * the @ref GlossMeshAsAContainer "MeshType concept".
+   * the @ref ConceptMeshType "MeshType concept".
    * @param p The point for which we want to find the surrounding cell.
    * @return An pair of an iterators into the mesh that points to the
    * surrounding cell, and of the coordinates of that point inside the cell in
@@ -520,7 +520,7 @@ namespace GridTools
    * (because the cell has no children that may be active).
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    * @param cell An iterator pointing to a cell of the mesh.
    * @return A list of active descendants of the given cell
    *
@@ -540,7 +540,7 @@ namespace GridTools
    * the vector @p active_neighbors.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    * @param[in] cell An iterator pointing to a cell of the mesh.
    * @param[out] active_neighbors A list of active descendants of the given
    * cell
@@ -588,7 +588,7 @@ namespace GridTools
    * not contain any artificial cells.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    * @param[in] mesh A mesh (i.e. objects of type Triangulation,
    * DoFHandler, or hp::DoFHandler).
    * @param[in] predicate A function  (or object of a type with an operator())
@@ -613,7 +613,7 @@ namespace GridTools
    * this will return all the ghost cells.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    * @param[in] mesh A mesh (i.e. objects of type Triangulation,
    * DoFHandler, or hp::DoFHandler).
    * @return A list of ghost cells
@@ -861,7 +861,7 @@ namespace GridTools
    * traversed in one, or both, of the meshes given as arguments.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    */
   template <typename MeshType>
   std::list<std::pair<typename MeshType::cell_iterator,
@@ -890,7 +890,7 @@ namespace GridTools
    * triangulations or the classes built on triangulations.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    */
   template <typename MeshType>
   bool
@@ -947,10 +947,10 @@ namespace GridTools
    * sub-faces to the list to be returned.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
-   * In C++, The <code>MeshType</code> template argument can not be deduced
-   * from the function call. You need to specify it as an explicit template
-   * argument following the function name.
+   * @ref ConceptMeshType "MeshType concept".
+   * In C++, the compiler can not determine <code>MeshType</code> from the
+   * function call. You need to specify it as an explicit template argument
+   * following the function name.
    * @param[in] cell An iterator pointing to a cell of the mesh.
    * @return A list of active cells that form the patch around the given cell
    *
@@ -1178,7 +1178,7 @@ namespace GridTools
    * PeriodicFacePair collection @p matched_pairs for further use.
    *
    * @tparam MeshType A type that satisfies the requirements of the
-   * @ref GlossMeshAsAContainer "MeshType concept".
+   * @ref ConceptMeshType "MeshType concept".
    *
    * @note The created std::vector can be used in
    * DoFTools::make_periodicity_constraints() and in
diff --git a/include/deal.II/grid/intergrid_map.h b/include/deal.II/grid/intergrid_map.h
index e2cd99c224..332a05635f 100644
--- a/include/deal.II/grid/intergrid_map.h
+++ b/include/deal.II/grid/intergrid_map.h
@@ -67,7 +67,7 @@ DEAL_II_NAMESPACE_OPEN
  * on the first grid will point to cell 1 on the second grid.
  *
  * @tparam MeshType This class may be used with any class that satisfies the
- * @ref GlossMeshAsAContainer "MeshType concept". The extension to other classes
+ * @ref ConceptMeshType "MeshType concept". The extension to other classes
  * offering iterator functions and some minor additional requirements is
  * simple.
  *
diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h
index 922c4039f2..406565e523 100644
--- a/include/deal.II/grid/tria.h
+++ b/include/deal.II/grid/tria.h
@@ -434,9 +434,8 @@ namespace internal
  * dependent of the dimension and there only exist specialized versions for
  * distinct dimensions.
  *
- * This class satisfies the requirements outlined in
- * @ref GlossMeshAsAContainer "Meshes as containers".
- *
+ * This class satisfies the @ref ConceptMeshType "MeshType concept"
+ * requirements.
  *
  * <h3>Structure and iterators</h3>
  *
@@ -2817,8 +2816,8 @@ public:
    *
    * This doesn't seem to be very useful but allows to write code that
    * can access the underlying triangulation for anything that satisfies
-   * the @ref GlossMeshAsAContainer "MeshType as a container" concept (which
-   * may not only be a triangulation, but also a DoFHandler, for example).
+   * the @ref ConceptMeshType "MeshType concept" (which may not only be a
+   * triangulation, but also a DoFHandler, for example).
    */
   Triangulation<dim,spacedim> &
   get_triangulation ();
diff --git a/include/deal.II/hp/dof_handler.h b/include/deal.II/hp/dof_handler.h
index 16abd9f14b..4b2e724d90 100644
--- a/include/deal.II/hp/dof_handler.h
+++ b/include/deal.II/hp/dof_handler.h
@@ -69,8 +69,8 @@ namespace hp
 
   /**
    * Manage the distribution and numbering of the degrees of freedom for hp-
-   * FEM algorithms. This class satisfies the requirements outlined in
-   * @ref GlossMeshAsAContainer "Meshes as containers".
+   * FEM algorithms. This class satisfies the
+   * @ref ConceptMeshType "MeshType concept" requirements.
    *
    * The purpose of this class is to allow for an enumeration of degrees of
    * freedom in the same way as the ::DoFHandler class, but it allows to use a
-- 
2.39.5