]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Introduce the concept of containers-of-cells and link to it in various places. 15/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 23 Jul 2014 13:06:24 +0000 (08:06 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 23 Jul 2014 13:06:24 +0000 (08:06 -0500)
doc/doxygen/headers/glossary.h
include/deal.II/distributed/tria.h
include/deal.II/dofs/dof_handler.h
include/deal.II/grid/grid_tools.h
include/deal.II/grid/tria.h
include/deal.II/hp/dof_handler.h

index 680fd110391876c36e0e7b0ea9c352a43984c24e..c93bf1623296085a6d6ac73e59e04349c5096c5c 100644 (file)
@@ -1051,6 +1051,35 @@ Article{BK07,
  * </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 mg_paper <b>%Multigrid paper</b></dt>
  * <dd>The "multigrid paper" is a paper by B. Janssen and G. Kanschat, titled
  * "Adaptive multilevel methods with local smoothing", that
index 8daa70dd590d0c4e55fba19b8ce745842659ca34..f902c7a77bdd35b674d6c576ed6331cd1dd373ba 100644 (file)
@@ -176,7 +176,8 @@ namespace parallel
      * load-balanced, fully distributed mesh. Use of this class is
      * explained in step-40, step-32, the @ref distributed documentation
      * module, as well as the @ref distributed_paper . See there for more
-     * information.
+     * information. This class satisfies the requirements outlined in
+     * @ref GlossMeshAsAContainer "Meshes as containers".
      *
      * @note This class does not support anisotropic refinement, because
      * it relies on the p4est library that does not support this. Attempts
index 7901770fea118488f9965cb4571773451b945c51..e5b155ead0b001c0606ef99177fa73d09192fced 100644 (file)
@@ -67,10 +67,11 @@ namespace internal
 
 /**
  * Manage the distribution and numbering of the degrees of freedom for
- * non-multigrid algorithms. The purpose of this class is first discussed
- * in the step-2 tutorial program.
+ * non-multigrid algorithms. This class satisfies the requirements outlined in
+ * @ref GlossMeshAsAContainer "Meshes as containers". It is first used in the
+ * step-2 tutorial program.
  *
- * For each vertex, line, quad, etc, we store a list of the indices of degrees
+ * For each vertex, line, quad, etc, this class stores a list of the indices of degrees
  * of freedom living on this object. These indices refer to the unconstrained
  * degrees of freedom, i.e. constrained degrees of freedom are numbered in the
  * same way as unconstrained ones, and are only later eliminated.  This leads
index d4c1604d430d7696a4bf1be4ef576fe637c329b0..683506fbf7e1a386cc790e04992096621d63da0e 100644 (file)
@@ -364,12 +364,13 @@ namespace GridTools
   /**
    * Find and return the number of
    * the used vertex in a given
-   * Container that is located closest
-   * to a given point @p p. The
-   * type of the first parameter
-   * may be either Triangulation,
-   * DoFHandler, hp::DoFHandler, or
-   * MGDoFHandler.
+   * mesh that is located closest
+   * to a given point.
+   *
+   * @param container A variable of a type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param p The point for which we want to find the closest vertex.
+   * @return The index of the closest vertex found.
    *
    * @author Ralf B. Schulz, 2006
    */
@@ -382,10 +383,6 @@ namespace GridTools
    * Find and return a vector of
    * iterators to active cells that
    * surround a given vertex with index @p vertex_index.
-   * The type of the first parameter
-   * may be either Triangulation,
-   * DoFHandler, hp::DoFHandler, or
-   * MGDoFHandler.
    *
    * For locally refined grids, the
    * vertex itself might not be a vertex
@@ -395,6 +392,12 @@ namespace GridTools
    * a hanging node located on a face or an
    * edge of it.
    *
+   * @param container A variable of a type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @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.
+   *
    * @note If the point requested does not lie in any of the cells of
    * the mesh given, then this function throws an exception of type
    * GridTools::ExcPointNotFound. You can catch this exception and
@@ -412,9 +415,7 @@ namespace GridTools
 
   /**
    * Find and return an iterator to the active cell that surrounds a
-   * given point @p ref. The type of the first parameter may be either
-   * Triangulation, or one of the DoF handler classes, i.e. we can find the
-   * cell around a point for iterators into each of these classes.
+   * given point.
    *
    * This is solely a wrapper function for the function of same name
    * below.  A Q1 mapping is used for the boundary, and the iterator
@@ -424,6 +425,12 @@ namespace GridTools
    * it simultaneously delivers the local coordinate of the given
    * point without additional computational cost.
    *
+   * @param container A variable of a type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param p The point for which we want to find the surrounding cell.
+   * @return An iterator into the mesh container that points to the
+   *   surrounding cell.
+   *
    * @note If the point requested does not lie in any of the cells of
    * the mesh given, then this function throws an exception of type
    * GridTools::ExcPointNotFound. You can catch this exception and
@@ -444,10 +451,7 @@ namespace GridTools
 
   /**
    * Find and return an iterator to the active cell that surrounds a
-   * given point @p p. The type of the first parameter may be either
-   * Triangulation, DoFHandler, hp::DoFHandler, or MGDoFHandler, i.e.,
-   * we can find the cell around a point for iterators into each of
-   * these classes.
+   * given point @p p.
    *
    * The algorithm used in this function proceeds by first looking for
    * vertex located closest to the given point, see
@@ -464,13 +468,19 @@ namespace GridTools
    * algorithm tries to identify the cell that is of highest
    * refinement level.
    *
-   * The function returns an iterator to the cell, as well as the
-   * local position of the point inside the unit cell. This local
-   * position might be located slightly outside an actual unit cell,
-   * due to numerical roundoff.  Therefore, the point returned by this
-   * function should be projected onto the unit cell, using
-   * GeometryInfo::project_to_unit_cell.  This is not automatically
-   * performed by the algorithm.
+   * @param mapping The mapping used to determine whether the given
+   *   point is inside a given cell.
+   * @param container A variable of a type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param p The point for which we want to find the surrounding cell.
+   * @return An pair of an iterator into the mesh container that points to the
+   *   surrounding cell, and of the coordinates of that point inside the cell
+   *   in the reference coordinates of that cell. This local
+   *   position might be located slightly outside an actual unit cell,
+   *   due to numerical roundoff.  Therefore, the point returned by this
+   *   function should be projected onto the unit cell, using
+   *   GeometryInfo::project_to_unit_cell().  This is not automatically
+   *   performed by the algorithm.
    *
    * @note If the point requested does not lie in any of the cells of
    * the mesh given, then this function throws an exception of type
@@ -518,7 +528,7 @@ namespace GridTools
                                  const Point<spacedim>     &p);
 
   /**
-   * Return a list of all descendents of
+   * Return a list of all descendants of
    * the given cell that are active. For
    * example, if the current cell is once
    * refined but none of its children are
@@ -530,10 +540,13 @@ namespace GridTools
    * (because the cell has no children that
    * may be active).
    *
-   * Since in C++ the type of the Container
-   * template argument (which can be
-   * Triangulation, DoFHandler,
-   * MGDoFHandler, or hp::DoFHandler) can
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param cell An iterator pointing to a cell of the mesh container.
+   * @return A list of active descendants of the given cell
+   *
+   * @note Since in C++ the type of the Container
+   * template argument can
    * not be deduced from a function call,
    * you will have to specify it after the
    * function name, as for example in
@@ -549,6 +562,11 @@ namespace GridTools
    * Extract the active cells around a given
    * cell @p cell and return them in the
    * vector @p active_neighbors.
+   *
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param cell[in] An iterator pointing to a cell of the mesh container.
+   * @param active_neighbors[out] A list of active descendants of the given cell
    */
   template <class Container>
   void
@@ -787,11 +805,14 @@ namespace GridTools
    *
    * Note that the list of these
    * iterators is not necessarily
-   * order, and does also not
+   * ordered, and does also not
    * necessarily coincide with the
    * order in which cells are
    * traversed in one, or both, of
    * the meshes given as arguments.
+   *
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
    */
   template <typename Container>
   std::list<std::pair<typename Container::cell_iterator,
@@ -830,6 +851,9 @@ namespace GridTools
    * representing triangulations or
    * the classes built on
    * triangulations.
+   *
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
    */
   template <typename Container>
   bool
@@ -950,11 +974,10 @@ namespace GridTools
    * loops over all subfaces of current face adds the neighbors behind these
    * sub-faces to the list to be returned.
    *
-   * The <code>Container</code> template argument can be either a triangulation
-   * or any of the DoF handler classes. Because the C++ language specifies that
-   * the container type can not be inferred from an iterator alone, you will
-   * need to explicitly specify the template argument when calling this
-   * function.
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * @param cell[in] An iterator pointing to a cell of the mesh container.
+   * @return A list of active cells that form the patch around the given cell
    *
    * @note Patches are often used in defining error estimators that require the
    * solution of a local problem on the patch surrounding each of the cells of
@@ -1012,7 +1035,7 @@ namespace GridTools
    * extracted. The function is used in
    * step-38.
    *
-   * It also builds a mapping linking the
+   * The function also builds a mapping linking the
    * cells on the surface mesh to the
    * corresponding faces on the volume
    * one. This mapping is the return value
@@ -1041,26 +1064,21 @@ namespace GridTools
    * you may want to use to determine the
    * location of new vertices.
    *
-   * @note Oftentimes, the
-   * <code>Container</code>
-   * template type will be of kind
-   * Triangulation; in that case,
-   * the map that is returned will
-   * be between Triangulation cell
-   * iterators of the surface mesh
-   * and Triangulation face
+   *
+   * @tparam Container A type that satisfies the
+   * requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   * 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. However, one often needs
-   * to have this mapping between
-   * DoFHandler (or hp::DoFHandler)
-   * iterators. In that case, you
-   * can pass DoFHandler arguments
-   * as first and second parameter;
-   * the function will in that case
+   * mesh container. If the Container argument is
+   * DoFHandler of hp::DoFHandler, then
+   * the function will
    * re-build the triangulation
    * underlying the second argument
    * and return a map between
-   * DoFHandler iterators. However,
+   * appropriate iterators into the Container arguments. However,
    * the function will not actually
    * distribute degrees of freedom
    * on this newly created surface
@@ -1225,6 +1243,9 @@ namespace GridTools
    * them to the corresponding vertices of the 'second' boundary. This can
    * be used to implement conditions such as $u(0,y)=u(1,y+1)$.
    *
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   *
    * @note The created std::vector can be used in
    * DoFTools::make_periodicity_constraints and in
    * parallel::distributed::Triangulation::add_periodicity to enforce
@@ -1237,15 +1258,15 @@ namespace GridTools
    *
    * @author Daniel Arndt, Matthias Maier, 2013
    */
-  template<typename CONTAINER>
+  template <typename Container>
   void
   collect_periodic_faces
-  (const CONTAINER &container,
+  (const Container &container,
    const types::boundary_id b_id1,
    const types::boundary_id b_id2,
    const int                direction,
-   std::vector<PeriodicFacePair<typename CONTAINER::cell_iterator> > &matched_pairs,
-   const dealii::Tensor<1,CONTAINER::space_dimension> &offset = dealii::Tensor<1,CONTAINER::space_dimension>());
+   std::vector<PeriodicFacePair<typename Container::cell_iterator> > &matched_pairs,
+   const dealii::Tensor<1,Container::space_dimension> &offset = dealii::Tensor<1,Container::space_dimension>());
 
 
   /**
@@ -1262,20 +1283,23 @@ namespace GridTools
    * This function will collect periodic face pairs on the coarsest mesh level
    * and add them to @p matched_pairs leaving the original contents intact.
    *
+   * @tparam Container A type that satisfies the
+   *   requirements of a mesh container (see @ref GlossMeshAsAContainer).
+   *
    * @note This version of collect_periodic_face_pairs  will not work on
    * meshes with cells not in @ref GlossFaceOrientation
    * "standard orientation".
    *
    * @author Daniel Arndt, Matthias Maier, 2013
    */
-  template<typename CONTAINER>
+  template <typename Container>
   void
   collect_periodic_faces
-  (const CONTAINER                 &container,
+  (const Container         &container,
    const types::boundary_id b_id,
    const int                direction,
-   std::vector<PeriodicFacePair<typename CONTAINER::cell_iterator> > &matched_pairs,
-   const dealii::Tensor<1,CONTAINER::space_dimension> &offset = dealii::Tensor<1,CONTAINER::space_dimension>());
+   std::vector<PeriodicFacePair<typename Container::cell_iterator> > &matched_pairs,
+   const dealii::Tensor<1,Container::space_dimension> &offset = dealii::Tensor<1,Container::space_dimension>());
 
   /*@}*/
   /**
index e1bb6c5b1afd0feb7281b02d6cce0c3fc7fffea2..bbfac4779437d714f9e98cf92daa7b33033a3455 100644 (file)
@@ -454,6 +454,9 @@ namespace internal
  *  dimension and there only exist specialized versions for distinct
  *  dimensions.
  *
+ *  This class satisfies the requirements outlined in
+ *  @ref GlossMeshAsAContainer "Meshes as containers".
+ *
  *
  *  <h3>Structure and iterators</h3>
  *
index b0513deadb03ac7a8739e0b75939b5a77cf6d991..10f0522892708d54f062b105aeacc89a1c91e664 100644 (file)
@@ -69,7 +69,8 @@ namespace hp
 
   /**
    * Manage the distribution and numbering of the degrees of freedom for
-   * hp-FEM algorithms.
+   * hp-FEM algorithms. This class satisfies the requirements outlined in
+   * @ref GlossMeshAsAContainer "Meshes as containers".
    *
    * This class has not yet been implemented for the use in the codimension
    * one case (<tt>spacedim != dim </tt>).

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.