From 2927d3a07d46e52d0fba532a31a4148a75426922 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Mon, 23 Jan 2006 21:51:41 +0000 Subject: [PATCH] Improve the documentation on the main page of the doxygen pages. git-svn-id: https://svn.dealii.org/trunk@12134 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/doxygen/headers/glossary.h | 40 ++++-- deal.II/doc/doxygen/headers/main.h | 192 ++++++++++++++++++++++--- 2 files changed, 203 insertions(+), 29 deletions(-) diff --git a/deal.II/doc/doxygen/headers/glossary.h b/deal.II/doc/doxygen/headers/glossary.h index 6c1b6ac5d8..f8ae81df6c 100644 --- a/deal.II/doc/doxygen/headers/glossary.h +++ b/deal.II/doc/doxygen/headers/glossary.h @@ -1,12 +1,19 @@ /** * @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. + * *
* - *
@anchor GlossActive Active cells
+ *
@anchor GlossActive Active cells
*
Mesh cells not refined any further in the hierarchy.
* - *
@anchor GlossGeneralizedSupport Generalized support points
+ * + *
@anchor GlossGeneralizedSupport Generalized support points
*
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 @@ -24,7 +31,8 @@ * and support points coincide. *
* - *
@anchor GlossInterpolation Interpolation with finite elements
+ * + *
@anchor GlossInterpolation Interpolation with finite elements
*
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 @@ -34,11 +42,13 @@ * f and store the result as entry i in the coefficient * vector. * - *
@anchor GlossLagrange Lagrange elements
+ * + *
@anchor GlossLagrange Lagrange elements
*
Finite elements based on Lagrangian interpolation at * @ref GlossSupport "support points".
* - *
@anchor GlossNodes Node values or node functionals
+ * + *
@anchor GlossNodes Node values or node functionals
* *
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 @@ -75,14 +85,17 @@ * Gauss points on edges(faces) and anisotropic Gauss points in the interior * * - *
@anchor GlossReferenceCell Reference cell
+ * + *
@anchor GlossReferenceCell Reference cell
*
The hypercube [0,1]dim, on which all parametric finite * element shape functions are defined.
* - *
@anchor GlossShape Shape functions
The restriction of + * + *
@anchor GlossShape Shape functions
The restriction of * the finite element basis functions to a single grid cell.
* - *
@anchor GlossSupport Support points
Support points are + * + *
@anchor GlossSupport Support points
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 @@ -102,16 +115,19 @@ * @ref GlossGeneralizedSupport "generalized support points". *
* - *
@anchor GlossTargetComponent Target component
When + * + *
@anchor GlossTargetComponent Target component
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.
- * - *
@anchor GlossUnitCell Unit cell
+ * + * + *
@anchor GlossUnitCell Unit cell
*
See @ref GlossReferenceCell "Reference cell".
* - *
@anchor GlossUnitSupport Unit support points
+ * + *
@anchor GlossUnitSupport Unit support points
*
@ref GlossSupport "Support points" on the reference cell, defined in * FiniteElementBase. For example, the usual Q1 element in 1d has support * points at x=0 and x=1 (and similarly, in higher diff --git a/deal.II/doc/doxygen/headers/main.h b/deal.II/doc/doxygen/headers/main.h index 287fd82f1c..bc597a295e 100644 --- a/deal.II/doc/doxygen/headers/main.h +++ b/deal.II/doc/doxygen/headers/main.h @@ -27,17 +27,50 @@ * @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: + * *
    * - *
  1. 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. - * - *
  2. Triangulation: - * - *
  3. Finite Element: Finite element classes describe the + *
  4. 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. + * + * 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. + * + * + *
  5. %Triangulation: 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. + * + * + *
  6. Finite Element: 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 @@ -47,12 +80,137 @@ * * The finite element classes are described in the @ref feall module. * - *
  7. Quadrature - *
  8. DoFHandler: - *
  9. Mapping: - *
  10. FEValues: - *
  11. Linear System: - *
  12. Linear Solver: - *
  13. Output: - *
+ * + *
  • %Quadrature: 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. + * + * + *
  • %DoFHandler: %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. + * + * + *
  • %Mapping: 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. + * + * + *
  • %FEValues: 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. + * + * + *
  • Linear System: 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. + * + * + *
  • Linear %Solver: 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. + * + * + *
  • Output: 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. + * + * + * + * 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). */ -- 2.39.5