From: Wolfgang Bangerth Date: Fri, 15 Apr 2016 04:37:36 +0000 (-0500) Subject: Update documentation of MGLevelObject. X-Git-Tag: v8.5.0-rc1~1103^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2509%2Fhead;p=dealii.git Update documentation of MGLevelObject. --- diff --git a/include/deal.II/base/mg_level_object.h b/include/deal.II/base/mg_level_object.h index 3d797e33cc..5d8f97b884 100644 --- a/include/deal.II/base/mg_level_object.h +++ b/include/deal.II/base/mg_level_object.h @@ -25,13 +25,20 @@ DEAL_II_NAMESPACE_OPEN /** - * An array with an object for each level. The purpose of this class is - * mostly to store objects and allow access by level number, even if the lower - * levels are not used and therefore have no object at all; this is done by + * This class represents an array with one object for each used level of a + * multilevel hierarchy, for example for use in the multigrid algorithms. + * In contrast to just a generic std::vector, this class allows + * to store objects only between some minimal and maximal index (=level), + * as one often wants to run a multilevel algorithm only on a subset of + * the levels of a mesh (e.g., because the second or third coarsest level is + * already small enough that it is cheaper to run a direct solver there, + * rather than recurse to even coarser levels). Despite storing objects only + * for these "interesting" levels, the class allows indexing simply by + * level. Internally, this is of course done by * simply shifting the given index by the minimum level we have stored. * - * In most cases, the objects which are stored on each levels, are either - * matrices or vectors. + * In a typical use case for this class, the objects stored on each level + * are either matrices or vectors. * * @ingroup mg * @ingroup data @@ -42,8 +49,23 @@ class MGLevelObject : public Subscriptor { public: /** - * Constructor allowing to initialize the number of levels. By default, the - * object is created empty. + * Constructor. Create a multilevel object with given minimal and + * maximal level, and allocate storage for objects on + * maxlevel-minlevel+1 levels. + * + * @note Unlike in many other places of the library, the two arguments + * here do not denote the first level and last-plus-one level, but indeed + * an inclusive range of levels for which to allocate storage + * for level objects. Consequently, the defaults for the two arguments + * will create an array with one level object, rather than an empty + * array. + * + * @param[in] minlevel The lowest level for which to provision memory + * for level objects. + * @param[in] maxlevel The highest level for which to provision memory + * for level objects. + * + * @pre minlevel <= maxlevel */ MGLevelObject (const unsigned int minlevel = 0, const unsigned int maxlevel = 0); @@ -54,20 +76,32 @@ public: Object &operator[] (const unsigned int level); /** - * Access object on level @p level. Constant version. + * Access object on level @p level. + * + * This function can be called on a @p const object, and + * consequently returns a @p const reference. */ const Object &operator[] (const unsigned int level) const; /** * Delete all previous contents of this object and reset its size according * to the values of @p new_minlevel and @p new_maxlevel. + * + * @param[in] new_minlevel The lowest level for which to provision memory + * for level objects. + * @param[in] new_maxlevel The highest level for which to provision memory + * for level objects. + * + * @pre minlevel <= maxlevel */ void resize (const unsigned int new_minlevel, const unsigned int new_maxlevel); /** - * Call operator = (s) on all objects stored by this object. This - * is particularly useful for e.g. Object==Vector@ + * Call operator = (s) on all objects stored by this object. + * This clearly requires that the objects stored on each level allow for + * this operation. This is, in particular, true for vectors and matrices + * if @p d is zero, thereby zeroing out all vector or matrix entries. */ MGLevelObject &operator = (const double d); @@ -79,12 +113,12 @@ public: void clear(); /** - * Coarsest level for multigrid. + * The coarsest level for which this class stores a level object. */ unsigned int min_level () const; /** - * Finest level for multigrid. + * The highest level for which this class stores a level object. */ unsigned int max_level () const;