From: Guido Kanschat Date: Thu, 16 Jul 2009 09:09:44 +0000 (+0000) Subject: straighten documentation X-Git-Tag: v8.0.0~7468 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e6d00e21a2c0639dd9e8bd3bfa283a0af7db9963;p=dealii.git straighten documentation git-svn-id: https://svn.dealii.org/trunk@19093 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/lac/include/lac/solver_gmres.h b/deal.II/lac/include/lac/solver_gmres.h index 9ffe75872a..66f547090e 100644 --- a/deal.II/lac/include/lac/solver_gmres.h +++ b/deal.II/lac/include/lac/solver_gmres.h @@ -2,7 +2,7 @@ // $Id$ // Version: $Name$ // -// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 by the deal.II authors +// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 by the deal.II authors // // This file is subject to QPL and may not be distributed // without copyright and license information. Please refer @@ -119,58 +119,46 @@ namespace internal * Minimal Residual Method. The stopping criterion is the norm of the * residual. * - * You have to give the maximum number of temporary vectors to the - * constructor which are to be used to do the orthogonalization. If - * the number of iterations needed to solve the problem to the given - * criterion, an intermediate solution is computed and a restart is - * performed. If you don't want to use the restarted method, you can - * limit the number of iterations (stated in the @p SolverControl - * object given to the constructor) to be below the number of - * temporary vectors minus three. Note the subtraction, which is due - * to the fact that three vectors are used for other purposes, so the - * number of iterations before a restart occurs is less by three than - * the total number of temporary vectors. If the size of the matrix is - * smaller than the maximum number of temporary vectors, then fewer - * vectors are allocated since GMRES can then be used as a direct - * solver. + * The AdditionalData structure contains the number of temporary + * vectors used. The size of the Arnoldi basis is this number minus + * three. Addinitonally, it allows you to choose bet right or left + * preconditioning. The default is left preconditioning. Finally it + * includes a flag indicating whether or not the default residual is + * used as stopping criterion. + + *

Left versus right preconditioning

* - * Note that restarts don't compensate temporary vectors very well, - * i.e. giving too few temporary vectors will increase the necessary - * iteration steps greatly; it is not uncommon that you will need more - * iterations than there are degrees of freedom in your solution - * vector, if the number of temporary vectors is lower than the size - * of the vector, even though GMRES is an exact solver if a sufficient - * number of temporary vectors is given. You should therefore always - * give as many temporary vectors as you can, unless you are limited - * by the available memory; only then should you start to trade - * computational speed against memory. One of the few other - * possibilities is to use a good preconditioner. + * @p AdditionalData allows you to choose between left and right + * preconditioning. As expected, this switches between solving for the + * systems P-1A and AP-1, + * respectively. * - * Like all other solver classes, this class has a local structure - * called @p AdditionalData which is used to pass additional - * parameters to the solver, like the number of temporary vectors for - * example. We use this additional structure instead of passing these - * values directly to the constructor because this makes the use of - * the @p SolverSelector and other classes much easier and guarantees - * that these will continue to work even if number or type of the - * additional parameters for a certain solver changes. + * A second consequence is the type of residual which is used to + * measure convergence. With left preconditioning, this is the + * preconditioned residual, while with right preconditioning, + * it is the residual of the unpreconditioned system. * - * For the GMRes method, the @p AdditionalData structure contains the number - * of temporary vectors as commented upon above. By default, the number of - * these vectors is set to 30. The @p AdditionalData also containes a flag - * indicating the use of right or left preconditioning. The default is left - * preconditioning. Finally it includes a flag indicating whether or not the - * default residual is used as stopping criterion. By default, the left - * preconditioned GMRes uses the preconditioned residual and the right - * preconditioned GMRes uses the normal, i.e. unpreconditioned, residual as - * stopping criterion. If the @p use_default_residual flag is @p false, the - * left preconditioned GMRes uses as stopping criterion the unpreconditioned - * residual and the right preconditioned GMRes the preconditioned - * residual. But be aware that the non-default residuals are not automatically - * computed by the GMRes method but need to be computed in addition. This - * (especially for the left preconditioned GMRes) might lead to a significant - * loss in the solver performance. Therefore, the user should set - * use_default_residual=false only for debugging/testing purposes. + * Optionally, this behavior can be overridden by using the flag + * AdditionalData::use_default_residual. A true value refers + * to the behavior described in the previous paragraph, while + * false reverts it. Be aware though that additional + * residuals have to be computed in this case, impeding the overall + * performance of the solver. + * + *

The size of the Arnoldi basis

+ * + * The maximal basis size is controlled by + * AdditionalData::max_n_tmp_vectors, and it is this number minus 2. + * If the number of iteration steps exceeds this number, all basis + * vectors are discarded and the iteration starts anew from the + * approximation obtained so far. + * + * Note that the minimizing property of GMRes only pertains to the + * Krylov space spanned by the Arnoldi basis. Therefore, restarted + * GMRes is not minimizing anymore. The choice of the basis + * length is a trade-off between memory consumption and convergence + * speed, since a longer basis means minimization over a larger + * space. * * For the requirements on matrices and vectors in order to work with * this class, see the documentation of the Solver base class. @@ -192,11 +180,10 @@ class SolverGMRES : public Solver * Constructor. By default, set the * number of temporary vectors to 30, * i.e. do a restart every - * approximately 30 iterations. Also + * 28 iterations. Also * set preconditioning from left and * the residual of the stopping - * criterion to the default residual - * (cf. class documentation). + * criterion to the default residual. */ AdditionalData (const unsigned int max_n_tmp_vectors = 30, const bool right_preconditioning = false, @@ -204,20 +191,33 @@ class SolverGMRES : public Solver /** * Maximum number of - * tmp vectors. + * temporary vectors. This + * parameter controls the + * size of the Arnoldi basis, + * which for historical + * reasons is + * #max_n_tmp_vectors-2. */ unsigned int max_n_tmp_vectors; /** * Flag for right * preconditioning. + * + * @note Change between left + * and right preconditioning + * will also change the way + * residuals are + * evaluated. See the + * corresponding section in + * the SolverGMRES. */ bool right_preconditioning; /** * Flag for the default - * residual that is used as - * stopping criterion. + * residual that is used to + * measure convergence. */ bool use_default_residual; };