/**
* @page DEALGlossary Glossary
*
+ * This glossary explains a few terms that are frequently used in the
+ * documentation of classes of deal.II. The glossary often only gives
+ * a microscopic view of a particular concept; if you struggle with
+ * the bigger picture, it may therefore also be worth to consult the
+ * global overview of classes on the main/@ref index page.
+ *
* <dl>
*
- * <dt>@anchor GlossActive Active cells</dt>
+ * <dt>@anchor GlossActive <b>Active cells</b></dt>
* <dd>Mesh cells not refined any further in the hierarchy.</dd>
*
- * <dt>@anchor GlossGeneralizedSupport Generalized support points</dt>
+ *
+ * <dt>@anchor GlossGeneralizedSupport <b>Generalized support points</b></dt>
* <dd>While @ref GlossSupport "support points" allow very simple interpolation
* into the finite element space, their concept is restricted to
* @ref GlossLagrange "Lagrange elements". For other elements, more general
* and support points coincide.
* </dd>
*
- * <dt>@anchor GlossInterpolation Interpolation with finite elements</dt>
+ *
+ * <dt>@anchor GlossInterpolation <b>Interpolation with finite elements</b></dt>
* <dd>The purpose of interpolation with finite elements is computing
* a vector of coefficients representing a finite element function,
* such that the @ref GlossNodes "node values" of the original
* <i>f</i> and store the result as entry <i>i</i> in the coefficient
* vector.
*
- * <dt>@anchor GlossLagrange Lagrange elements</dt>
+ *
+ * <dt>@anchor GlossLagrange <b>Lagrange elements</b></dt>
* <dd>Finite elements based on Lagrangian interpolation at
* @ref GlossSupport "support points".</dd>
*
- * <dt>@anchor GlossNodes Node values or node functionals</dt>
+ *
+ * <dt>@anchor GlossNodes <b>Node values or node functionals</b></dt>
*
* <dd>It is customary to define a FiniteElement as a pair consisting
* of a local function space and a set of node values $N_i$ on the
* <td>Gauss points on edges(faces) and anisotropic Gauss points in the interior</td></tr>
* </table>
*
- * <dt>@anchor GlossReferenceCell Reference cell</dt>
+ *
+ * <dt>@anchor GlossReferenceCell <b>Reference cell</b></dt>
* <dd>The hypercube [0,1]<sup>dim</sup>, on which all parametric finite
* element shape functions are defined.</dd>
*
- * <dt>@anchor GlossShape Shape functions</dt> <dd>The restriction of
+ *
+ * <dt>@anchor GlossShape <b>Shape functions</b></dt> <dd>The restriction of
* the finite element basis functions to a single grid cell.</dd>
*
- * <dt>@anchor GlossSupport Support points</dt> <dd>Support points are
+ *
+ * <dt>@anchor GlossSupport <b>Support points</b></dt> <dd>Support points are
* by definition those points $p_i$, such that for the shape functions
* $v_j$ holds $v_j(p_i) = \delta_{ij}$. Therefore, a finite element
* interpolation can be defined uniquely by the values in the support
* @ref GlossGeneralizedSupport "generalized support points".
* </dd>
*
- * <dt>@anchor GlossTargetComponent Target component</dt> <dd>When
+ *
+ * <dt>@anchor GlossTargetComponent <b>Target component</b></dt> <dd>When
* vectors and matrices are grouped into blocks by component, it is
* often desirable to collect several of the original components into
* a single one. This could be for instance, grouping the velocities
* of a Stokes system into a single block.</dd>
- *
- * <dt>@anchor GlossUnitCell Unit cell</dt>
+ *
+ *
+ * <dt>@anchor GlossUnitCell <b>Unit cell</b></dt>
* <dd>See @ref GlossReferenceCell "Reference cell".</dd>
*
- * <dt>@anchor GlossUnitSupport Unit support points</dt>
+ *
+ * <dt>@anchor GlossUnitSupport <b>Unit support points</b></dt>
* <dd>@ref GlossSupport "Support points" on the reference cell, defined in
* FiniteElementBase. For example, the usual Q1 element in 1d has support
* points at <tt>x=0</tt> and <tt>x=1</tt> (and similarly, in higher
* @image html collaboration.png "Collaboration diagram for the most important groups of classes in deal.II"
* @image latex collaboration.eps "Collaboration diagram for the most important groups of classes in deal.II" width=.9\textwidth
*
- * This classification of groups can be explained as follows:
+ * Here is a guide to this classification of groups, as well as links
+ * to the documentation pertaining to each of them:
+ *
* <ol>
*
- * <li> Unit cell: deal.II supports only hypercubes as unit cells, i.e. the
- * unit cell [0,1] in 1d, the unit square [0,1]^2 in 2d, and the unit cube
- * [0,1]^3 in 3d. We do not support triangles, tetrahedra, pyramids, or
- * prisms.
- *
- * <li> Triangulation:
- *
- * <li> Finite Element: Finite element classes describe the
+ * <li> <b>Unit cell</b>: deal.II supports only hypercubes as unit
+ * cells, i.e. the unit cell [0,1] in 1d, the unit square [0,1]^2 in
+ * 2d, and the unit cube [0,1]^3 in 3d. We do not support triangles,
+ * tetrahedra, pyramids, or prisms.
+ *
+ * Inside the library, most properties of unit cells such as the
+ * number of vertices per cell, ordering of faces, or direction of
+ * edges, are explicitly described in the GeometryInfo class. This
+ * avoids the use of implicit assumptions in many places of the
+ * code.
+ *
+ *
+ * <li> <b>%Triangulation</b>: Triangulations are collections of
+ * cells that have the general shape derived from the unit cell. The
+ * only thing a triangulation stores are the geometric and topologic
+ * properties of a mesh: where are vertices located, and how are
+ * these vertices connected to cells. A triangulation doesn't know
+ * anything about the finite elements that you may want to used on
+ * this mesh, and a triangulation does not even know anything about
+ * the shape of its cells: in 2d it only knows that a cell has four
+ * vertices (and in 3d that it has 8 vertices), but there are no
+ * provisions that the mapping from the unit cell to a particular
+ * cell in the triangulation is well-behaved in any way: it really
+ * only knows about the geometric location of vertices and their
+ * topological connection.
+ *
+ * The properties and data of triangulations are almost always
+ * queried through loops over all cells, or all faces of cells. Most
+ * of the knowledge about a mesh is therefore hidden behind
+ * @em iterators, i.e. pointer-like structures that one can
+ * iterate from one cell to the next, and that one can ask for
+ * information about the cell it presently points to.
+ *
+ * The classes that describe triangulations and cells are located
+ * and documented in the @ref grid module. Iterators are described
+ * in the @ref Iterators module.
+ *
+ *
+ * <li> <b>Finite Element</b>: Finite element classes describe the
* properties of a finite element space as defined on the unit
* cell. This includes, for example, how many degrees of freedom are
* located at vertices, on lines, or in the interior of cells. In
*
* The finite element classes are described in the @ref feall module.
*
- * <li> Quadrature
- * <li> DoFHandler:
- * <li> Mapping:
- * <li> FEValues:
- * <li> Linear System:
- * <li> Linear Solver:
- * <li> Output:
- * </ol>
+ *
+ * <li> <b>%Quadrature</b>: As with finite elements, quadrature
+ * objects are defined on the unit cell. They only describe the
+ * location of quadrature points on the unit cell, and the weights
+ * of quadrature points thereon.
+ *
+ * The documentation of the classes describing particular quadrature
+ * formulas is found in the @ref Quadrature module.
+ *
+ *
+ * <li> <b>%DoFHandler</b>: %DoFHandler objects are the confluence
+ * of triangulations and finite elements: the finite element class
+ * describes how many degrees of freedom it needs per vertex, line,
+ * or cell, and the DoFHandler class allocates this space so that
+ * each vertex, line, or cell of the triangulation has the correct
+ * number of them. It also gives them a global numbering.
+ *
+ * Just as with triangulation objects, most operations on
+ * DoFHandlers is done by looping over all cells and doing something
+ * on each or a subset of them. The interfaces of the two classes is
+ * therefore rather similar: they allow to get iterators to the
+ * first and last cell (or face, or line, etc) and offer information
+ * through these iterators. The information that can be gotten from
+ * these iterators is the geometric and topological information that
+ * can already be gotten from the triangulation iterators (they are
+ * in fact derived classes) as well as things like the global
+ * numbers of the degrees of freedom on the present cell. On can
+ * also ask an iterator to extract the values corresponding to the
+ * degrees of freedom on the present cell from a data vector that
+ * stores values for all degrees of freedom associated with a
+ * triangulation.
+ *
+ * It is worth noting that, just as triangulations, DoFHandler
+ * classes do not know anything about the mapping from the unit cell
+ * to its individual cells. It is also ignorant of the shape
+ * functions that correspond to the degrees of freedom it manages:
+ * all it knows is that there are, for example, 2 degrees of freedom
+ * for each vertex and 4 per cell. Nothing about their specifics is
+ * relevant to the DoFHandler class.
+ *
+ * The DoFHandler class and its associates are described in the @ref
+ * dofs module. In addition, there are specialized versions that can
+ * handle multilevel and hp discretizations. These are described in
+ * the @ref mg and @ref hp modules.
+ *
+ *
+ * <li> <b>%Mapping</b>: The next step in a finite element program
+ * is that one would want to compute matrix and right hand side
+ * entries or other quantities on each cell of a triangulation,
+ * using the shape functions of a finite element and quadrature
+ * points defined by a quadrature rule. To this end, it is necessary
+ * to map the shape functions, quadrature points, and quadrature
+ * weights from the unit cell to each cell of a triangulation. This
+ * is not directly done by, but facilitated by the Mapping and
+ * derived classes: they describe how to map points from unit to
+ * real space and back, as well as provide gradients of this
+ * derivative and Jacobian determinants.
+ *
+ * These classes are all described in the @ref mapping module.
+ *
+ *
+ * <li> <b>%FEValues</b>: The next step is to actually take a finite
+ * element and evaluate its shape functions and their gradients at
+ * the points defined by a quadrature formula when mapped to the
+ * real cell. This is the realm of the FEValues class and siblings:
+ * in a sense, they offer a point-wise view of the finite element
+ * function space.
+ *
+ * This seems restrictive: in mathematical analysis, we always write
+ * our formulas in terms of integrals over cells, or faces of cells,
+ * involving the finite element shape functions. One would therefore
+ * think that it is necessary to describe finite element spaces as
+ * continuous spaces. However, in practice, this is not necessary:
+ * all integrals are in actual computations replaced by
+ * approximations using quadrature formula, and what is therefore
+ * really only necessary is the ability to evaluate shape functions
+ * at a finite number of given locations inside a domain. The
+ * FEValues classes offer exactly this information: Given finite
+ * element, quadrature, and mapping objects, they compute the
+ * restriction of a continuous function space (as opposed to
+ * discrete, not as opposed to discontinuous) to a discrete number
+ * of points.
+ *
+ * There are a number of objects that can do this: FEValues for
+ * evaluation on cells, FEFaceValues for evaluation on faces of
+ * cells, and FESubfaceValues for evaluation on parts of faces of
+ * cells. All these classes are described in the @ref feaccess
+ * module.
+ *
+ *
+ * <li> <b>Linear System</b>: One one knows how to evaluate the
+ * values and gradients of shape functions on individual cells using
+ * FEValues and friends, and knows how to get the global numbers of
+ * the degrees of freedom on a cell using the DoFHandler iterators,
+ * one uses the bilinear form of the problem to assemble the system
+ * matrix (and right hand side) of the linear system from which we
+ * will determine the solution of our problem.
+ *
+ * To do this, we need to have classes that store and manage the
+ * entries of matrices and vectors. deal.II comes with a whole set
+ * of classes for this purpose, as well as with interfaces to other
+ * software packages that offer similar functionality. Documentation
+ * to this end can be found in the @ref LAC module.
+ *
+ *
+ * <li> <b>Linear %Solver</b>: In order to determine the solution of
+ * a finite-dimensional, linear system of equations, one needs
+ * linear solvers. In finite element applications, they are
+ * frequently iterative, but sometimes one may also want to use
+ * direct or sparse direct solvers. deal.II has quite a number of
+ * these. They are documented in the @ref Solvers module.
+ *
+ *
+ * <li> <b>Output</b>: Finally, once one has obtained a solution of
+ * a finite element problem on a given triangulation, one will often
+ * want to postprocess it using a visualization program. This
+ * library doesn't do that by itself, but rather generates output
+ * files in a variety of graphics formats understood by widely
+ * distributed visualization tools.
+ *
+ * A description of the classes that do so is given in the @ref
+ * output module.
+ *
+ * </ol>
+ *
+ * In addition, deal.II has a number of groups of classes that go
+ * beyond the ones listed here. They pertain to more refined concepts
+ * of the hierarchy presented above, or to tangential aspects like
+ * handling of input and output that are not necessarily specific to
+ * finite element programs, but appear there as well. These classes
+ * are all listed in the Classes and Namespaces views reachable from
+ * the menu bar at the top of this page, and are also grouped into
+ * modules of their own (see the Modules view also in the menu bar).
*/