From 1c4daba2bdba3fe8555c6130c589cb4a203623a9 Mon Sep 17 00:00:00 2001 From: David Wells Date: Sun, 15 Jul 2018 20:26:08 -0400 Subject: [PATCH] Add a glossary entry on colorization. --- doc/doxygen/headers/glossary.h | 28 ++++++++++- include/deal.II/grid/grid_generator.h | 69 +++++++++++++++++++-------- 2 files changed, 76 insertions(+), 21 deletions(-) diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index e37bcf4336..3a4d72740a 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -319,7 +319,9 @@ * 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, * or unless you use one of the mesh generation functions in namespace GridGenerator - * that have a 'colorize' option. A typical piece of code that sets the boundary + * that have a + * @ref GlossColorization "colorize" + * option. A typical piece of code that sets the boundary * indicator on part of the boundary to something else would look like * this, here setting the boundary indicator to 42 for all faces located at * $x=-1$: @@ -378,6 +380,28 @@ * @see @ref boundary "The module on boundaries" * * + *
@anchor GlossColorization Colorization
+ *
Colorization is the process of marking certain parts of a + * Triangulation with different labels. The use of the word color + * comes from cartography, where countries on a map are made visually distinct + * from each other by assigning them different colors. Using the same term + * coloring is common in mathematics, even though we assign integers + * and not hues to different regions. deal.II refers to two processes as + * coloring: + * + *
    + *
  1. Most of the functions in the GridGenerator namespace take an optional + * argument colorize. This argument controls whether or not the + * different parts of the boundary will be assigned different + * @ref GlossBoundaryIndicator "boundary indicators". Some functions also assign + * different + * @ref GlossMaterialId "material indicators" as well.
    2. + *
  2. The function GraphColoring::make_graph_coloring() computes a + * decomposition of a Triangulation (more exactly, a range of iterators). No + * two adjacent cells are given the same color.
    3. + *
