Reference documentation for deal.II version Git 7026f387cc 2019-10-15 14:19:01 -0400
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
solver_control.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2018 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE.md at
12 // the top level directory of deal.II.
13 //
14 // ---------------------------------------------------------------------
15 
16 #ifndef dealii_solver_control_h
17 #define dealii_solver_control_h
18 
19 
20 #include <deal.II/base/config.h>
21 
22 #include <deal.II/base/subscriptor.h>
23 
24 #include <vector>
25 
26 DEAL_II_NAMESPACE_OPEN
27 
28 #ifndef DOXYGEN
29 class ParameterHandler;
30 #endif
31 
34 
67 class SolverControl : public Subscriptor
68 {
69 public:
74  enum State
75  {
77  iterate = 0,
82  };
83 
84 
85 
97  {
98  public:
99  NoConvergence(const unsigned int last_step, const double last_residual)
100  : last_step(last_step)
101  , last_residual(last_residual)
102  {}
103 
104  virtual ~NoConvergence() noexcept override = default;
105 
106  virtual void
107  print_info(std::ostream &out) const override
108  {
109  out
110  << "Iterative method reported convergence failure in step " << last_step
111  << ". The residual in the last step was " << last_residual << ".\n\n"
112  << "This error message can indicate that you have simply not allowed "
113  << "a sufficiently large number of iterations for your iterative solver "
114  << "to converge. This often happens when you increase the size of your "
115  << "problem. In such cases, the last residual will likely still be very "
116  << "small, and you can make the error go away by increasing the allowed "
117  << "number of iterations when setting up the SolverControl object that "
118  << "determines the maximal number of iterations you allow."
119  << "\n\n"
120  << "The other situation where this error may occur is when your matrix "
121  << "is not invertible (e.g., your matrix has a null-space), or if you "
122  << "try to apply the wrong solver to a matrix (e.g., using CG for a "
123  << "matrix that is not symmetric or not positive definite). In these "
124  << "cases, the residual in the last iteration is likely going to be large."
125  << std::endl;
126  }
127 
131  const unsigned int last_step;
132 
136  const double last_residual;
137  };
138 
139 
140 
152  SolverControl(const unsigned int n = 100,
153  const double tol = 1.e-10,
154  const bool log_history = false,
155  const bool log_result = true);
156 
161  virtual ~SolverControl() override = default;
162 
166  static void
168 
172  void
174 
192  virtual State
193  check(const unsigned int step, const double check_value);
194 
198  State
199  last_check() const;
200 
204  double
205  initial_value() const;
206 
211  double
212  last_value() const;
213 
217  unsigned int
218  last_step() const;
219 
223  unsigned int
224  max_steps() const;
225 
229  unsigned int
230  set_max_steps(const unsigned int);
231 
237  void
238  set_failure_criterion(const double rel_failure_residual);
239 
244  void
246 
250  double
251  tolerance() const;
252 
256  double
257  set_tolerance(const double);
258 
262  void
264 
268  const std::vector<double> &
269  get_history_data() const;
270 
276  double
277  average_reduction() const;
284  double
285  final_reduction() const;
286 
292  double
293  step_reduction(unsigned int step) const;
294 
298  void
299  log_history(const bool);
300 
304  bool
305  log_history() const;
306 
310  unsigned int
311  log_frequency(unsigned int);
312 
316  void
317  log_result(const bool);
318 
322  bool
323  log_result() const;
324 
331 
332 protected:
336  unsigned int maxsteps;
337 
341  double tol;
342 
347 
351  double initial_val;
352 
356  double lvalue;
357 
361  unsigned int lstep;
362 
368 
373 
381 
386 
390  unsigned int m_log_frequency;
391 
398 
403 
410  std::vector<double> history_data;
411 };
412 
413 
428 {
429 public:
435  ReductionControl(const unsigned int maxiter = 100,
436  const double tolerance = 1.e-10,
437  const double reduce = 1.e-2,
438  const bool log_history = false,
439  const bool log_result = true);
440 
446 
452  operator=(const SolverControl &c);
453 
458  virtual ~ReductionControl() override = default;
459 
463  static void
465 
469  void
471 
477  virtual State
478  check(const unsigned int step, const double check_value) override;
479 
483  double
484  reduction() const;
485 
489  double
490  set_reduction(const double);
491 
492 protected:
496  double reduce;
497 
502  double reduced_tol;
503 };
504 
518 {
519 public:
524  IterationNumberControl(const unsigned int maxiter = 100,
525  const double tolerance = 1e-12,
526  const bool log_history = false,
527  const bool log_result = true);
528 
534 
541  operator=(const SolverControl &c);
542 
547  virtual ~IterationNumberControl() override = default;
548 
554  virtual State
555  check(const unsigned int step, const double check_value) override;
556 };
557 
558 
573 {
574 public:
581  ConsecutiveControl(const unsigned int maxiter = 100,
582  const double tolerance = 1.e-10,
583  const unsigned int n_consecutive_iterations = 2,
584  const bool log_history = false,
585  const bool log_result = false);
586 
592 
599  operator=(const SolverControl &c);
600 
605  virtual ~ConsecutiveControl() override = default;
606 
611  virtual State
612  check(const unsigned int step, const double check_value) override;
613 
614 protected:
620 
625 };
626 
628 //---------------------------------------------------------------------------
629 
630 #ifndef DOXYGEN
631 
632 inline unsigned int
634 {
635  return maxsteps;
636 }
637 
638 
639 
640 inline unsigned int
641 SolverControl::set_max_steps(const unsigned int newval)
642 {
643  unsigned int old = maxsteps;
644  maxsteps = newval;
645  return old;
646 }
647 
648 
649 
650 inline void
651 SolverControl::set_failure_criterion(const double rel_failure_residual)
652 {
653  relative_failure_residual = rel_failure_residual;
654  check_failure = true;
655 }
656 
657 
658 
659 inline void
661 {
663  failure_residual = 0;
664  check_failure = false;
665 }
666 
667 
668 
669 inline double
671 {
672  return tol;
673 }
674 
675 
676 
677 inline double
678 SolverControl::set_tolerance(const double t)
679 {
680  double old = tol;
681  tol = t;
682  return old;
683 }
684 
685 
686 inline void
687 SolverControl::log_history(const bool newval)
688 {
689  m_log_history = newval;
690 }
691 
692 
693 
694 inline bool
696 {
697  return m_log_history;
698 }
699 
700 
701 inline void
702 SolverControl::log_result(const bool newval)
703 {
704  m_log_result = newval;
705 }
706 
707 
708 inline bool
710 {
711  return m_log_result;
712 }
713 
714 
715 inline double
717 {
718  return reduce;
719 }
720 
721 
722 inline double
723 ReductionControl::set_reduction(const double t)
724 {
725  double old = reduce;
726  reduce = t;
727  return old;
728 }
729 
730 #endif // DOXYGEN
731 
732 DEAL_II_NAMESPACE_CLOSE
733 
734 #endif
double initial_value() const
Stop iteration, goal not reached.
__global__ void reduction(Number *result, const Number *v, const size_type N)
bool log_history() const
virtual State check(const unsigned int step, const double check_value)
bool history_data_enabled
Continue iteration.
const std::vector< double > & get_history_data() const
static void declare_parameters(ParameterHandler &param)
unsigned int n_consecutive_iterations
double step_reduction(unsigned int step) const
double final_reduction() const
void clear_failure_criterion()
double reduction() const
double failure_residual
ExceptionBase operator=(const ExceptionBase &)=delete
const unsigned int last_step
unsigned int log_frequency(unsigned int)
Stop iteration, goal reached.
unsigned int m_log_frequency
double set_reduction(const double)
#define DeclException0(Exception0)
Definition: exceptions.h:473
static ::ExceptionBase & ExcHistoryDataRequired()
double relative_failure_residual
double last_value() const
double average_reduction() const
unsigned int lstep
double tolerance() const
virtual ~SolverControl() override=default
unsigned int n_converged_iterations
State last_check() const
unsigned int max_steps() const
void enable_history_data()
double set_tolerance(const double)
unsigned int maxsteps
void parse_parameters(ParameterHandler &param)
std::vector< double > history_data
virtual void print_info(std::ostream &out) const override
SolverControl(const unsigned int n=100, const double tol=1.e-10, const bool log_history=false, const bool log_result=true)
bool log_result() const
unsigned int set_max_steps(const unsigned int)
void set_failure_criterion(const double rel_failure_residual)