Improve error message and give some guidance on what to do.

git-svn-id: https://svn.dealii.org/trunk@33060 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/include/deal.II/lac/solver_control.h b/deal.II/include/deal.II/lac/solver_control.h
index 80d998fd86700e83846f8415d103795311a6d432..31672d3f8f2272b499bc5e3b81ae5fd1db105dcb 100644 (file)
--- a/deal.II/include/deal.II/lac/solver_control.h
+++ b/deal.II/include/deal.II/lac/solver_control.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 1998 - 2013 by the deal.II authors
+// Copyright (C) 1998 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -106,7 +106,22 @@ public:
     virtual void print_info (std::ostream &out) const
     {
       out << "Iterative method reported convergence failure in step "
-          << last_step << " with residual " << last_residual << std::endl;
+          << last_step << ". The residual in the last step was " << last_residual
+         << ".\n\n"
+         << "This error message can indicate that you have simply not allowed "
+         << "a sufficiently large number of iterations for your iterative solver "
+         << "to converge. This often happens when you increase the size of your "
+         << "problem. In such cases, the last residual will likely still be very "
+         << "small, and you can make the error go away by increasing the allowed "
+         << "number of iterations when setting up the SolverControl object that "
+         << "determines the maximal number of iterations you allow."
+         << "\n\n"
+         << "The other situation where this error may occur is when your matrix "
+         << "is not invertible (e.g., your matrix has a null-space), or if you "
+         << "try to apply the wrong solver to a matrix (e.g., using CG for a "
+         << "matrix that is not symmetric or not positive definite). In these "
+         << "cases, the residual in the last iteration is likely going to be large."
+         << std::endl;
     }
 
     /**