From 506dd94b339c502dcd5de6e49020aaae3e015e9e Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 25 May 2022 21:22:59 -0600 Subject: [PATCH] Better document ReferenceCell and the reference cell glossary entry. --- doc/doxygen/headers/glossary.h | 16 +++++++++++++--- include/deal.II/base/geometry_info.h | 6 +++++- include/deal.II/grid/reference_cell.h | 26 ++++++++++++++++++-------- 3 files changed, 36 insertions(+), 12 deletions(-) diff --git a/doc/doxygen/headers/glossary.h b/doc/doxygen/headers/glossary.h index 2df60159e8..7c849fa6eb 100644 --- a/doc/doxygen/headers/glossary.h +++ b/doc/doxygen/headers/glossary.h @@ -1705,9 +1705,19 @@ * * *
@anchor GlossReferenceCell Reference cell
- *
The hypercube [0,1]dim, on which all parametric finite - * element shape functions are defined. Many properties of the reference - * cell are described by the GeometryInfo class. + *
The finite element method is typically described by providing shape + * functions on a "reference cell" whose shape, along with the shape functions, + * is then mapped to the actual cells of the mesh. These reference cells are + * typically triangles or quadrilaterals for two-dimensional meshes; + * tetrahedra, hexahedra, wedges, or pyramids for three-dimensional meshes; + * and simple line segments in the one-dimensional case. + * + * Rather than hard-coding properties of the reference cell in all places + * where one wants to know about, say, the number of vertices of a cell, + * deal.II uses a single, central place to describe the properties of + * reference cells: The ReferenceCell class. In loops over the cells of a + * mesh, one typically asks for properties of these cells using the + * call `cell->reference_cell()`. *
* * diff --git a/include/deal.II/base/geometry_info.h b/include/deal.II/base/geometry_info.h index 674e501d57..4c778352d0 100644 --- a/include/deal.II/base/geometry_info.h +++ b/include/deal.II/base/geometry_info.h @@ -1438,8 +1438,12 @@ struct GeometryInfo<0> * This class provides dimension independent information to all topological * structures that make up the unit, or * @ref GlossReferenceCell "reference cell". - * This class has been + * That said, this class only describes information about hypercube reference + * cells (i.e., lines, quadrilaterals, or hexahedra), which historically + * were the only kinds of cells supported by deal.II. This is no longer the + * case today, and consequently this class has been * superseded by the ReferenceCell class -- see there for more information. + * The rest of this class's documentation is therefore partly historical. * * * It is the one central point in the library where information about the diff --git a/include/deal.II/grid/reference_cell.h b/include/deal.II/grid/reference_cell.h index 9d21ca8aa7..76fdec26e4 100644 --- a/include/deal.II/grid/reference_cell.h +++ b/include/deal.II/grid/reference_cell.h @@ -68,10 +68,19 @@ namespace internal /** - * A type that describes the kinds of reference cells that can be used. - * This includes quadrilaterals and hexahedra (i.e., "hypercubes"), - * triangles and tetrahedra (simplices), and the pyramids and wedges - * necessary when using mixed 3d meshes. + * A type that describes the kinds of reference cells that can be + * used. This includes quadrilaterals and hexahedra (i.e., + * "hypercubes"), triangles and tetrahedra (simplices), and the + * pyramids and wedges necessary when using mixed 3d meshes. This + * class then describes geometric, topological, and other kinds of + * information about these kinds of reference cells. This includes how + * many vertices or faces a certain kind of reference cell has + * (topological information), where these vertices lie, what the + * cell's volume or center of mass is (geometric information), and how + * to output these cells in various output formats or what appropriate + * quadrature rules are. The documentation of this class is separated + * into a number of sections to group the many member functions into + * different categories such as those mentioned above. * * Objects of this type should not be created in user code, and as a * consequence the class does not have a user-accessible constructor @@ -487,10 +496,11 @@ public: volume() const; /** - * Return the barycenter of the reference cell that corresponds - * to the current object. The function is not called `center()` because - * one can define the center of an object in a number of different ways - * whereas the barycenter of a reference cell $K$ is unambiguously defined as + * Return the barycenter (i.e., the center of mass) of the reference + * cell that corresponds to the current object. The function is not + * called `center()` because one can define the center of an object + * in a number of different ways whereas the barycenter of a + * reference cell $K$ is unambiguously defined as * @f[ * \mathbf x_K = \frac{1}{V} \int_K \mathbf x \; dx * @f] -- 2.39.5