]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Merge GlossMeshAsAContainer and ConceptMeshType. 2093/head
authorDavid Wells <wellsd2@rpi.edu>
Thu, 21 Jan 2016 04:42:46 +0000 (23:42 -0500)
committerDavid Wells <wellsd2@rpi.edu>
Sat, 23 Jan 2016 19:12:41 +0000 (14:12 -0500)
This moves the discussion completely into concepts.h.

doc/doxygen/headers/concepts.h
doc/doxygen/headers/glossary.h
doc/news/changes.h
include/deal.II/distributed/tria.h
include/deal.II/dofs/dof_handler.h
include/deal.II/grid/grid_generator.h
include/deal.II/grid/grid_tools.h
include/deal.II/grid/intergrid_map.h
include/deal.II/grid/tria.h
include/deal.II/hp/dof_handler.h

index 86f13ba994312f2219a429147a9eb9358fcd7096..4488cec3df38af6ac81dbe53c5720cb374e421e9 100644 (file)
  * <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
  * @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>
index a02db66a2fd6c899010e6e5796fbb46df310d0aa..59b441aff0817b428eb1b1c7900b43477a476f83 100644 (file)
  * </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
index 571f51156b47dd4a20a8d18980860f3a622f6103..468089cf230ead913ef9e29501d9b76d5ed27082 100644 (file)
@@ -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
index adec7a751181d410717d99dd4ac2d69d37206021..cb45c7eff75cc24a5b5e63a5d5df9c7aca22f1a9 100644 (file)
@@ -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
index 7e9466a66c4df8aa1394aeec2a01ae8e44057d2b..60310810a8fe41e425d469dcfdb2e01d7241d1b5 100644 (file)
@@ -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
index 61b4bc3b7c30d896e12b7aaed9cbc9fdc22d70ce..362666fc884fe724f6ac3ce3916bdc87ca757971 100644 (file)
@@ -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
index a95ffdf4a5e5f9bd58ec2a9fa2bb3b7cb986c16a..2ddb7af1c28f3e3d7c90ba2d9dfddce20e4c17ec 100644 (file)
@@ -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
index e2cd99c224d56d878a21ec9531615fab7da7e1f1..332a05635fe4b6f5d8e9c62f14e31e5f218a21af 100644 (file)
@@ -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.
  *
index 922c4039f208079f88db0271c3a5a4b8cebb2ced..406565e5235daf59ec9ec340df22647408e2294e 100644 (file)
@@ -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 ();
index 16abd9f14ba6c53abd3f592d2804691e15934aa9..4b2e724d903878a9475ad8d3dd39afc69c8eb434 100644 (file)
@@ -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

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.