]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Move a good amount of documentation about the reference cell from Triangulation to...
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Thu, 26 Jan 2006 03:43:12 +0000 (03:43 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Thu, 26 Jan 2006 03:43:12 +0000 (03:43 +0000)
git-svn-id: https://svn.dealii.org/trunk@12170 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/base/include/base/geometry_info.h
deal.II/deal.II/include/grid/tria.h

index 21a30b69b241ca5a88225cb8fe6c97a26f8437e2..9d390439b9971b5e2609d28b4f93f1de9bdede1a 100644 (file)
@@ -113,12 +113,414 @@ struct GeometryInfo<0>
 
 
 /**
- * This template specifies the interface to all topological structure
- * of the mesh cells.
+ * This class provides dimension independent information to all topological
+ * structures that make up the unit, or
+ * @ref GlossReferenceCell "reference cell".
  *
- * The information of this class is used extensively in the geometric
- * description of Triangulation objects, as well as in various other
- * parts of the code.
+ * It is the one central point in the library where information about the
+ * numbering of vertices, lines, or faces of the reference cell is
+ * collected. Consequently, the information of this class is used extensively
+ * in the geometric description of Triangulation objects, as well as in
+ * various other parts of the code. In particular, it also serves as the focus
+ * of writing code in a dimension independent way; for example, instead of
+ * writing a loop over vertices 0<=v<4 in 2d, one would write it as
+ * 0<=v<GeometryInfo<dim>::vertices_per_cell, thus allowing the code to work
+ * in 3d as well without changes.
+ *
+ * The most frequently used parts of the class are its static members like
+ * vertices_per_cell, faces_per_cell, etc. However, the class also offers
+ * information about more abstract questions like the orientation of faces,
+ * etc. The following documentation gives a textual description of many of
+ * these concepts.
+ *
+ *
+ * <h3>Implementation conventions for two spatial dimensions</h3>
+ * 
+ * From version 5.2 onwards deal.II is based on a numbering scheme
+ * that uses a lexicographic ordering (with x running fastest)
+ * wherever possible, hence trying to adopt a kind of 'canonical'
+ * ordering.
+ *
+ * The ordering of vertices and faces (lines) in 2d is defined by
+ *
+ * N1) vertices are numbered in lexicographically
+ *
+ * N2) faces (lines in 2d): first the two faces with normals in x-
+ * and then y-direction. For each two faces: first the face with
+ * normal in negative coordinate direction, then the one with normal
+ * in positive direction, i.e. the faces are ordered according to
+ * their normals pointing in -x, x, -y, y direction.
+ *
+ * N3) the direction of a line is represented by the direction of
+ * point 0 towards point 1 and is always in one of the coordinate
+ * directions
+ * 
+ * N4/ face lines in 3d are ordered, such that the induced 2d local
+ * coordinate system (x,y) implies (right hand rule) a normal in
+ * face normal direction, see N2/.
+ *
+ * The resulting numbering of vertices and faces (lines) in 2d as
+ * well as the directions of lines is shown in the following.
+ * @verbatim
+ *       3
+ *    2-->--3
+ *    |     |
+ *   0^     ^1
+ *    |     |
+ *    0-->--1
+ *        2
+ * @endverbatim
+ * 
+ * Note that the orientation of lines has to be correct upon construction of a
+ * grid; however, it is automatically preserved upon refinement.
+ *
+ * Further we define that child lines have the same direction as their parent,
+ * i.e. that <tt>line->child(0)->vertex(0)==line->vertex(0)</tt> and
+ * <tt>line->child(1)->vertex(1)==line->vertex(1)</tt>. This also implies,
+ * that the first sub-line (<tt>line->child(0)</tt>) is the one at vertex(0)
+ * of the old line.
+ *
+ * Similarly we define, that the four children of a quad are adjacent to the
+ * vertex with the same number of the old quad.
+ *
+ * Note that information about several of these conventions can be
+ * extracted at run- or compile-time from the member functions and
+ * variables of the present class.
+ *
+ *
+ * <h4>Coordinate systems</h4>
+ *
+ * When explicit coordinates are required for points in a cell (e.g for
+ * quadrature formulae or the point of definition of trial functions), we
+ * define the following coordinate system for the unit cell:
+ * @verbatim
+ *  y^   2-----3
+ *   |   |     |
+ *   |   |     |
+ *   |   |     |
+ *   |   0-----1
+ *   *------------>x
+ * @endverbatim
+ * 
+ * Here, vertex 0 is the origin of the coordinate system, vertex 1 has
+ * coordinates <tt>(1,0)</tt>, vertex 2 at <tt>(0,1)</tt> and vertex 3 at
+ * <tt>(1,1)</tt>. The GeometryInfo<dim>::unit_cell_vertex() function can be
+ * used to query this information at run-time.
+ *
+ *
+ * <h3>Implementation conventions for three spatial dimensions</h3>
+ *
+ * By convention, we will use the following numbering conventions
+ * for vertices, lines and faces of hexahedra in three space
+ * dimensions. Before giving these conventions we declare the
+ * following sketch to be the standard way of drawing 3d pictures of
+ * hexahedra:
+ * @verbatim
+ *                       *-------*        *-------*
+ *                      /|       |       /       /|
+ *                     / |       |      /       / |
+ *  z                 /  |       |     /       /  |
+ *  ^                *   |       |    *-------*   |
+ *  |   ^y           |   *-------*    |       |   *
+ *  |  /             |  /       /     |       |  /
+ *  | /              | /       /      |       | /
+ *  |/               |/       /       |       |/
+ *  *------>x        *-------*        *-------*
+ * @endverbatim
+ * The left part of the picture shows the left, bottom and back face of the
+ * cube, while the right one shall be the top, right and front face. You may
+ * recover the whole cube by moving the two parts together into one.
+ *
+ * Note again that information about several of the following
+ * conventions can be extracted at run- or compile-time from the
+ * member functions and variables of the present class.
+ *
+ * <h4>Vertices</h4>
+ *  
+ * The ordering of vertices in 3d is defined by the same rules as in
+ * the 2d case, i.e.
+ *
+ * N1) vertices are numbered in lexicographic ordering.
+ *
+ * Hence, the vertices are numbered as follows   
+ * @verbatim
+ *       6-------7        6-------7
+ *      /|       |       /       /|
+ *     / |       |      /       / |
+ *    /  |       |     /       /  |
+ *   4   |       |    4-------5   |
+ *   |   2-------3    |       |   3
+ *   |  /       /     |       |  /
+ *   | /       /      |       | /
+ *   |/       /       |       |/
+ *   0-------1        0-------1
+ * @endverbatim
+ * 
+ * We note, that first the vertices on the bottom face (z=0) are numbered
+ * exactly the same way as are the vertices on a quadrilateral. Then the
+ * vertices on the top face (z=1) are numbered similarly by moving the bottom
+ * face to the top. Again, the GeometryInfo<dim>::unit_cell_vertex() function
+ * can be used to query this information at run-time.
+ *
+ * 
+ * <h4>Lines</h4>
+ *
+ * Here, the same holds as for the vertices:
+ *
+ * N4) line ordering in 3d:
+ * <ul>
+ *   <li>first the lines of face (z=0) in 2d line ordering,
+ *   <li>then the lines of face (z=1) in 2d line ordering,
+ *   <li>finally the lines in z direction in lexicographic ordering
+ * </ul>
+ * @verbatim
+ *       *---7---*        *---7---*
+ *      /|       |       /       /|
+ *     4 |       11     4       5 11
+ *    /  10      |     /       /  |
+ *   *   |       |    *---6---*   |
+ *   |   *---3---*    |       |   *
+ *   |  /       /     |       9  /
+ *   8 0       1      8       | 1
+ *   |/       /       |       |/
+ *   *---2---*        *---2---*
+ * @endverbatim
+ * As in 2d lines are directed in coordinate directions, see N3.
+ * @verbatim
+ *       *--->---*        *--->---*
+ *      /|       |       /       /|
+ *     ^ |       ^      ^       ^ ^
+ *    /  ^       |     /       /  |
+ *   *   |       |    *--->---*   |
+ *   |   *--->---*    |       |   *
+ *   |  /       /     |       ^  /
+ *   ^ ^       ^      ^       | ^
+ *   |/       /       |       |/
+ *   *--->---*        *--->---*
+ * @endverbatim
+ *
+ * The fact that edges (just as vertices and faces) are entities
+ * that are stored in their own right rather than constructed from
+ * cells each time they are needed, means that adjacent cells
+ * actually have pointers to edges that are thus shared between
+ * them. This implies that the convention that sets of parallel
+ * edges have parallel directions is not only a local
+ * condition. Before a list of cells is passed to an object of this
+ * class for creation of a triangulation, you therefore have to make
+ * sure that cells are oriented in a compatible fashion, so that
+ * edge directions are globally according to above
+ * convention. However, the GridReordering class can do this
+ * for you, by reorienting cells and edges of an arbitrary list of
+ * input cells that need not be already sorted.
+ * 
+ * <h4>Faces</h4>
+ *
+ * The numbering of faces in 3d is defined by a rule analogous to 2d:
+ *
+ * N2a) faces (quads in 3d): first the two faces with normals in x-,
+ * then y- and z-direction. For each two faces: first the face with
+ * normal in negative coordinate direction, then the one with normal
+ * in positive direction, i.e. the faces are ordered according to
+ * their normals pointing in -x, x, -y, y, -z, z direction.
+ *
+ * Therefore, the faces are numbered in the ordering: left, right,
+ * front, back, bottom and top face:
+ * @verbatim
+ *       *-------*        *-------*
+ *      /|       |       /       /|
+ *     / |   3   |      /   5   / |
+ *    /  |       |     /       /  |
+ *   *   |       |    *-------*   |
+ *   | 0 *-------*    |       | 1 *
+ *   |  /       /     |       |  /
+ *   | /   4   /      |   2   | /
+ *   |/       /       |       |/
+ *   *-------*        *-------*
+ * @endverbatim
+ *
+ * The <em>standard</em> direction of the faces is such, that the
+ * induced 2d local coordinate system (x,y) implies (right hand
+ * rule) a normal in face normal direction, see N2a).  In the
+ * following we show the local coordinate system and the numbering
+ * of face lines:
+ * <ul>
+ * <li> Faces 0 and 1:
+ *  @verbatim
+ *          Face 0           Face 1
+ *        *-------*        *-------*
+ *       /|       |       /       /|
+ *      3 1       |      /       3 1
+ *    y/  |       |     /      y/  |
+ *    *   |x      |    *-------*   |x
+ *    |   *-------*    |       |   *
+ *    0  /       /     |       0  /
+ *    | 2       /      |       | 2
+ *    |/       /       |       |/
+ *    *-------*        *-------*
+ *  @endverbatim
+ * 
+ * <li> Faces 2 and 3:
+ *  @verbatim
+ *        x Face 3           Face 2
+ *        *---1---*        *-------*
+ *       /|       |       /       /|
+ *      / |       3      /       / |
+ *     /  2       |    x/       /  |
+ *    *   |       |    *---1---*   |
+ *    |   *---0---*y   |       |   *
+ *    |  /       /     |       3  /
+ *    | /       /      2       | /
+ *    |/       /       |       |/
+ *    *-------*        *---0---*y
+ *  @endverbatim 
+ * 
+ * <li> Faces 4 and 5:
+ *  @verbatim
+ *          Face 4         y Face 5
+ *        *-------*        *---3---*
+ *       /|       |       /       /|
+ *      / |       |      0       1 |
+ *     /  |       |     /       /  |
+ *    *   |y      |    *---2---* x |
+ *    |   *---3---*    |       |   *
+ *    |  /       /     |       |  /
+ *    | 0       1      |       | /
+ *    |/       /       |       |/
+ *    *---2---* x      *-------*
+ *  @endverbatim
+ * </ul>
+ *
+ * The face line numbers (0,1,2,3) correspond to following cell line
+ * numbers.
+ * <ul>
+ * <li> Face 0: lines 8, 10, 0, 4;
+ * <li> Face 1: lines 9, 11, 1, 5;
+ * <li> Face 2: lines 2, 6, 8, 9;
+ * <li> Face 3: lines 3, 7, 10, 11;
+ * <li> Face 4: lines 0, 1, 2, 3;
+ * <li> Face 5: lines 4, 5, 6, 7;
+ * </ul>
+ * You can get these numbers using the
+ * GeometryInfo<3>::face_to_cell_lines() function.
+ *
+ * The face normals can be deduced from the face orientation by
+ * applying the right hand side rule (x,y -> normal).  We note, that
+ * in the standard orientation of faces in 2d, faces 0 and 2 have
+ * normals that point into the cell, and faces 1 and 3 have normals
+ * pointing outward. In 3d, faces 0, 2, and 4
+ * have normals that point into the cell, while the normals of faces
+ * 1, 3, and 5 point outward. This information, again, can be queried from
+ * GeometryInfo<dim>::unit_normal_orientation.
+ *
+ * However, it turns out that a significant number of 3d meshes cannot
+ * satisfy this convention. This is due to the fact that the face
+ * convention for one cell already implies something for the
+ * neighbor, since they share a common face and fixing it for the
+ * first cell also fixes the normal vectors of the opposite faces of
+ * both cells. It is easy to construct cases of loops of cells for
+ * which this leads to cases where we cannot find orientations for
+ * all faces that are consistent with this convention.
+ *
+ * For this reason, above convention is only what we call the <em>standard
+ * orientation</em>. deal.II actually allows faces in 3d to have either the
+ * standard direction, or its opposite, in which case the lines that make up a
+ * cell would have reverted orders, and the above line equivalences would not
+ * hold any more. You can ask a cell whether a given face has standard
+ * orientation by calling <tt>cell->face_orientation(face_no)</tt>: if the
+ * result is @p true, then the face has standard orientation, otherwise its
+ * normal vector is pointing the other direction. There are not very many
+ * places in application programs where you need this information actually,
+ * but a few places in the library make use of this. Note that in 2d, the
+ * result is always @p true. More information on the topic can be found in the
+ * @ref GlossFaceOrientation "glossary" article on this topic.
+ *
+ *
+ * <h4>Children</h4>
+ *
+ * The eight children of a cell are numbered according to the vertices they
+ * are adjacent to:
+ * @verbatim
+ *       *-------*        *-------*
+ *      /| 6   7 |       / 6   7 /|
+ *     /6|       |      /       /7|
+ *    /  |       |     / 4   5 /  |
+ *   *   | 2   3 |    *-------*5 3|
+ *   |4 2*-------*    | 4   5 |   *
+ *   |  / 2   3 /     |       |  /
+ *   |0/       /      |       |1/
+ *   |/0    1 /       | 0   1 |/
+ *   *-------*        *-------*
+ * @endverbatim
+ *
+ * Taking into account the orientation of the faces, the following
+ * children are adjacent to the respective faces:
+ * <ul>
+ * <li> Face 0: children 0, 2, 4, 6;
+ * <li> Face 1: children 1, 3, 5, 7;
+ * <li> Face 2: children 0, 4, 1, 5;
+ * <li> Face 3: children 2, 6, 3, 7;
+ * <li> Face 4: children 0, 1, 2, 3;
+ * <li> Face 5: children 4, 5, 6, 7.
+ * </ul>
+ * You can get these numbers using the
+ * GeometryInfo<3>::child_cell_on_face() function. As each child is
+ * adjacent to the vertex with the same number these numbers are
+ * also given by the GeometryInfo<3>::face_to_cell_vertices()
+ * function.
+ *
+ * Note that, again, the above list only holds for faces in their
+ * standard orientation. If a face is not in standard orientation,
+ * then the children at positions 1 and 2 (counting from 0 to 3)
+ * would be swapped. In fact, this is what the child_cell_on_face
+ * and the face_to_cell_vertices functions of GeometryInfo<3> do,
+ * when invoked with a <tt>face_orientation=false</tt> argument.
+ *
+ * The information which child cell is at which position of which
+ * face is most often used when computing jump terms across faces
+ * with hanging nodes, using objects of type
+ * FESubfaceValues. Sitting on one cell, you would look at face and
+ * figure out which child of the neighbor is sitting on a given
+ * subface between the present and the neighboring cell. To avoid
+ * having to query the standard orientation of the faces of the two
+ * cells every time in such cases, you should use a function call
+ * like
+ * <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>,
+ * which returns the correct result both in 2d (where face
+ * orientations are immaterial) and 3d (where it is necessary to use
+ * the face orientation as additional argument to
+ * <tt>GeometryInfo<3>::child_cell_on_face</tt>).
+ *
+ * <h4>Coordinate systems</h4>
+ *
+ * We define the following coordinate system for the explicit coordinates of
+ * the vertices of the unit cell:
+ * @verbatim
+ *                       6-------7        6-------7
+ *                      /|       |       /       /|
+ *                     / |       |      /       / |
+ *  z                 /  |       |     /       /  |
+ *  ^                4   |       |    4-------5   |
+ *  |   ^y           |   2-------3    |       |   3
+ *  |  /             |  /       /     |       |  /
+ *  | /              | /       /      |       | /
+ *  |/               |/       /       |       |/
+ *  *------>x        0-------1        0-------1
+ * @endverbatim
+ *
+ * By the convention laid down as above, the vertices have the following
+ * coordinates (lexicographic, with x running fastest):
+ * <ul>
+ *    <li> Vertex 0: <tt>(0,0,0)</tt>;
+ *    <li> Vertex 1: <tt>(1,0,0)</tt>;
+ *    <li> Vertex 2: <tt>(0,1,0)</tt>;
+ *    <li> Vertex 3: <tt>(1,1,0)</tt>;
+ *    <li> Vertex 4: <tt>(0,0,1)</tt>;
+ *    <li> Vertex 5: <tt>(1,0,1)</tt>;
+ *    <li> Vertex 6: <tt>(0,1,1)</tt>;
+ *    <li> Vertex 7: <tt>(1,1,1)</tt>.
+ * </ul>
+ *
+ * 
  *
  * @note Instantiations for this template are provided for dimensions 1,2,3,4,
  * and there is a specialization for dim=0 (see the section on @ref
@@ -294,20 +696,20 @@ struct GeometryInfo
                                      * 2, on face 3 they are 2 and 3,
                                      * etc.
                                      *
-                                     * For three spatial dimensions,
-                                     * the exact order of the
-                                     * children is laid down in the
-                                     * documentation of the
-                                     * Triangulation class. Through
-                                     * the <tt>face_orientation</tt>
-                                     * argument this function handles
-                                     * faces oriented in both, the
-                                     * standard and non-standard
+                                     * For three spatial dimensions, the
+                                     * exact order of the children is laid
+                                     * down in the general documentation of
+                                     * this class. Through the
+                                     * <tt>face_orientation</tt> argument
+                                     * this function handles faces oriented
+                                     * in both, the standard and non-standard
                                      * orientation.
-                                     * <tt>face_orientation</tt>
-                                     * defaults to <tt>true</tt>
-                                     * (standard orientation) and has
-                                     * no effect in 2d.
+                                     * <tt>face_orientation</tt> defaults to
+                                     * <tt>true</tt> (standard orientation)
+                                     * and has no effect in 2d. The concept
+                                     * of face orientations is explained in
+                                     * this @ref GlossFaceOrientation "glossary"
+                                     * entry.
                                      */
     static unsigned int child_cell_on_face (const unsigned int face,
                                            const unsigned int subface,
@@ -321,15 +723,13 @@ struct GeometryInfo
                                      * line <tt>line</tt>, e.g.
                                      * <tt>GeometryInfo<2>::line_to_cell_vertices(3,0)=2</tt>.
                                      *
-                                     * The order of the lines, as
-                                     * well as their direction (which
-                                     * in turn determines which is
-                                     * the first and which the second
-                                     * vertex on a line) is the
-                                     * canonical one in deal.II, as
-                                     * described in the documentation
-                                     * of the Triangulation
-                                     * class.
+                                     * The order of the lines, as well as
+                                     * their direction (which in turn
+                                     * determines which is the first and
+                                     * which the second vertex on a line) is
+                                     * the canonical one in deal.II, as
+                                     * described in the general documentation
+                                     * of this class.
                                      *
                                      * For <tt>dim=2</tt> this call
                                      * is simply passed down to the
@@ -396,13 +796,11 @@ struct GeometryInfo
                                            const bool face_orientation = true);
     
                                     /**
-                                     * Return the position of the
-                                     * @p ith vertex on the unit
-                                     * cell. The order of vertices is
-                                     * the canonical one in deal.II,
-                                     * as described in the
-                                     * documentation of the
-                                     * Triangulation class.
+                                     * Return the position of the @p ith
+                                     * vertex on the unit cell. The order of
+                                     * vertices is the canonical one in
+                                     * deal.II, as described in the general
+                                     * documentation of this class.
                                      */
     static Point<dim> unit_cell_vertex (const unsigned int vertex);
 
@@ -417,9 +815,9 @@ struct GeometryInfo
                                      * always less than
                                      * GeometryInfo<dimension>::children_per_cell.
                                      *
-                                     * The order of child cells is
-                                     * described the documentation of
-                                     * the Triangulation class.
+                                     * The order of child cells is described
+                                     * the general documentation of this
+                                     * class.
                                      */
     static unsigned int child_cell_from_point (const Point<dim> &p);
 
index a094415e77305d88a0bc4a04c53340ce185e872a..ec40f38ac50c85b6b6a8379be7e6c321c7b09c73 100644 (file)
@@ -1128,389 +1128,7 @@ namespace internal
  *   apply some smoothing for multigrid algorithms, but this has to be decided
  *   upon later.
  *
- *
- *   <h4>Implementation conventions for two spatial dimensions</h4>
- *   
- *   From version 5.2 onwards deal.II is based on a numbering scheme,
- *   which uses a lexicographic ordering (with x running fastest)
- *   whereever possible, hence trying to adopt a kind of 'canonical'
- *   ordering.
- *
- *   The ordering of vertices and faces (lines) in 2d is defined by
- *
- *   N1) vertices are numbered in lexicographic ordering
- *
- *   N2) faces (lines in 2d): first the two faces with normals in x-
- *   and then y-direction. For each two faces: first the face with
- *   normal in negative coordinate direction, then the one with normal
- *   in positive direction, i.e. the faces are ordered according to
- *   their normals pointing in -x, x, -y, y direction.
- *
- *   N3) the direction of a line is represented by the direction of
- *   point 0 towards point 1 and is always in one of the coordinate
- *   directions
- * 
- *   N4/ face lines in 3d are ordered, such that the induced 2d local
- *   coordinate system (x,y) implies (right hand rule) a normal in
- *   face normal direction, see N2/.
- *
- *   The resulting numbering of vertices and faces (lines) in 2d as
- *   well as the directions of lines is shown in the following.
- *   @verbatim
- *         3
- *      2-->--3
- *      |     |
- *     0^     ^1
- *      |     |
- *      0-->--1
- *          2
- *   @endverbatim
- *   We note, that the orientation of lines has to be
- *   checked/generated upon construction of a grid and is preserved
- *   upon refinement.
- *
- *   Further we define, that child lines have the same direction as their parent,
- *   i.e. that <tt>subline(0).vertex(0)==line.vertex(0)</tt> and
- *   <tt>subline(1).vertex(1)==line.vertex(1)</tt>. This also implies, that the
- *   first subline (<tt>subline(0)</tt>) is the one at vertex(0) of the old line.
- *
- *   Similarly we define, that the four children of a quad are adjacent to the
- *   vertex with the same number of the old quad.
- *
- *   Note that information about several of these conventions can be
- *   extracted at run- or compile-time from the member functions and
- *   variables of the GeometryInfo classes.
- *
- *
- *   <h4>Coordinate systems</h4>
- *
- *   When explicit coordinates are required for points in a cell (e.g for
- *   quadrature formulae or the point of definition of trial functions), we
- *   define the following coordinate system for the unit cell:
- *   @verbatim
- *    y^   2-----3
- *     |   |     |
- *     |   |     |
- *     |   |     |
- *     |   0-----1
- *     *------------>x
- *   @endverbatim
- *   with vertex 0 being the origin of the coordinate system, vertex 1
- *   having coordinates <tt>(1,0)</tt>, vertex 2 at <tt>(0,1)</tt> and
- *   vertex 3 at <tt>(1,1)</tt>.
- *
- *
- *   <h3>Implementation conventions for three spatial dimensions</h3>
- *
- *   By convention, we will use the following numbering conventions
- *   for vertices, lines and faces of hexahedra in three space
- *   dimensions. Before giving these conventions we declare the
- *   following sketch to be the standard way of drawing 3d pictures of
- *   hexahedra:
- *   @verbatim
- *                         *-------*        *-------*
- *                        /|       |       /       /|
- *                       / |       |      /       / |
- *    z                 /  |       |     /       /  |
- *    ^                *   |       |    *-------*   |
- *    |   ^y           |   *-------*    |       |   *
- *    |  /             |  /       /     |       |  /
- *    | /              | /       /      |       | /
- *    |/               |/       /       |       |/
- *    *------>x        *-------*        *-------*
- *   @endverbatim
- *   The left part of the picture shows the left, bottom and back face of the
- *   cube, while the right one shall be the top, right and front face. You may
- *   recover the whole cube by moving the two parts together into one.
- *
- *   Note again that information about several of the following
- *   conventions can be extracted at run- or compile-time from the
- *   member functions and variables of the GeometryInfo classes.
- *
- *   <h4>Vertices</h4>
- *  
- *   The ordering of vertices in 3d is defined by the same rules as in
- *   the 2d case, i.e.
- *
- *   N1) vertices are numbered in lexicographic ordering
- *
- *   Hence, the vertices are numbered as follows   
- *   @verbatim
- *         6-------7        6-------7
- *        /|       |       /       /|
- *       / |       |      /       / |
- *      /  |       |     /       /  |
- *     4   |       |    4-------5   |
- *     |   2-------3    |       |   3
- *     |  /       /     |       |  /
- *     | /       /      |       | /
- *     |/       /       |       |/
- *     0-------1        0-------1
- *   @endverbatim
  *   
