/**
- * @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
*/
*
* <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,
* 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.
*
* 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
projects / dealii-svn.git / commitdiff