From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 6 Jun 2017 19:21:14 +0000 (-0600)
Subject: Better explain the concept of material_ids.
X-Git-Tag: v9.0.0-rc1~1525^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=af2949dc686453cec2e58d75155bbb845e09ab99;p=dealii.git

Better explain the concept of material_ids.
---

diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index 36193541dc..e748ea84f4 100644
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -1168,8 +1168,24 @@
  * "material id". It is commonly used in problems with heterogeneous
  * coefficients to identify which part of the domain a cell is in and,
  * consequently, which value the coefficient should have on this particular
- * cell. The material id is inherited from mother to child cell upon mesh
- * refinement.
+ * cell. In practice, the material id of a cell
+ * is typically used to identify which cells belong to a particular part of
+ * the domain, e.g., when you have different materials (steel, concrete, wood)
+ * that are all part of the same domain. One would then usually query the
+ * material id associated with a cell during assembly of the bilinear form,
+ * and use it to determine (e.g., by table lookup, or a sequence of if-else
+ * statements) what the correct material coefficients would be for that cell.
+ *
+ * This material_id may be set upon construction of a triangulation (through
+ * the CellData data structure), or later through use of cell iterators. For a
+ * typical use of this functionality, see the step-28 tutorial program. The
+ * functions of the GridGenerator namespace typically set the material ID of
+ * all cells to zero. When reading a triangulation through the GridIn class,
+ * different input file formats have different conventions, but typically
+ * either explicitly specify the material id, or if they don't, then GridIn
+ * simply sets them to zero. Because the material of a cell is intended
+ * to pertain to a particular region of the domain, material ids are inherited
+ * by child cells from their parent upon mesh refinement.
  *
  * The material id is set and queried using the CellAccessor::material_id,
  * CellAccessor::set_material_id and CellAccessor::recursively_set_material_id
diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h
index 06017e04c7..ffcf1317da 100644
--- a/include/deal.II/grid/tria.h
+++ b/include/deal.II/grid/tria.h
@@ -817,19 +817,25 @@ namespace internal
  * <h3>Material and boundary information</h3>
  *
  * Each cell, face or edge stores information denoting the material or the
- * part of the boundary that an object belongs to. The material of a cell may
- * be used during matrix generation in order to implement different
- * coefficients in different parts of the domain. It is not used by functions
- * of the grid and dof handling libraries.
+ * part of the boundary that an object belongs to. The material id of a cell
+ * is typically used to identify which cells belong to a particular part of
+ * the domain, e.g., when you have different materials (steel, concrete, wood)
+ * that are all part of the same domain. One would then usually query the
+ * material id associated with a cell during assembly of the bilinear form,
+ * and use it to determine (e.g., by table lookup, or a sequence of if-else
+ * statements) what the correct material coefficients would be for that cell.
+ * See also @ref GlossMaterialId "this glossary entry".
  *
  * This material_id may be set upon construction of a triangulation (through
  * the CellData data structure), or later through use of cell iterators. For a
  * typical use of this functionality, see the step-28 tutorial program. The
  * functions of the GridGenerator namespace typically set the material ID of
- * all cells to zero. When reading a triangulation, the material id must be
- * specified in the input file (UCD format) or is otherwise set to zero.
- * Material IDs are inherited by child cells from their parent upon mesh
- * refinement.
+ * all cells to zero. When reading a triangulation through the GridIn class,
+ * different input file formats have different conventions, but typically
+ * either explicitly specify the material id, or if they don't, then GridIn
+ * simply sets them to zero. Because the material of a cell is intended
+ * to pertain to a particular region of the domain, material ids are inherited
+ * by child cells from their parent upon mesh refinement.
  *
  * Boundary indicators on lower dimensional objects (these have no material
  * id) indicate the number of a boundary component. These are used for two