From: heltai <heltai@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Sun, 29 Jun 2014 19:45:47 +0000 (+0000)
Subject: Fixed some comments for boundary ids and manifold ids.
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6f85ebab97009b94cae373f0ef34f2b543b84752;p=dealii-svn.git

Fixed some comments for boundary ids and manifold ids.

git-svn-id: https://svn.dealii.org/branches/branch_manifold_id_intermediate@33098 0785d39b-7218-0410-832d-ea1e28bc413d
---

diff --git a/deal.II/doc/doxygen/headers/boundary.h b/deal.II/doc/doxygen/headers/boundary.h
index adfe76abf7..e930b2bdfa 100644
--- a/deal.II/doc/doxygen/headers/boundary.h
+++ b/deal.II/doc/doxygen/headers/boundary.h
@@ -16,66 +16,117 @@
 
 
 /**
- * @defgroup boundary Boundary description for triangulations
+ * @defgroup boundary Boundary and Manifold description for triangulations
  *
  * The classes in this module are concerned with the description of the
- * boundary of a domain in which a Triangulation lives. This boundary
+ * geometry of a domain in which a Triangulation lives. This geometry
  * description is necessary in three contexts:
  * <ul>
  *
- *   <li> Mesh refinement: Whenever a cell at the boundary is refined, it is
- *   necessary to introduce at least one new vertex on the boundary. In the
- *   simplest case, one assumes that the boundary consists of straight line
- *   segments (in 2d) or a bilinear surface (in 3d) between the vertices of
- *   the original, coarsest mesh, and the next vertex is simply put into the
- *   middle of the old ones. This is the default behavior of the Triangulation
- *   class, and is described by the StraightBoundary class.
+ *   <li> Mesh refinement: Whenever a cell is refined, it is necessary
+ *   to introduce at least one new vertex. In the simplest case, one
+ *   assumes that the cells and their faces consists of straight line
+ *   segments, bilinear surface or trilinear volumes between the
+ *   vertices of the original, coarsest mesh, and the next vertex is
+ *   simply put into the middle of the old ones. This is the default
+ *   behavior of the Triangulation class, and is described by the
+ *   StraightBoundary and FlatManifold classes.
  *
- *   On the other hand, if one deals with curved boundaries, this is not the
- *   appropriate thing to do. The classes derived from the Boundary base class
- *   therefore describe the geometry of a domain. One can then attach an
- *   object of a class derived from this base class to the Triangulation
- *   object using the Triangulation::set_boundary() function, and the
- *   Triangulation will ask the boundary object where a new vertex should be
- *   located upon mesh refinement. Several classes already exist to support
- *   the most common geometries, e.g., CylinderBoundary, HyperBallBoundary, or
- *   HyperShellBoundary.
+ *   On the other hand, if one deals with curved geometries and
+ *   boundaries, this is not the appropriate thing to do. The classes
+ *   derived from the Manifold and Boundary base classes describe the
+ *   geometry of a domain. One can then attach an object of a class
+ *   derived from this base classes to the Triangulation object using
+ *   the Triangulation::set_boundary() (the old, deprecated function)
+ *   or Triangulation::set_manifold() functions, and the Triangulation
+ *   will ask the manifold object where a new vertex should be located
+ *   upon mesh refinement. Several classes already exist to support
+ *   the boundary of the most common geometries, e.g.,
+ *   CylinderBoundary, HyperBallBoundary, or HyperShellBoundary. 
  *
- *   <li> Integration: When using higher order finite element methods, it is
- *   often necessary to compute cell terms (like cell contributions to the
- *   matrix and right hand side of the linear system) using curved
- *   approximations of the boundary, rather than the straight line
- *   approximation. The actual implementation of such curved elements happens
- *   in the Mapping class (see the @ref mapping module), which however obtains
- *   its information about the boundary of the domain from the classes
- *   described here. The same is, of course, true when integrating boundary
- *   terms (e.g., inhomogenous Neumann boundary conditions).
+ *   <li> Integration: When using higher order finite element methods,
+ *   it is often necessary to compute cell terms (like cell
+ *   contributions to the matrix and right hand side of the linear
+ *   system) using curved approximations of the geometry, rather than
+ *   the straight line approximation. The actual implementation of
+ *   such curved elements happens in the Mapping class (see the @ref
+ *   mapping module), which however obtains its information about the
+ *   manifold description from the classes described here. The same
+ *   is, of course, true when integrating boundary terms (e.g.,
+ *   inhomogenous Neumann boundary conditions).
+ *
+ *   <li> In cases where a Triangulation is embedded into a higher
+ *   dimensional space, i.e., whenever the second template argument of
+ *   the Triangulation class is explicitly specified and larger than
+ *   the first (for an example, see step-34), the manifold description
+ *   objects serve as a tool to describe the geometry not only of the
+ *   boundary of the domain but of the domain itself, in case the
+ *   domain is a manifold that is in fact curved. In these cases, one
+ *   can use the Triangulation::set_manifold() function to indicate
+ *   what manifold description to use when refining the curve, or when
+ *   computing integrals using high order mappings.
  *
- *   <li> In cases where a Triangulation is embedded into a higher dimensional
- *   space, i.e., whenever the second template argument of the Triangulation
- *   class is explicitly specified and larger than the first (for an example,
- *   see step-34), the boundary description objects also serve as a tool to
- *   describe the geometry not only of the boundary of the domain but of the
- *   domain itself, in case the domain is a manifold that is in fact curved.
  * </ul>
  *
- * In the context of triangulations, each face of a cell that is located at
- * the boundary of the domain stores a number called <tt>boundary_id</tt> that
- * uniquely identifies which part of the boundary this face is on. If nothing
- * is specified at creation time, each boundary face has a zero boundary
- * id. On the other hand, the boundary id of faces can be set either at
- * creation time or later by looping over all cells and querying their faces.
+ * In the context of triangulations, each object stores a number
+ * called <tt>manifold_id</tt>, and each face of a cell that is
+ * located at the boundary of the domain stores a number called
+ * <tt>boundary_id</tt> that uniquely identifies which part of the
+ * boundary this face is on. If nothing is specified at creation time,
+ * each boundary face has a zero boundary id and each triangulation
+ * object has an invalid manifold id. On the other hand, the boundary
+ * id of faces and the manifold id of objects can be set either at
+ * creation time or later by looping over all cells and querying their
+ * faces.
+ *
+ * It is then possible to associate objects describing the geometry to
+ * certain boundary_id values used in a triangulation and to certain
+ * manifold_id values.
+ *
+ * Befor version 8.2, the library allowed only boundary faces to
+ * follow a curved geometrical description. Since version 8.2 this has
+ * been introduced also for interior faces and cells, and the
+ * boundary_id has been separated from the manifold_id.
+ *
+ * Although the old behavior is still supported, one should use the
+ * boundary indicator only for the physical meaning associated, for
+ * example, to boundary conditions, and revert to manifold_ids to
+ * describe the geometry of the triangulation.
+ *
+ * The behavior of the Triangulation class w.r.t. geometry
+ * descriptions is the following: Triangulation::set_boundary() and
+ * Triangulation::set_manifold() do the exact same thing: they attach
+ * a manifold descriptor to the specified id. The first function is
+ * maintained for backward compatibility, but will be deprecated in
+ * future releases.
+ *
+ * Whenever a new vertex is needed in a object that supports
+ * geometrical dependent refinement (i.e., a face on the boundary, an
+ * interior face, or a cell in codimension one), the Triangulation
+ * queries to manifold_id of the object which needs refinement. If the
+ * manifold_id is set to numbers::invalid_manifold_id, then the
+ * Triangulation queries the boundary_id (if the face is on the
+ * boundary) or the material_id (if the Triangulation is of
+ * codimension one and the object is a cell). If the previous queries
+ * resulted in a number different from numbers::invalid_manifold_id,
+ * then the Triangulation looks wether a previous call to
+ * Triangulation::set_manifold() (or set_boundary()) was performed
+ * with the given id, and if yes, it uses the stored object to obtain
+ * new vertices, otherwise it uses a FlatManifold or StraightBoundary
+ * object.
  *
- * It is then possible to associate objects describing the boundary to certain
- * boundary_id values used in a triangulation. Note that this is not
- * necessary: in some cases one may want to use the default straight boundary
- * approximation, and use non-zero boundary indicators for completely
- * different purposes, for example to indicate that a part of the boundary has
- * a different kind of boundary condition in the partial differential
- * equation.
+ * The given behavior is backward compatible. If one ignores the
+ * manifold_id of an object, by default this is set to
+ * numbers::invalid_manifold_id, and the first query will trigger a
+ * query to the old style boundary_id. This behavior will be
+ * maintained for a while, but might eventually be changed. The
+ * suggested strategy is to use manifold_ids to describe the geometry,
+ * and boundary_ids to describe boundary conditions. 
+ * 
  *
  * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
+ * @see @ref GlossManifoldIndicator "Glossary entry on manifold indicators"
  *
  * @ingroup grid
- * @author Wolfgang Bangerth, 1998-2006
+ * @author Wolfgang Bangerth, Luca Heltai, 1998-2014
  */
diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h
index 0c1478f680..8e11889651 100644
--- a/deal.II/doc/doxygen/headers/glossary.h
+++ b/deal.II/doc/doxygen/headers/glossary.h
@@ -307,14 +307,12 @@
  *
  * <dt class="glossary">@anchor GlossBoundaryIndicator <b>%Boundary indicator</b></dt>
  *
- * <dd>
- * In a Triangulation object, every part of the boundary is associated with
- * a unique number (of type types::boundary_id) that is used to identify which
- * boundary geometry object is responsible to generate new points when the mesh
- * is refined. By convention, this boundary indicator is also often used to
- * determine what kinds of boundary conditions are to be applied to a particular
- * part of a boundary. The boundary is composed of the faces of the cells and, in 3d,
- * the edges of these faces.
+ * <dd> In a Triangulation object, every part of the boundary may be
+ * associated with a unique number (of type types::boundary_id) that
+ * is used to determine what kinds of boundary conditions are to be
+ * applied to a particular part of a boundary. The boundary is
+ * composed of the faces of the cells and, in 3d, the edges of these
+ * faces.
  *
  * By default, all boundary indicators of a mesh are zero, unless you are
  * reading from a mesh file that specifically sets them to something different,
@@ -338,22 +336,29 @@
  * on each of the selected faces. To query the boundary indicator of a particular
  * face or edge, use TriaAccessor::boundary_indicator.
  *
