* Base class for multigrid smoothers. Does nothing but defining the interface
* used by multigrid methods.
*
+ * The smoother interface provides two methods, a smooth() method and an
+ * apply() method. The multigrid preconditioner interfaces distinguish between
+ * the two for efficiency reasons: Upon entry to the preconditioner operations,
+ * the vector @p u needs to be set to zero and smoothing starts by a simple
+ * application of the smoother on the @p rhs vector. This method is provided by
+ * the apply() method of this class. It is the same as first setting @p u to
+ * zero and then calling smooth(), but for many classes the separate apply()
+ * interface is more efficient because it can skip one matrix-vector product.
+ *
+ * In the multigrid preconditioner interfaces, the apply() method is used for
+ * the pre-smoothing operation because the previous content in the solution
+ * vector needs to be overwritten for a new incoming residual. On the other
+ * hand, all subsequent operations need to smooth the content already present
+ * in the vector @p u given the right hand side, which is done by smooth().
+ *
* @author Guido Kanschat, 2002
*/
template <typename VectorType>
virtual void clear() = 0;
/**
- * Smoothing function. This is the function used in multigrid methods.
+ * Smoothing function that smooths the content in @p u given the right hand
+ * side vector @p rhs. This is the function used in multigrid methods.
*/
virtual void smooth (const unsigned int level,
VectorType &u,
const VectorType &rhs) const = 0;
/**
- * As opposed to the smoothing function, this function applies the action of
+ * As opposed to the smooth() function, this function applies the action of
* the smoothing, overwriting the previous content in the vector u. This
* function must be equivalent to the following code
* @code
* u = 0;
* smooth(level, u, rhs);
* @endcode
- * but can usually be implemented more efficiently than the former.
+ * but can usually be implemented more efficiently than the former. If a
+ * particular smoother does not override the apply() method, the default
+ * implementation as described here is used.
+ *
+ * In the multigrid preconditioner interfaces, the apply() method is used for
+ * the pre-smoothing operation because the previous content in the solution
+ * vector needs to be overwritten for a new incoming residual. On the other
+ * hand, all subsequent operations need to smooth the content already present
+ * in the vector @p u given the right hand side, which is done by smooth().
*/
virtual void apply (const unsigned int level,
VectorType &u,
/**
* The apply variant of smoothing, setting the vector u to zero before
- * calling the smooth function.
+ * calling the smooth function. This function is equivalent to the
+ * following code
+ * @code
+ * u = 0;
+ * smooth(level, u, rhs);
+ * @endcode
+ *
+ * In the multigrid preconditioner interfaces, the apply() method is used for
+ * the pre-smoothing operation because the previous content in the solution
+ * vector needs to be overwritten for a new incoming residual. On the other
+ * hand, all subsequent operations need to smooth the content already present
+ * in the vector @p u given the right hand side, which is done by smooth().
*/
virtual void apply (const unsigned int level,
VectorType &u,
/**
* The apply variant of smoothing, setting the vector u to zero before
- * calling the smooth function.
+ * calling the smooth function. This function is equivalent to the
+ * following code
+ * @code
+ * u = 0;
+ * smooth(level, u, rhs);
+ * @endcode
+ *
+ * In the multigrid preconditioner interfaces, the apply() method is used for
+ * the pre-smoothing operation because the previous content in the solution
+ * vector needs to be overwritten for a new incoming residual. On the other
+ * hand, all subsequent operations need to smooth the content already present
+ * in the vector @p u given the right hand side, which is done by smooth().
*/
virtual void apply (const unsigned int level,
VectorType &u,
/**
* The apply variant of smoothing, setting the vector u to zero before
- * calling the smooth function.
+ * calling the smooth function. This function is equivalent to the
+ * following code
+ * @code
+ * u = 0;
+ * smooth(level, u, rhs);
+ * @endcode
+ *
+ * In the multigrid preconditioner interfaces, the apply() method is used for
+ * the pre-smoothing operation because the previous content in the solution
+ * vector needs to be overwritten for a new incoming residual. On the other
+ * hand, all subsequent operations need to smooth the content already present
+ * in the vector @p u given the right hand side, which is done by smooth().
*/
virtual void apply (const unsigned int level,
VectorType &u,
/*@{*/
/**
- * Implementation of the multigrid method.
- *
- * @warning multigrid on locally refined meshes only works with
- * <b>discontinuous finite elements</b> right now. It is not clear, whether
- * the paradigm of local smoothing we use is applicable to continuous elements
- * with hanging nodes; in fact, most people you meet on conferences seem to
- * deny this.
+ * Implementation of the multigrid method. The implementation supports both
+ * continuous and discontinuous elements and follows the procedure described in
+ * the @ref mg_paper "multigrid paper by Janssen and Kanschat".
*
* The function which starts a multigrid cycle on the finest level is cycle().
* Depending on the cycle type chosen with the constructor (see enum Cycle),