From c2addbfbb020880843652e067193952239abbd6f Mon Sep 17 00:00:00 2001 From: wolf Date: Fri, 15 Jul 2005 15:01:38 +0000 Subject: [PATCH] Improve documentation. git-svn-id: https://svn.dealii.org/trunk@11144 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/deal.II/include/dofs/dof_handler.h | 73 +++++++++++----------- deal.II/deal.II/include/fe/fe_values.h | 63 ++++++++++++------- deal.II/doc/news/changes.html | 8 +++ 3 files changed, 85 insertions(+), 59 deletions(-) diff --git a/deal.II/deal.II/include/dofs/dof_handler.h b/deal.II/deal.II/include/dofs/dof_handler.h index 30d68b5ba5..8efef09bd5 100644 --- a/deal.II/deal.II/include/dofs/dof_handler.h +++ b/deal.II/deal.II/include/dofs/dof_handler.h @@ -263,29 +263,27 @@ class DoFDimensionInfo<3> * Manage the distribution and numbering of the degrees of freedom for * non-multigrid algorithms. * - * We store a list of numbers for each vertex, line, quad, etc - * denoting the mapping between the degrees of freedom on this object - * and the global number of this degree of freedom. The numbers refer - * to the unconstrained degrees of freedom, i.e. constrained degrees - * of freedom are numbered in the same way as unconstrained ones. - * This leads to the fact that indices in global vectors and matrices - * also refer to all degrees of freedom and some kind of condensation - * is needed to restrict the systems of equations to the unconstrained - * degrees of freedom only. The actual layout of storage of the indices - * is described in the DoFLevel class documentation. + * For each vertex, line, quad, etc, we store a list of the indices of degrees + * of freedom living on this object. These indices refer to the unconstrained + * degrees of freedom, i.e. constrained degrees of freedom are numbered in the + * same way as unconstrained ones, and are only later eliminated. This leads + * to the fact that indices in global vectors and matrices also refer to all + * degrees of freedom and some kind of condensation is needed to restrict the + * systems of equations to the unconstrained degrees of freedom only. The + * actual layout of storage of the indices is described in the DoFLevel class + * documentation. * - * Finally it offers a starting point for the assemblage of the matrices - * by offering begin() and end() functions which return iterators - * to walk on the DoF structures as well as the triangulation data. - * These iterators work much like those described in the documentation - * of the Triangulation class and of the iterator classes themselved, - * but offer more functionality than pure triangulation iterators. The - * order in which dof iterators are presented by the ++ and @p -- operators - * is the same as that for the alike triangulation iterators. + * The class offers iterators to traverse all cells, in much the same way as + * the Triangulation class does. Using the begin() and end() functions (and + * all their companions, like begin_active(), begin_line(), etc, just as for + * the Triangulation class), one can obtain iterators to walk over cells, and + * query the degree of freedom structures as well as the triangulation data. + * These iterators are built on top of those of the Triangulation class, but + * offer the additional information on degrees of freedom functionality than + * pure triangulation iterators. The order in which dof iterators are + * presented by the ++ and -- operators is the same as that + * for the corresponding triangulation iterators. * - * This class also provides functions to create the sparsity patterns of - * global matrices as well as matrices living on (parts of) the boundary. - * * *

Distribution of indices for degrees of freedom

* @@ -304,27 +302,26 @@ class DoFDimensionInfo<3> * * This numbering implies very large bandwiths of the resulting matrices and * is thus vastly suboptimal for some solution algorithms. For this reason, - * the DoFRenumbering class offers the function @p renumber_dofs which reorders - * the dof numbering according to some scheme. See there for a discussion of - * the implemented algorithms. + * the DoFRenumbering class offers several algorithms to reorder the dof + * numbering according. See there for a discussion of the implemented + * algorithms. * * *

User defined renumbering schemes