- *   We note, that first the vertices on the bottom face (z=0) are
- *   numbered exactly the same way as are the vertices on a
- *   quadrilateral. Then the vertices on the top face (z=1) are
- *   numbered similarly by moving the bottom face to the top.
- *
- *   <h4>Lines</h4>
- *
- *   Here, the same holds as for the vertices:
- *
- *   N4) line ordering in 3d:
- *   <ul>
- *     <li>first the lines of face (z=0) in 2d line ordering,
- *     <li>then the lines of face (z=1) in 2d line ordering,
- *     <li>finally the lines in z direction in lexicographic ordering
- *   </ul>
- *   @verbatim
- *         *---7---*        *---7---*
- *        /|       |       /       /|
- *       4 |       11     4       5 11
- *      /  10      |     /       /  |
- *     *   |       |    *---6---*   |
- *     |   *---3---*    |       |   *
- *     |  /       /     |       9  /
- *     8 0       1      8       | 1
- *     |/       /       |       |/
- *     *---2---*        *---2---*
- *   @endverbatim
- *   As in 2d lines are directed in coordinate directions, see N3.
- *   @verbatim
- *         *--->---*        *--->---*
- *        /|       |       /       /|
- *       ^ |       ^      ^       ^ ^
- *      /  ^       |     /       /  |
- *     *   |       |    *--->---*   |
- *     |   *--->---*    |       |   *
- *     |  /       /     |       ^  /
- *     ^ ^       ^      ^       | ^
- *     |/       /       |       |/
- *     *--->---*        *--->---*
- *   @endverbatim
- *
- *   The fact that edges (just as vertices and faces) are entities
- *   that are stored in their own right rather than constructed from
- *   cells each time they are needed, means that adjacent cells
- *   actually have pointers to edges that are thus shared between
- *   them. This implies that the convention that sets of parallel
- *   edges have parallel directions is not only a local
- *   condition. Before a list of cells is passed to an object of this
- *   class for creation of a triangulation, you therefore have to make
- *   sure that cells are oriented in a compatible fashion, so that
- *   edge directions are globally according to above
- *   convention. However, the GridReordering class can do this
- *   for you, by reorienting cells and edges of an arbitrary list of
- *   input cells that need not be already sorted.
- *   
- *   <h4>Faces</h4>
- *
- *   The numbering of faces in 3d is defined by a rule analogous to 2d:
- *
- *   N2a) faces (quads in 3d): first the two faces with normals in x-,
- *   then y- and z-direction. For each two faces: first the face with
- *   normal in negative coordinate direction, then the one with normal
- *   in positive direction, i.e. the faces are ordered according to
- *   their normals pointing in -x, x, -y, y, -z, z direction.
- *
- *   Therefore, the faces are numbered in the ordering: left, right,
- *   front, back, bottom and top face:
- *   @verbatim
- *         *-------*        *-------*
- *        /|       |       /       /|
- *       / |   3   |      /   5   / |
- *      /  |       |     /       /  |
- *     *   |       |    *-------*   |
- *     | 0 *-------*    |       | 1 *
- *     |  /       /     |       |  /
- *     | /   4   /      |   2   | /
- *     |/       /       |       |/
- *     *-------*        *-------*
- *   @endverbatim
- *
- *   The <em>standard</em> direction of the faces is such, that the
- *   induced 2d local coordinate system (x,y) implies (right hand
- *   rule) a normal in face normal direction, see N2a).  In the
- *   following we show the local coordinate system and the numbering
- *   of face lines:
- *   <ul>
- *   <li> Faces 0 and 1:
- *    @verbatim
- *            Face 0           Face 1
- *          *-------*        *-------*
- *         /|       |       /       /|
- *        3 1       |      /       3 1
- *      y/  |       |     /      y/  |
- *      *   |x      |    *-------*   |x
- *      |   *-------*    |       |   *
- *      0  /       /     |       0  /
- *      | 2       /      |       | 2
- *      |/       /       |       |/
- *      *-------*        *-------*
- *    @endverbatim
- * 
- *   <li> Faces 2 and 3:
- *    @verbatim
- *          x Face 3           Face 2
- *          *---1---*        *-------*
- *         /|       |       /       /|
- *        / |       3      /       / |
- *       /  2       |    x/       /  |
- *      *   |       |    *---1---*   |
- *      |   *---0---*y   |       |   *
- *      |  /       /     |       3  /
- *      | /       /      2       | /
- *      |/       /       |       |/
- *      *-------*        *---0---*y
- *    @endverbatim 
- * 
- *   <li> Faces 4 and 5:
- *    @verbatim
- *            Face 4         y Face 5
- *          *-------*        *---3---*
- *         /|       |       /       /|
- *        / |       |      0       1 |
- *       /  |       |     /       /  |
- *      *   |y      |    *---2---* x |
- *      |   *---3---*    |       |   *
- *      |  /       /     |       |  /
- *      | 0       1      |       | /
- *      |/       /       |       |/
- *      *---2---* x      *-------*
- *    @endverbatim
- *   </ul>
- *
- *   The face line numbers (0,1,2,3) correspond to following cell line
- *   numbers.
- *   <ul>
- *   <li> Face 0: lines 8, 10, 0, 4;
- *   <li> Face 1: lines 9, 11, 1, 5;
- *   <li> Face 2: lines 2, 6, 8, 9;
- *   <li> Face 3: lines 3, 7, 10, 11;
- *   <li> Face 4: lines 0, 1, 2, 3;
- *   <li> Face 5: lines 4, 5, 6, 7;
- *   </ul>
- *   You can get these numbers using the
- *   GeometryInfo<3>::face_to_cell_lines() function.
- *
- *   The face normals can be deduced from the face orientation by
- *   applying the right hand side rule (x,y -> normal).  We note, that
- *   in the standard orientation of faces in 2d, faces 0 and 2 have
- *   normals that point into the cell, and faces 1 and 3 have normals
- *   pointing outward. In 3d, faces 0, 2, and 4
- *   have normals that point into the cell, while the normals of faces
- *   1, 3, and 5 point outward. This information, again, can be queried from
- *   GeometryInfo<dim>::unit_normal_orientation.
- *
- *   However, it turns out that a significant number of 3d meshes cannot
- *   satisfy this convention. This is due to the fact that the face
- *   convention for one cell already implies something for the
- *   neighbor, since they share a common face and fixing it for the
- *   first cell also fixes the normal vectors of the opposite faces of
- *   both cells. It is easy to construct cases of loops of cells for
- *   which this leads to cases where we cannot find orientations for
- *   all faces that are consistent with this convention.
- *
- *   For this reason, above convention is only what we call the
- *   <em>standard orientation</em>. deal.II actually allows faces in
- *   3d to have either the standard direction, or its opposite, in
- *   which case the lines that make up a cell would have reverted
- *   orders, and the above line equivalences would not hold any
- *   more. You can ask a cell whether a given face has standard
- *   orientation by calling <tt>cell->face_orientation(face_no)</tt>: if
- *   the result is @p true, then the face has standard orientation,
- *   otherwise its normal vector is pointing the other
- *   direction. There are not very many places in application programs
- *   where you need this information actually, but a few places in the
- *   library make use of this. Note that in 2d, the
- *   result is always @p true.
- *
- *
- *   <h4>Children</h4>
- *
- *   The eight children of a cell are numbered according to the vertices:
- *   @verbatim
- *         *-------*        *-------*
- *        /| 6   7 |       / 6   7 /|
- *       /6|       |      /       /7|
- *      /  |       |     / 4   5 /  |
- *     *   | 2   3 |    *-------*5 3|
- *     |4 2*-------*    | 4   5 |   *
- *     |  / 2   3 /     |       |  /
- *     |0/       /      |       |1/
- *     |/0    1 /       | 0   1 |/
- *     *-------*        *-------*
- *   @endverbatim
- *
- *   Taking into account the orientation of the faces, the following
- *   children are adjacent to the respective faces:
- *   <ul>
- *   <li> Face 0: children 0, 2, 4, 6;
- *   <li> Face 1: children 1, 3, 5, 7;
- *   <li> Face 2: children 0, 4, 1, 5;
- *   <li> Face 3: children 2, 6, 3, 7;
- *   <li> Face 4: children 0, 1, 2, 3;
- *   <li> Face 5: children 4, 5, 6, 7.
- *   </ul>
- *   You can get these numbers using the
- *   GeometryInfo<3>::child_cell_on_face() function. As each child is
- *   adjacent to the vertex with the same number these numbers are
- *   also given by the GeometryInfo<3>::face_to_cell_vertices()
- *   function.
- *
- *   Note that, again, the above list only holds for faces in their
- *   standard orientation. If a face is not in standard orientation,
- *   then the children at positions 1 and 2 (counting from 0 to 3)
- *   would be swapped. In fact, this is what the child_cell_on_face
- *   and the face_to_cell_vertices functions of GeometryInfo<3> do,
- *   when invoked with a <tt>face_orientation=false</tt> argument.
- *
- *   The information which child cell is at which position of which
- *   face is most often used when computing jump terms across faces
- *   with hanging nodes, using objects of type
- *   FESubfaceValues. Sitting on one cell, you would look at face and
- *   figure out which child of the neighbor is sitting on a given
- *   subface between the present and the neighboring cell. To avoid
- *   having to query the standard orientation of the faces of the two
- *   cells every time in such cases, you should use a function call
- *   like
- *   <tt>cell->neighbor_child_on_subface(face_no,subface_no)</tt>,
- *   which returns the correct result both in 2d (where face
- *   orientations are immaterial) and 3d (where it is necessary to use
- *   the face orientation as additional argument to
- *   <tt>GeometryInfo<3>::child_cell_on_face</tt>).
- *
- *   <h4>Coordinate systems</h4>
- *
- *   We define the following coordinate system for the explicit coordinates of
- *   the vertices of the unit cell:
- *   @verbatim
- *                         6-------7        6-------7
- *                        /|       |       /       /|
- *                       / |       |      /       / |
- *    z                 /  |       |     /       /  |
- *    ^                4   |       |    4-------5   |
- *    |   ^y           |   2-------3    |       |   3
- *    |  /             |  /       /     |       |  /
- *    | /              | /       /      |       | /
- *    |/               |/       /       |       |/
- *    *------>x        0-------1        0-------1
- *   @endverbatim
- *
- *   By the convention laid down as above, the vertices have the following
- *   coordinates (lexicographic, with x running fastest):
- *   <ul>
- *      <li> Vertex 0: <tt>(0,0,0)</tt>;
- *      <li> Vertex 1: <tt>(1,0,0)</tt>;
- *      <li> Vertex 2: <tt>(0,1,0)</tt>;
- *      <li> Vertex 3: <tt>(1,1,0)</tt>;
- *      <li> Vertex 4: <tt>(0,0,1)</tt>;
- *      <li> Vertex 5: <tt>(1,0,1)</tt>;
- *      <li> Vertex 6: <tt>(0,1,1)</tt>;
- *      <li> Vertex 7: <tt>(1,1,1)</tt>.
- *   </ul>
- *
- *
  *   <h3>Warning</h3>
  *
  *   It seems impossible to preserve @p constness of a triangulation through

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.