From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Fri, 6 Apr 2018 00:43:00 +0000 (-0600)
Subject: Add glossary entry on dimensions.
X-Git-Tag: v9.0.0-rc1~198^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07fce1b64267c1da5ae89ee55577574532561c95;p=dealii.git

Add glossary entry on dimensions.

While there, also update the glossary entry on concepts.
---

diff --git a/doc/doxygen/headers/concepts.h b/doc/doxygen/headers/concepts.h
index 3273aa01ee..308140769a 100644
--- a/doc/doxygen/headers/concepts.h
+++ b/doc/doxygen/headers/concepts.h
@@ -49,6 +49,27 @@
  * throughout deal.II. Specifically, in the example above, the
  * @ref ConceptNumber "Number concept" discussed below describes the
  * types that could be used as argument for the Vector class.
+ *
+ * Concepts have been proposed as a language
+ * extension to C++ for a long time already. They would allow us to
+ * describe that a class or function has certain properties in order
+ * to be a qualified template argument. For example, it would allow us
+ * to express in C++ code that the first argument to, say,
+ * GridTools::find_closest_vertex(), must have a type that represents
+ * an actual mesh -- which we can currently only describe in words,
+ * see below. Using C++ concepts would allow us to describe this in
+ * code and trying to call such a function with an object as first
+ * argument that is not, in fact, a mesh would yield a compiler error
+ * that makes the mismatch clear.
+ *
+ * Unfortunately, these proposals to C++ have never made it into any
+ * official C++ standard; they are proposed for C++20 however. We may
+ * start to use them once the vast majority of our users have
+ * compilers that support this standard.
+ *
+ * More information on the topic can be found at
+ * <a href="https://en.wikipedia.org/wiki/Concepts_(C%2B%2B)">this wikipedia page</a>.
+
  *
  * <dl>
  *
diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h
index 586dafabb8..bac9d73eb6 100644
--- a/doc/doxygen/headers/glossary.h
+++ b/doc/doxygen/headers/glossary.h
@@ -586,6 +586,47 @@
  * @ref Concepts for more information and a list of concepts in deal.II.
  * </dd>
  *
+ *
+ * <dt class="glossary">@anchor GlossDimension <b>Dimensions @p dim and @p spacedim</b></dt>
+ *
+ * <dd>
+ * Many classes and functions in deal.II have two template parameters,
+ * @p dim and @p spacedim. An example is the basic Triangulation class:
+ * @code
+ *   template <int dim, int spacedim=dim>
+ *   class Triangulation {...};
+ * @endcode
+ * In all of these contexts where you see @p dim and @p spacedim referenced,
+ * these arguments have the following meaning:
+ * - @p dim denotes the dimensionality of the mesh. For example, a mesh that
+ *   consists of line segments is one-dimensional and consequently corresponds
+ *   to `dim==1`. A mesh consisting of quadrilaterals then has `dim==2` and a
+ *   mesh of hexahedra has `dim==3`.
+ * - @p spacedim denotes the dimensionality of the space in which such a mesh
+ *   lives. Generally, one-dimensional meshes live in a one-dimensional space,
+ *   and similarly for two-dimensional and three-dimensional meshes that
+ *   subdivide two- and three-dimensional domains. Consequently, the
+ *   @p spacedim template argument has a default equal to @p dim. But this need
+ *   not be the case: For example, we may want to solve an equation for
+ *   sediment transport on the surface of the Earth. In this case, the domain
+ *   is the two-dimensional surface of the Earth (`dim==2`) that lives in a
+ *   three-dimensional coordinate system (`spacedim==3`).
+ * More generally, deal.II can be used to solve partial differential
+ * equations on <a href="https://en.wikipedia.org/wiki/Manifold">manifolds</a>
+ * that are embedded in higher dimensional space. In other words,
+ * these two template arguments need to satisfy `dim <= spacedim`,
+ * though in many applications one simply has `dim == spacedim`.
+ *
+ * Following the convention in geometry, we say that the "codimension" is
+ * defined as `spacedim-dim`. In other words, a triangulation consisting of
+ * quadrilaterals whose coordinates are three-dimensional (for which we
+ * would then use a `Triangulation<2,3>` object) has "codimension one".
+ *
+ * Examples of uses where these two arguments are not the same are shown in
+ * step-34, step-38, step-54.
+ * </dd>
+ *
+ *
  * <dt class="glossary">@anchor GlossDoF <b>Degree of freedom</b></dt>
  *
  * <dd> The term "degree of freedom" (often abbreviated as "DoF") is commonly