From: Wolfgang Bangerth Date: Tue, 2 Jan 2018 22:54:47 +0000 (-0700) Subject: Write something about the Z order in the glossary. X-Git-Tag: v9.0.0-rc1~603^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da251d6a4fe245726a8f5354b07db1d4ab201949;p=dealii.git Write something about the Z order in the glossary. --- diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index e035a08532..82dceec989 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -1791,5 +1791,115 @@ * It is available from http://www.math.colostate.edu/~bangerth/publications.html, also see deal.II publications for details. * * + * + *
@anchor GlossZOrder Z order
+ *
+ * The "Z order" of cells describes an order in which cells are traversed. + * + * By default, if you write a loop over all cells in deal.II, the cells + * will be traversed in an order where coarser cells (i.e., cells that were + * obtained from coarse mesh cells with fewer refinement steps) come before + * cells that are finer (i.e., cells that were obtained with more refinement + * steps). Within each refinement level, cells are traversed in an order + * that has something to do with the order in which they were created; + * in essence, however, this order is best of thought of as "unspecified": + * you will visit each cell on a given refinement level exactly once, in + * some order, but you should not make any assumptions about this order. + * + * Because the order in which cells are created factors into the order + * of cells, it can happen that the order in which you traverse cells is + * different for two identical meshes. For example, think of a 1d (coarse) + * mesh with two cells: If you first refine the first of these cells and then + * the other, then you will traverse the four cells on refinement level 1 + * in a different order than if you had first refined the second coarse + * cell and then the first coarse cell. + * + * This order is entirely practical for almost all applications because + * in most cases, it does not actually matter in which order one traverses + * cells. Furthermore, it allows using data structures that lead to + * particularly low cache miss frequencies and are therefore efficient + * for high performance computing applications. + * + * On the other hand, there are cases where one would want to traverse + * cells in a particular, specified and reproducible order that only + * depends on the mesh itself, not its creation history or any other + * seemingly arbitrary design decisions. The "Z order" is one way + * to achieve this goal. + * + * To explain the concept of the Z order, consider the following sequence + * of meshes (with each cell numbered using the "level.index" notation, + * where "level" is the number of refinements necessary to get from a + * coarse mesh cell to a particular cell, and "index" the index of this + * cell within a particular refinement level): + * + * @image html simple-mesh-0.png "A coarse mesh" + * @image html simple-mesh-1.png "The mesh after one refinement cycle" + * @image html simple-mesh-2.png "The mesh after two refinement cycles" + * @image html simple-mesh-3.png "The mesh after three refinement cycles" + * + * Note how the cells on level 2 are ordered in the order in which they + * were created. (Which is not always the case: if cells had been removed + * in between, then newly created cells would have filled in the holes + * so created.) + * + * The "natural" order in which deal.II traverses cells would then be + * 0.0 -> 1.0 -> 1.1 -> 1.2 -> 1.3 -> 2.0 -> 2.1 -> 2.2 -> 2.3 -> 2.4 -> + * 2.5 -> 2.6 -> 2.7. (If you want to traverse only over the + * @ref GlossActive "active cells", then omit all cells from this + * list that have children.) + * This can be thought of as the "lexicographic" + * order on the pairs of numbers "level.index", but because the index + * within each level is not well defined, this is not a particularly useful + * notion. Alternatively, one can also think of it as one possible breadth-first + * traversal of the tree that corresponds to this mesh and that represents + * the parent-child relationship between cells: + * + * @image html simple-mesh-tree.png "The tree that corresponds to the mesh after three refinement cycles" + * + * On the other hand, the Z order corresponds to a particular + * depth-first traversal of the tree. Namely: start with a cell, and if it + * has children then iterate over these cell's children; this rule is + * recursively applied as long as a child has childen. + * + * For the given mesh above, this yields the following order: 0.0 -> 1.0 -> 2.4 + * -> 2.5 -> 2.6 -> 2.7 -> 1.1 -> 1.2 -> 1.3 -> 1.4 -> 2.0 -> 2.1 -> 2.2 -> 2.3. + * (Again, if you only care about active cells, then remove 0.0, 1.0, and 1.3 + * from this list.) Because the order of children of a cell is well defined + * (as opposed to the order of cells within each level), this "hierarchical" + * traversal makes sense and is, in particular, independent of the history + * of a triangulation. + * + * In practice, it is easily implemented using a recursive function: + * @code + * template + * void visit_cells_hierarchically (const typename Triangulation::cell_iterator &cell) + * { + * if (cell->has_children()) + * for (unsigned int c=0; cn_children(); ++c) + * visit_cells_hierarchically (cell->child(c)); + * else + * { + * ... do whatever you wanted to do on each cell ...; + * } + * } + * @endcode + * This function is then called as follows: + * @code + * // loop over all coarse mesh cells + * for (typename Triangulation::cell_iterator cell = triangulation.begin(0); + * cell != triangulation.end(); ++cell) + * visit_cells_hierarchically (cell); + * @endcode + * + * Finally, as an explanation of the term "Z" order: if you draw a line through + * all cells in the order in which they appear in this hierarchical fashion, + * then it will look like a left-right inverted Z on each refined cell. Indeed, + * the curve so defined can be thought of a space-filling curve and is also + * sometimes called "Morton ordering", see + * https://en.wikipedia.org/wiki/Z-order_curve . + *
+ * + * + * * */ diff --git a/doc/doxygen/images/simple-mesh-0.fig b/doc/doxygen/images/simple-mesh-0.fig new file mode 100644 index 0000000000..64247f6d44 --- /dev/null +++ b/doc/doxygen/images/simple-mesh-0.fig @@ -0,0 +1,14 @@ +#FIG 3.2 Produced by xfig version 3.2.6 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +4 1 0 50 -1 18 16 0.0000 4 150 270 1350 1440 0.0\001 diff --git a/doc/doxygen/images/simple-mesh-0.png b/doc/doxygen/images/simple-mesh-0.png new file mode 100644 index 0000000000..3380d09faa Binary files /dev/null and b/doc/doxygen/images/simple-mesh-0.png differ diff --git a/doc/doxygen/images/simple-mesh-1.fig b/doc/doxygen/images/simple-mesh-1.fig new file mode 100644 index 0000000000..db32eabcff --- /dev/null +++ b/doc/doxygen/images/simple-mesh-1.fig @@ -0,0 +1,21 @@ +#FIG 3.2 Produced by xfig version 3.2.6 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 450 2250 450 2250 1350 1350 1350 1350 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 1350 450 1350 450 2250 1350 2250 1350 1350 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +4 1 0 50 -1 18 16 0.0000 4 150 270 855 1935 1.0\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 1800 1935 1.1\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 855 990 1.2\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 1800 990 1.3\001 diff --git a/doc/doxygen/images/simple-mesh-1.png b/doc/doxygen/images/simple-mesh-1.png new file mode 100644 index 0000000000..797e3a645f Binary files /dev/null and b/doc/doxygen/images/simple-mesh-1.png differ diff --git a/doc/doxygen/images/simple-mesh-2.fig b/doc/doxygen/images/simple-mesh-2.fig new file mode 100644 index 0000000000..231932847e --- /dev/null +++ b/doc/doxygen/images/simple-mesh-2.fig @@ -0,0 +1,28 @@ +#FIG 3.2 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 450 2250 450 2250 1350 1350 1350 1350 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 1350 450 1350 450 2250 1350 2250 1350 1350 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1800 450 2250 450 2250 900 1800 900 1800 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1800 900 1350 900 1350 1350 1800 1350 1800 900 +4 1 0 50 -1 18 16 0.0000 4 180 180 855 1935 1.0\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 1800 1935 1.1\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 855 990 1.2\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 1575 1215 2.0\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 2025 1215 2.1\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 1575 765 2.2\001 +4 1 0 50 -1 18 16 0.0000 4 180 180 2025 765 2.3\001 diff --git a/doc/doxygen/images/simple-mesh-2.png b/doc/doxygen/images/simple-mesh-2.png new file mode 100644 index 0000000000..708c7ee39f Binary files /dev/null and b/doc/doxygen/images/simple-mesh-2.png differ diff --git a/doc/doxygen/images/simple-mesh-3.fig b/doc/doxygen/images/simple-mesh-3.fig new file mode 100644 index 0000000000..29a5b9fe02 --- /dev/null +++ b/doc/doxygen/images/simple-mesh-3.fig @@ -0,0 +1,37 @@ +#FIG 3.2 Produced by xfig version 3.2.6 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +6 1305 405 2295 1395 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 450 2250 450 2250 1350 1350 1350 1350 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1800 450 2250 450 2250 900 1800 900 1800 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1800 900 1350 900 1350 1350 1800 1350 1800 900 +4 1 0 50 -1 18 16 0.0000 4 150 270 1575 1215 2.0\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 2025 1215 2.1\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 1575 765 2.2\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 2025 765 2.3\001 +-6 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 1350 1350 450 1350 450 2250 1350 2250 1350 1350 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 450 2250 450 2250 2250 450 2250 450 450 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 450 1350 1350 1350 1350 2250 450 2250 450 1350 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 900 1350 1350 1350 1350 1800 900 1800 900 1350 +2 2 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 5 + 900 1800 450 1800 450 2250 900 2250 900 1800 +4 1 0 50 -1 18 16 0.0000 4 150 270 1800 1935 1.1\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 855 990 1.2\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 675 2115 2.4\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 1125 2115 2.5\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 675 1665 2.6\001 +4 1 0 50 -1 18 16 0.0000 4 150 270 1125 1665 2.7\001 diff --git a/doc/doxygen/images/simple-mesh-3.png b/doc/doxygen/images/simple-mesh-3.png new file mode 100644 index 0000000000..a76cbcc729 Binary files /dev/null and b/doc/doxygen/images/simple-mesh-3.png differ diff --git a/doc/doxygen/images/simple-mesh-tree.fig b/doc/doxygen/images/simple-mesh-tree.fig new file mode 100644 index 0000000000..4f64c418a2 --- /dev/null +++ b/doc/doxygen/images/simple-mesh-tree.fig @@ -0,0 +1,46 @@ +#FIG 3.2 Produced by xfig version 3.2.6 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1035 1395 585 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1035 1395 923 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1035 1395 1260 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1035 1395 1598 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 2565 1395 2115 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 2565 1395 2453 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 2565 1395 2790 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 2565 1395 3128 2070 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1800 450 1575 1125 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1800 450 2025 1125 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1800 450 1125 1125 +2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 1800 450 2475 1125 +4 1 0 50 -1 18 12 0.0000 4 150 270 1800 405 0.0\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 1260 2295 2.6\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 585 2295 2.4\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 923 2295 2.5\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 1598 2295 2.7\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 2790 2295 2.2\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 3128 2295 2.3\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 2115 2295 2.0\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 2453 2295 2.1\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 1125 1350 1.0\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 1575 1350 1.1\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 2025 1350 1.2\001 +4 1 0 50 -1 18 12 0.0000 4 150 270 2475 1350 1.3\001 diff --git a/doc/doxygen/images/simple-mesh-tree.png b/doc/doxygen/images/simple-mesh-tree.png new file mode 100644 index 0000000000..b5dc37b9a5 Binary files /dev/null and b/doc/doxygen/images/simple-mesh-tree.png differ diff --git a/include/deal.II/distributed/shared_tria.h b/include/deal.II/distributed/shared_tria.h index fae5637e10..d072095013 100644 --- a/include/deal.II/distributed/shared_tria.h +++ b/include/deal.II/distributed/shared_tria.h @@ -148,6 +148,8 @@ namespace parallel * children are enumerated by the GeometryInfo class. The * "Z-order" is also sometimes called "Morton ordering", see * https://en.wikipedia.org/wiki/Z-order_curve . + * + * @see This @ref GlossZOrder "glossary entry". */ partition_zorder = 0x2,