]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Improve the documentation on the main page of the doxygen pages.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 23 Jan 2006 21:51:41 +0000 (21:51 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 23 Jan 2006 21:51:41 +0000 (21:51 +0000)
git-svn-id: https://svn.dealii.org/trunk@12134 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/doc/doxygen/headers/glossary.h
deal.II/doc/doxygen/headers/main.h

index 6c1b6ac5d8147233f501633ab7bc9bf8efd79f37..f8ae81df6c5204fc1dbd2038d0c13b5a2ee29ddc 100644 (file)
@@ -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.
+ *
  * <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
@@ -24,7 +31,8 @@
  * 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
index 287fd82f1c78f2eeab41ac6959edb1f0d87bf5da..bc597a295e6f0ba9b16ca9bb4c2a335a4a4b8c0e 100644 (file)
  * @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).
  */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.