* - * The DoFRenumbering class offers a number of renumbering - * schemes like the Cuthill-McKey scheme. Basically, the function sets - * up an array in which for each degree of freedom the index is stored - * which is to be assigned by the renumbering. Using this array, the - * renumber_dofs() function is called, which actually - * does the change from old DoF indices to the ones given in the - * array. In some cases, however, a user may want to compute her own - * renumbering order; in this case, allocate an array with one element - * per degree of freedom and fill it with the number that the - * respective degree of freedom shall be assigned. This number may, - * for example, be obtained by sorting the support points of the - * degrees of freedom in downwind direction. Then call the - * renumber_dofs(vector) with the array, which converts old - * into new degree of freedom indices. + * The DoFRenumbering class offers a number of renumbering schemes like the + * Cuthill-McKey scheme. Basically, the function sets up an array in which for + * each degree of freedom we store the new index this DoF should have after + * renumbering. Using this array, the renumber_dofs() function of the present + * class is called, which actually performs the change from old DoF indices to + * the ones given in the array. In some cases, however, a user may want to + * compute her own renumbering order; in this case, one can allocate an array + * with one element per degree of freedom and fill it with the number that the + * respective degree of freedom shall be assigned. This number may, for + * example, be obtained by sorting the support points of the degrees of + * freedom in downwind direction. Then call the + * renumber_dofs(vector) function with the array, which + * converts old into new degree of freedom indices. * * @ingroup dofs * @author Wolfgang Bangerth, 1998 diff --git a/deal.II/deal.II/include/fe/fe_values.h b/deal.II/deal.II/include/fe/fe_values.h index 5385212608..b32aeaf8ad 100644 --- a/deal.II/deal.II/include/fe/fe_values.h +++ b/deal.II/deal.II/include/fe/fe_values.h @@ -246,31 +246,42 @@ class FEValuesData /** - * FEValues, FEFaceValues and FESubfaceValues objects are programming - * interfaces to finite element and mapping classes on the one hand - * side, to cells and quadrature rules on the other side. The reason - * for their existence is possible optimization. Depending on the type - * of finite element and mapping, some values can be computed once on - * the unit cell. Others must be computed on each cell, but maybe - * computation of several values at the same time offers ways for - * optimization. Since this interlay may be complex and depends on the - * actual finite element, it cannot be left to the applications - * programmer. + * FEValues, FEFaceValues and FESubfaceValues objects are interfaces to finite + * element and mapping classes on the one hand side, to cells and quadrature + * rules on the other side. They allow to evaluate values or derivatives of + * shape functions at the quadrature points of a quadrature formula when + * projected by a mapping from the unit cell onto a cell in real space. The + * reason for this abstraction is possible optimization: Depending on the type + * of finite element and mapping, some values can be computed once on the unit + * cell. Others must be computed on each cell, but maybe computation of + * several values at the same time offers ways for optimization. Since this + * interlay may be complex and depends on the actual finite element, it cannot + * be left to the applications programmer. * - * FEValues, FEFaceValues and FESubfaceValues provide only data - * handling: computations are left to objects of type Mapping and - * FiniteElement. These provide functions get_*_data and - * fill_*_values which are called by the constructor and - * reinit functions of FEValues*, respectively. + * FEValues, FEFaceValues and FESubfaceValues provide only data handling: + * computations are left to objects of type Mapping and FiniteElement. These + * provide functions get_*_data and fill_*_values which are + * called by the constructor and reinit functions of + * FEValues*, respectively. * *

General usage

* - * Usually, an object of FEValues* is used in integration loops - * over all cells of a triangulation. To take full advantage of the - * optimization features, it should be constructed before the - * loop. Then, it must be re-initialized for each grid cell. This is - * like a magnifying glass being used to look at one item after the - * other. A typical piece of code looks like this: + * Usually, an object of FEValues* is used in integration loops over + * all cells of a triangulation (or faces of cells). To take full advantage of + * the optimization features, it should be constructed before the loop so that + * information that does not depend on the location and shape of cells can be + * computed once and for all (this includes, for example, the values of shape + * functions at quadrature points for the most common elements: we can + * evaluate them on the unit cell and they will be the same when mapped to the + * real cell). Then, in the loop over all cells, it must be re-initialized for + * each grid cell to compute that part of the information that changes + * depending on the actual cell (for example, the gradient of shape functions + * equals the gradient on the unit cell -- which can be computed once and for + * all -- times the Jacobian matrix of the mapping between unit and real cell, + * which needs to be recomputed for each cell). + * + * A typical piece of code, adding up local contributions to the Laplace + * matrix looks like this: * * @code * FEValues values (mapping, finite_element, quadrature, flags); @@ -279,10 +290,20 @@ class FEValuesData * ++cell) * { * values.reinit(cell); + * for (unsigned int q=0; qMember functions * diff --git a/deal.II/doc/news/changes.html b/deal.II/doc/news/changes.html index d9d92bb59f..11b2c7afda 100644 --- a/deal.II/doc/news/changes.html +++ b/deal.II/doc/news/changes.html @@ -241,6 +241,14 @@ inconvenience this causes.

base

    +

  1. + Removed: The write_multigrid flag in DataOutBase::DXFlags + has been removed, since it wasn't used anywhere. +
    + (WB, 2005/07/14) +

    +

  2. New: A function deal_II_exceptions::disable_abort_on_exception now allows -- 2.39.5