]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Add a glossary entry on colorization.
authorDavid Wells <drwells@email.unc.edu>
Mon, 16 Jul 2018 00:26:08 +0000 (20:26 -0400)
committerDavid Wells <drwells@email.unc.edu>
Wed, 18 Jul 2018 03:18:10 +0000 (23:18 -0400)
doc/doxygen/headers/glossary.h
include/deal.II/grid/grid_generator.h

index e37bcf4336b3e7b60f2c8b4a553607d3600de1f8..3a4d72740a0d26917935b6f84b08bb3c2fb82178 100644 (file)
  * 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$:
  * @see @ref boundary "The module on boundaries"
  *
  *
+ * <dt class="glossary">@anchor GlossColorization <b>Colorization</b></dt>
+ * <dd><em>Colorization</em> is the process of marking certain parts of a
+ * Triangulation with different labels. The use of the word <em>color</em>
+ * comes from cartography, where countries on a map are made visually distinct
+ * from each other by assigning them different colors. Using the same term
+ * <em>coloring</em> is common in mathematics, even though we assign integers
+ * and not hues to different regions. deal.II refers to two processes as
+ * coloring:
+ *
+ * <ol>
+ *   <li> Most of the functions in the GridGenerator namespace take an optional
+ *   argument <code>colorize</code>. 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.</li>
+ *   <li> 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.</li>
+ * </ol>
+ * </dd>
+ *
  * <dt class="glossary">@anchor GlossComponent <b>Component</b></dt>
  *
  * <dd> When considering systems of equations in which the solution is not
  * 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.
 *
+ *
  * <i>Selecting components:</i>
  * Many functions allow you to restrict their operation to certain
  * vector components or blocks. For example, this is the case for
index 853c14534ebe65fdea50a1a9e807f0e3b85e312a..462dc9fa4f5e1ed72ef85a350b5e1d4134f6d102 100644 (file)
@@ -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 <code>true</code>, 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 <i>edges</i>, but only of <i>faces</i>, 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 <code>true</code>, 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 <code>true</code>, the boundary_ids of the boundary
+
+   * If the @p colorize (see
+   * @ref GlossColorization "the glossary entry on colorization")
+   * flag is <code>true</code>, 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 <code>true</code>, 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 <code>true</code>, 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 <code>true</code>, 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 <code>true</code>, 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.

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.