This moves the discussion completely into concepts.h.
* <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>
* </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
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
* @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
/**
* 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
* 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
* 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.
*
* 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.
* 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.
*
* @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
* (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
*
* 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
* 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())
* 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
* 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,
* 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
* 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
*
* 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
* 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.
*
* 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>
*
*
* 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 ();
/**
* 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
projects / dealii.git / commitdiff