* 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 <tt>begin()</tt> and <tt>end()</tt> 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 <tt>++</tt> 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 <tt>++</tt> and <tt>--</tt> 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.
- *
*
* <h3>Distribution of indices for degrees of freedom</h3>
*
*
* 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.
*
*
* <h3>User defined renumbering schemes</h3>
*
- * 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
- * <tt>renumber_dofs(vector<unsigned int>)</tt> 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
+ * <tt>renumber_dofs(vector<unsigned int>)</tt> function with the array, which
+ * converts old into new degree of freedom indices.
*
* @ingroup dofs
* @author Wolfgang Bangerth, 1998
/**
- * 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 <tt>get_*_data</tt> and
- * <tt>fill_*_values</tt> which are called by the constructor and
- * <tt>reinit</tt> functions of <tt>FEValues*</tt>, respectively.
+ * FEValues, FEFaceValues and FESubfaceValues provide only data handling:
+ * computations are left to objects of type Mapping and FiniteElement. These
+ * provide functions <tt>get_*_data</tt> and <tt>fill_*_values</tt> which are
+ * called by the constructor and <tt>reinit</tt> functions of
+ * <tt>FEValues*</tt>, respectively.
*
* <h3>General usage</h3>
*
- * Usually, an object of <tt>FEValues*</tt> 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 <tt>FEValues*</tt> 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);
* ++cell)
* {
* values.reinit(cell);
+ * for (unsigned int q=0; q<quadrature.n_quadrature_points; ++q)
+ * for (unsigned int i=0; i<finite_element.dofs_per_cell; ++i)
+ * for (unsigned int j=0; j<finite_element.dofs_per_cell; ++j)
+ * A(i,j) += fe_values.shape_value(i,q) *
+ * fe_values.shape_value(j,q) *
+ * fe_values.JxW(q);
* ...
* }
* @endcode
*
+ * The individual functions used here are described below. Note that by
+ * design, the order of quadrature points used inside the FEValues object is
+ * the same as defined by the quadrature formula passed to the constructor of
+ * the FEValues object above.
*
* <h3>Member functions</h3>
*
projects / dealii-svn.git / commitdiff