]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Write something about the Z order in the glossary. 5694/head
authorWolfgang Bangerth <bangerth@colostate.edu>
Tue, 2 Jan 2018 22:54:47 +0000 (15:54 -0700)
committerWolfgang Bangerth <bangerth@colostate.edu>
Thu, 4 Jan 2018 14:26:24 +0000 (07:26 -0700)
12 files changed:
doc/doxygen/headers/glossary.h
doc/doxygen/images/simple-mesh-0.fig [new file with mode: 0644]
doc/doxygen/images/simple-mesh-0.png [new file with mode: 0644]
doc/doxygen/images/simple-mesh-1.fig [new file with mode: 0644]
doc/doxygen/images/simple-mesh-1.png [new file with mode: 0644]
doc/doxygen/images/simple-mesh-2.fig [new file with mode: 0644]
doc/doxygen/images/simple-mesh-2.png [new file with mode: 0644]
doc/doxygen/images/simple-mesh-3.fig [new file with mode: 0644]
doc/doxygen/images/simple-mesh-3.png [new file with mode: 0644]
doc/doxygen/images/simple-mesh-tree.fig [new file with mode: 0644]
doc/doxygen/images/simple-mesh-tree.png [new file with mode: 0644]
include/deal.II/distributed/shared_tria.h

index e035a08532f4c8bcd3adbc26d7bae41d1c7c28cd..82dceec989a3e326fd5ad94eec61ce83bd9cc5e8 100644 (file)
  * It is available from <a href="http://www.math.colostate.edu/~bangerth/publications.html">http://www.math.colostate.edu/~bangerth/publications.html</a>, also see <a href="https://www.dealii.org/publications.html#details">deal.II publications</a> for details.
  * </dd>
  *
+ *
+ * <dt class="glossary">@anchor GlossZOrder <b>Z order</b></dt>
+ * <dd>
+ *  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 <int dim>
+ *    void visit_cells_hierarchically (const typename Triangulation<dim>::cell_iterator &cell)
+ *    {
+ *      if (cell->has_children())
+ *        for (unsigned int c=0; c<cell->n_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<dim>::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 .
+ * </dd>
+ *
+ *
+ *
  * </dl>
  */
diff --git a/doc/doxygen/images/simple-mesh-0.fig b/doc/doxygen/images/simple-mesh-0.fig
new file mode 100644 (file)
index 0000000..64247f6
--- /dev/null
@@ -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 (file)
index 0000000..3380d09
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 (file)
index 0000000..db32eab
--- /dev/null
@@ -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 (file)
index 0000000..797e3a6
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 (file)
index 0000000..2319328
--- /dev/null
@@ -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 (file)
index 0000000..708c7ee
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 (file)
index 0000000..29a5b9f
--- /dev/null
@@ -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 (file)
index 0000000..a76cbcc
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 (file)
index 0000000..4f64c41
--- /dev/null
@@ -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 (file)
index 0000000..b5dc37b
Binary files /dev/null and b/doc/doxygen/images/simple-mesh-tree.png differ
index fae5637e10aecc2d232327d2134481be50971149..d072095013a6fe021ec2736f71d03cfaa9b33279 100644 (file)
@@ -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,
 

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.