+ *
+ * *
@anchor GlossComponent Component
* *
When considering systems of equations in which the solution is not @@ -424,7 +448,7 @@ * FEValues::shape_value_component() and FEValues::shape_grad_component() * functions do the same on a real cell. See also the documentation of the * FiniteElement and FEValues classes. - * + * * Selecting components: * Many functions allow you to restrict their operation to certain * vector components or blocks. For example, this is the case for diff --git a/include/deal.II/grid/grid_generator.h b/include/deal.II/grid/grid_generator.h index 853c14534e..462dc9fa4f 100644 --- a/include/deal.II/grid/grid_generator.h +++ b/include/deal.II/grid/grid_generator.h @@ -35,8 +35,9 @@ DEAL_II_NAMESPACE_OPEN * This namespace provides a collection of functions for generating * triangulations for some basic geometries. * - * Some of these functions receive a flag @p colorize. If this is set, parts of - * the boundary receive different + * Some of these functions receive a flag @p colorize (see + * @ref GlossColorization "the glossary entry on colorization"). + * If this is set, parts of the boundary receive different * @ref GlossBoundaryIndicator "boundary indicators" * allowing them to be distinguished for the purpose of evaluating * different boundary conditions. @@ -67,9 +68,10 @@ namespace GridGenerator * zero and unity, then producing the unit hypercube. * * If the argument @p colorize is false, all boundary indicators are set to - * zero ("not colorized") for 2d and 3d. If it is true, the boundary is - * colorized as in hyper_rectangle(). In 1d the indicators are always - * colorized, see hyper_rectangle(). + * zero (the default boundary indicator) for 2d and 3d. If it is true, the + * boundary is + * @ref GlossColorization "colorized" as in hyper_rectangle(). In 1d the + * indicators are always colorized, see hyper_rectangle(). * * @image html hyper_cubes.png * @@ -144,12 +146,16 @@ namespace GridGenerator * Create a coordinate-parallel brick from the two diagonally opposite * corner points @p p1 and @p p2. * - * If the @p colorize flag is @p true, the @p boundary_ids of the boundary + * If the @p colorize (see + * @ref GlossColorization "the glossary entry on colorization") + * flag is true, then the @p boundary_ids of the boundary * faces are assigned, such that the lower one in @p x-direction is 0, the * upper one is 1. The indicators for the surfaces in @p y-direction are 2 * and 3, the ones for @p z are 4 and 5. This corresponds to the numbers of * faces of the unit square of cube as laid out in the documentation of the - * GeometryInfo class. Importantly, however, in 3d colorization does not set + * GeometryInfo class. Importantly, however, in 3d + * @ref GlossColorization "colorization" + * does not set * @p boundary_ids of edges, but only of faces, because each * boundary edge is shared between two faces and it is not clear how the * boundary id of an edge should be set in that case. @@ -186,7 +192,9 @@ namespace GridGenerator * coordinate directions. The minimum number of subdivisions in each * direction is 1. * - * If the @p colorize flag is set, the @p boundary_ids of the surfaces are + * If the @p colorize (see + * @ref GlossColorization "the glossary entry on colorization") + * flag is true, then the @p boundary_ids of the surfaces are * assigned, such that the lower one in @p x-direction is 0, the upper one is * 1 (the left and the right vertical face). The indicators for the surfaces * in @p y-direction are 2 and 3, the ones for @p z are 4 and 5. @@ -336,7 +344,10 @@ namespace GridGenerator * * In 3D, triangulation will be extruded in the z-direction by the total * height of @p L using @p n_slices slices (minimum is 2). - * If the @p colorize flag is true, the boundary_ids of the boundary + + * If the @p colorize (see + * @ref GlossColorization "the glossary entry on colorization") + * flag is true, the boundary_ids of the boundary * faces are assigned, such that the lower one in the x-direction is 0, the * upper one is 1. The indicators for the surfaces in the y-direction are 2 * and 3, and the ones for the z-direction are 5 and 6. The hole boundary has @@ -367,7 +378,9 @@ namespace GridGenerator * stored in the same order as they are given. It is also important to make * sure that the volume of the cell is positive. * - * If the argument @p colorize is false, all boundary indicators are set to + * If the argument @p colorize (see + * @ref GlossColorization "the glossary entry on colorization") + * is false, all boundary indicators are set to * zero ("not colorized") for 2d and 3d. If it is true, the boundary is * colorized as in hyper_rectangle(). In 1d the indicators are always * colorized, see hyper_rectangle(). @@ -466,7 +479,9 @@ namespace GridGenerator * Each entry must be positive. An empty vector is equivalent to one * subdivision in each direction. * - * @param colorize Assign different boundary ids if set to true. + * @param colorize + * (see @ref GlossColorization "the glossary entry on colorization") + * Assign different boundary ids if set to true. * * @note Implemented for all combinations of @p dim and @p spacedim. * @@ -487,7 +502,9 @@ namespace GridGenerator * give the lower and upper bound of the inner hypercube in all coordinate * directions. @p thickness marks the size of the layer cells. * - * If the flag @p colorize is set, the outer cells get material id's + * If the flag @p colorize (see + * @ref GlossColorization "the glossary entry on colorization") + * is set, the outer cells get material id's * according to the following scheme: extending over the inner cube in (+/-) * x-direction: 1/2. In y-direction 4/8, in z-direction 16/32. The cells at * corners and edges (3d) get these values bitwise or'd. @@ -685,7 +702,9 @@ namespace GridGenerator * stacked on this face. All numbers may be zero, thus L- and T-shaped * domains are specializations of this domain. * - * @param colorize_cells If colorization is chosen, then the material id of + * @param colorize_cells If colorization (see + * @ref GlossColorization "the glossary entry on colorization") + * is enabled, then the material id of * a cells corresponds to the leg it is in. The id of the center cell is * zero, and then the legs are numbered starting at one. * @@ -716,7 +735,9 @@ namespace GridGenerator * remain bounded. As a consequence, this domain is often used to * test convergence of schemes when the solution lacks regularity. * - * If the @p colorize flag is set, the @p boundary_ids of the + * If the @p colorize flag + * (see @ref GlossColorization "the glossary entry on colorization") + * is true, the @p boundary_ids of the * surfaces are assigned such that the left boundary is 0 and the * others are assigned counterclockwise in ascending order. * The @p colorize option only works in two dimensions. @@ -755,7 +776,9 @@ namespace GridGenerator * declared to exist for triangulations of all space dimensions, but throws * an error if called in 1d. * - * If @p colorize is set to @p true, the faces forming the slit are marked + * If @p colorize + * (see @ref GlossColorization "the glossary entry on colorization") + * is set to @p true, the faces forming the slit are marked * with boundary id 1 and 2, respectively. * * @note The triangulation passed as argument needs to be empty when calling this function. @@ -774,7 +797,9 @@ namespace GridGenerator * of cells of the resulting triangulation, i.e., how many cells form the * ring (in 2d) or the shell (in 3d). * - * If the flag @p colorize is @p true, then the outer boundary will have the + * If the flag @p colorize + * (see @ref GlossColorization "the glossary entry on colorization") + * is true, then the outer boundary will have the * indicator 1, while the inner boundary has id zero. In 3d, this applies to * both the faces and the edges of these boundaries. If the flag is @p * false, both have indicator zero. @@ -828,7 +853,9 @@ namespace GridGenerator * computed adaptively such that the resulting elements have the least * aspect ratio. * - * If colorize is set to true, the inner, outer, and the part of the + * If colorize + * (see @ref GlossColorization "the glossary entry on colorization") + * is set to true, the inner, outer, and the part of the * boundary where $x=0$, get indicator 0, 1, and 2, respectively. Otherwise * all indicators are set to 0. * @@ -860,7 +887,9 @@ namespace GridGenerator * computed adaptively such that the resulting elements have the least * aspect ratio in 2d. * - * If @p colorize is set to true, the inner, outer, left, and right boundary + * If @p colorize + * (see @ref GlossColorization "the glossary entry on colorization") + * is set to true, the inner, outer, left, and right boundary * get indicator 0, 1, 2, and 3 in 2d, respectively. Otherwise all * indicators are set to 0. In 3d indicator 2 is at the face x=0, 3 at y=0, * 4 at z=0. @@ -956,7 +985,9 @@ namespace GridGenerator * @param L Extension in @p z-direction (only used in 3d). * @param repetitions Number of subdivisions along the @p z-direction. * @param colorize Whether to assign different boundary indicators to - * different faces. The colors are given in lexicographic ordering for the + * different faces + * (see @ref GlossColorization "the glossary entry on colorization"). + * The colors are given in lexicographic ordering for the * flat faces (0 to 3 in 2d, 0 to 5 in 3d) plus the curved hole (4 in 2d, * and 6 in 3d). If @p colorize is set to false, then flat faces get the * number 0 and the hole gets number 1. -- 2.39.5