From: Wolfgang Bangerth 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=refs%2Fpull%2F6175%2Fhead;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 + * this wikipedia page. + * *
* 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. * * + * + *
@anchor GlossDimension Dimensions @p dim and @p spacedim
+ * + *
+ * 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 + * 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 manifolds + * 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. + *
+ * + * *
@anchor GlossDoF Degree of freedom
* *
The term "degree of freedom" (often abbreviated as "DoF") is commonly