From 5b3c7ef1d78b8bebe5070bac8a59679bfef867d7 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 23 Jul 2014 08:06:24 -0500 Subject: [PATCH] Introduce the concept of containers-of-cells and link to it in various places. --- doc/doxygen/headers/glossary.h | 29 ++++++ include/deal.II/distributed/tria.h | 3 +- include/deal.II/dofs/dof_handler.h | 7 +- include/deal.II/grid/grid_tools.h | 144 +++++++++++++++++------------ include/deal.II/grid/tria.h | 3 + include/deal.II/hp/dof_handler.h | 3 +- 6 files changed, 124 insertions(+), 65 deletions(-) diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index 680fd11039..c93bf16232 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -1051,6 +1051,35 @@ Article{BK07, * * * + *
@anchor GlossMeshAsAContainer Meshes as containers
+ *
+ * Meshes can be thought of as arrays of vertices and connectivities, but a + * more fruitful view is to consider them as collections of cells. In C++, + * collections are often called containers (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. + *
+ * + * + * *
@anchor mg_paper %Multigrid paper
*
The "multigrid paper" is a paper by B. Janssen and G. Kanschat, titled * "Adaptive multilevel methods with local smoothing", that diff --git a/include/deal.II/distributed/tria.h b/include/deal.II/distributed/tria.h index 8daa70dd59..f902c7a77b 100644 --- a/include/deal.II/distributed/tria.h +++ b/include/deal.II/distributed/tria.h @@ -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 diff --git a/include/deal.II/dofs/dof_handler.h b/include/deal.II/dofs/dof_handler.h index 7901770fea..e5b155ead0 100644 --- a/include/deal.II/dofs/dof_handler.h +++ b/include/deal.II/dofs/dof_handler.h @@ -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 diff --git a/include/deal.II/grid/grid_tools.h b/include/deal.II/grid/grid_tools.h index d4c1604d43..683506fbf7 100644 --- a/include/deal.II/grid/grid_tools.h +++ b/include/deal.II/grid/grid_tools.h @@ -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 &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 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 std::list 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 Container 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 - * Container - * 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 + template 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 > &matched_pairs, - const dealii::Tensor<1,CONTAINER::space_dimension> &offset = dealii::Tensor<1,CONTAINER::space_dimension>()); + std::vector > &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 + template void collect_periodic_faces - (const CONTAINER &container, + (const Container &container, const types::boundary_id b_id, const int direction, - std::vector > &matched_pairs, - const dealii::Tensor<1,CONTAINER::space_dimension> &offset = dealii::Tensor<1,CONTAINER::space_dimension>()); + std::vector > &matched_pairs, + const dealii::Tensor<1,Container::space_dimension> &offset = dealii::Tensor<1,Container::space_dimension>()); /*@}*/ /** diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h index e1bb6c5b1a..bbfac47794 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -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". + * * *

Structure and iterators

* diff --git a/include/deal.II/hp/dof_handler.h b/include/deal.II/hp/dof_handler.h index b0513deadb..10f0522892 100644 --- a/include/deal.II/hp/dof_handler.h +++ b/include/deal.II/hp/dof_handler.h @@ -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 (spacedim != dim ). -- 2.39.5