]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Improve documentation.
authorwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 15 Jul 2005 15:01:38 +0000 (15:01 +0000)
committerwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 15 Jul 2005 15:01:38 +0000 (15:01 +0000)
git-svn-id: https://svn.dealii.org/trunk@11144 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/dofs/dof_handler.h
deal.II/deal.II/include/fe/fe_values.h
deal.II/doc/news/changes.html

index 30d68b5ba5527239a33ff4fce7b725875f938a08..8efef09bd5e73f5eea10549a43f054a179cac43f 100644 (file)
@@ -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 <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>
  *
@@ -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.
  *
  *
  * <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
index 538521260848d0f14beb30fcd760f690b72c49d1..b32aeaf8ad4d00d0a505b1ca7853800cee56d3a6 100644 (file)
@@ -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 <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);
@@ -279,10 +290,20 @@ class FEValuesData
  *      ++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>
  *
index d9d92bb59fcbf470e348690c37458e93e6c80266..11b2c7afdac9904aae58ef47e209c38fe49d574f 100644 (file)
@@ -241,6 +241,14 @@ inconvenience this causes.
 <h3>base</h3>
 
 <ol>
+  <li> <p>
+       Removed: The <code>write_multigrid</code> flag in <code
+       class="member">DataOutBase::DXFlags</code> 
+       has been removed, since it wasn't used anywhere.
+       <br>
+       (WB, 2005/07/14)
+       </p>
+
   <li> <p>
        New: A function <code class="member">
        deal_II_exceptions::disable_abort_on_exception</code> now allows

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.