From 6f85ebab97009b94cae373f0ef34f2b543b84752 Mon Sep 17 00:00:00 2001 From: heltai Date: Sun, 29 Jun 2014 19:45:47 +0000 Subject: [PATCH] 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 --- deal.II/doc/doxygen/headers/boundary.h | 145 +++++++++++++++++-------- deal.II/doc/doxygen/headers/glossary.h | 61 +++++------ 2 files changed, 127 insertions(+), 79 deletions(-) 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: * * - * In the context of triangulations, each face of a cell that is located at - * the boundary of the domain stores a number called boundary_id 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 manifold_id, and each face of a cell that is + * located at the boundary of the domain stores a number called + * boundary_id 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 @@ * *
@anchor GlossBoundaryIndicator %Boundary indicator
* - *
- * 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. + *
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 -- 2.39.5