- * The code above only sets the boundary indicators of a particular part
- * of the boundary, but it does not by itself change the way the Triangulation
- * class treats this boundary for the purposes of mesh refinement. For this,
- * you need to call Triangulation::set_boundary to associate a boundary
- * object with a particular boundary indicator. This allows the Triangulation
- * object to use a different method of finding new points on faces and edges
- * to be refined; the default is to use a StraightBoundary object for all
- * faces and edges. The results section of step-49 has a worked example that
- * shows all of this in action.
- *
- * The second use of boundary indicators is to describe not only which geometry
- * object to use on a particular boundary but to select a part of the boundary
- * for particular boundary conditions. To this end, many of the functions in
- * namespaces DoFTools and VectorTools take arguments that specify which part of
- * the boundary to work on. Examples are DoFTools::make_periodicity_constraints,
- * DoFTools::extract_boundary_dofs, DoFTools::make_zero_boundary_constraints and
+ * In older versions of the library (prior to 8.2), if you wanted also
+ * to change the way the Triangulation class treated the boundary for
+ * the purposes of mesh refinement, you could call
+ * Triangulation::set_boundary to associate a boundary object with a
+ * particular boundary indicator. This method is still supported, and
+ * it allows the Triangulation object to use a different method of
+ * finding new points on faces and edges to be refined; the default is
+ * to use a StraightBoundary object for all faces and edges. The
+ * results section of step-49 has a worked example that shows all of
+ * this in action.
+ *
+ * The suggested method from version 8.2 onwards, is to split the
+ * geometrical description of the boundary from its physical meaning,
+ * by using separately manifold_ids and boundary_ids. The former are
+ * used to describe how the geometry changes, and the latter are used
+ * to identify the boundary conditions.
+ *
+ * Many of the functions in namespaces DoFTools and VectorTools take
+ * arguments that specify which part of the boundary to work on, and
+ * they specifically refer to boundary_ids. Examples are
+ * DoFTools::make_periodicity_constraints,
+ * DoFTools::extract_boundary_dofs,
+ * DoFTools::make_zero_boundary_constraints and
  * VectorTools::interpolate_boundary_values,
  * VectorTools::compute_no_normal_flux_constraints.
  *
@@ -362,14 +367,6 @@
  * indicators is also presented in a section of the documentation of the
  * Triangulation class.
  *
- * @note For meshes embedded in a higher dimension (i.e., for which the
- * 'dim' template argument to the Triangulation class is less than the
- * 'spacedim' argument -- sometimes called the 'codimension one' or 'codimension
- * two' case), the Triangulation also stores boundary indicators for cells, not just
- * faces and edges. In this case, the boundary object associated with a particular
- * boundary indicator is also used to move the new center points of cells back
- * onto the manifold that the triangulation describes whenever a cell is refined.
- *
  * @note For parallel triangulations of type parallel::distributed::Triangulation,
  * it is not enough to set boundary indicators only once at the beginning. See
  * the long discussion on this topic in the class documentation of