Reference documentation for deal.II version GIT 5dcc62ab57 2022-07-04 21:05:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
solver_control.h
Go to the documentation of this file.
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2022 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 
23 
24 #include <vector>
25 
27 
28 #ifndef DOXYGEN
29 class ParameterHandler;
30 #endif
31 
34 
65 class SolverControl : public Subscriptor
66 {
67 public:
72  enum State
73  {
75  iterate = 0,
79  failure
80  };
81 
82 
83 
94  {
95  public:
96  NoConvergence(const unsigned int last_step, const double last_residual)
99  {}
100 
101  virtual ~NoConvergence() noexcept override = default;
102 
103  virtual void
104  print_info(std::ostream &out) const override
105  {
106  out
107  << "Iterative method reported convergence failure in step " << last_step
108  << ". The residual in the last step was " << last_residual << ".\n\n"
109  << "This error message can indicate that you have simply not allowed "
110  << "a sufficiently large number of iterations for your iterative solver "
111  << "to converge. This often happens when you increase the size of your "
112  << "problem. In such cases, the last residual will likely still be very "
113  << "small, and you can make the error go away by increasing the allowed "
114  << "number of iterations when setting up the SolverControl object that "
115  << "determines the maximal number of iterations you allow."
116  << "\n\n"
117  << "The other situation where this error may occur is when your matrix "
118  << "is not invertible (e.g., your matrix has a null-space), or if you "
119  << "try to apply the wrong solver to a matrix (e.g., using CG for a "
120  << "matrix that is not symmetric or not positive definite). In these "
121  << "cases, the residual in the last iteration is likely going to be large."
122  << std::endl;
123  }
124 
128  const unsigned int last_step;
129 
133  const double last_residual;
134  };
135 
136 
137 
149  explicit SolverControl(const unsigned int n = 100,
150  const double tol = 1.e-10,
151  const bool log_history = false,
152  const bool log_result = true);
153 
158  virtual ~SolverControl() override = default;
159 
163  static void
165 
169  void
171 
189  virtual State
190  check(const unsigned int step, const double check_value);
191 
195  State
196  last_check() const;
197 
201  double
202  initial_value() const;
203 
208  double
209  last_value() const;
210 
214  unsigned int
215  last_step() const;
216 
220  unsigned int
221  max_steps() const;
222 
226  unsigned int
227  set_max_steps(const unsigned int);
228 
234  void
235  set_failure_criterion(const double rel_failure_residual);
236 
241  void
243 
247  double
248  tolerance() const;
249 
253  double
254  set_tolerance(const double);
255 
259  void
261 
265  const std::vector<double> &
266  get_history_data() const;
267 
273  double
274  average_reduction() const;
281  double
282  final_reduction() const;
283 
289  double
290  step_reduction(unsigned int step) const;
291 
295  void
296  log_history(const bool);
297 
301  bool
302  log_history() const;
303 
307  unsigned int
308  log_frequency(unsigned int);
309 
313  void
314  log_result(const bool);
315 
319  bool
320  log_result() const;
321 
328 
329 protected:
333  unsigned int maxsteps;
334 
338  double tol;
339 
344 
348  double initial_val;
349 
353  double lvalue;
354 
358  unsigned int lstep;
359 
365 
370 
378 
383 
387  unsigned int m_log_frequency;
388 
395 
400 
407  std::vector<double> history_data;
408 };
409 
410 
423 {
424 public:
430  explicit ReductionControl(const unsigned int maxiter = 100,
431  const double tolerance = 1.e-10,
432  const double reduce = 1.e-2,
433  const bool log_history = false,
434  const bool log_result = true);
435 
441 
447  operator=(const SolverControl &c);
448 
453  virtual ~ReductionControl() override = default;
454 
458  static void
460 
464  void
466 
472  virtual State
473  check(const unsigned int step, const double check_value) override;
474 
478  double
479  reduction() const;
480 
484  double
485  set_reduction(const double);
486 
487 protected:
491  double reduce;
492 
497  double reduced_tol;
498 };
499 
511 {
512 public:
517  explicit IterationNumberControl(const unsigned int maxiter = 100,
518  const double tolerance = 1e-12,
519  const bool log_history = false,
520  const bool log_result = true);
521 
527 
535 
540  virtual ~IterationNumberControl() override = default;
541 
547  virtual State
548  check(const unsigned int step, const double check_value) override;
549 };
550 
551 
564 {
565 public:
572  explicit ConsecutiveControl(const unsigned int maxiter = 100,
573  const double tolerance = 1.e-10,
574  const unsigned int n_consecutive_iterations = 2,
575  const bool log_history = false,
576  const bool log_result = false);
577 
583 
590  operator=(const SolverControl &c);
591 
596  virtual ~ConsecutiveControl() override = default;
597 
602  virtual State
603  check(const unsigned int step, const double check_value) override;
604 
605 protected:
611 
616 };
617 
619 //---------------------------------------------------------------------------
620 
621 #ifndef DOXYGEN
622 
623 inline unsigned int
625 {
626  return maxsteps;
627 }
628 
629 
630 
631 inline unsigned int
632 SolverControl::set_max_steps(const unsigned int newval)
633 {
634  unsigned int old = maxsteps;
635  maxsteps = newval;
636  return old;
637 }
638 
639 
640 
641 inline void
642 SolverControl::set_failure_criterion(const double rel_failure_residual)
643 {
644  relative_failure_residual = rel_failure_residual;
645  check_failure = true;
646 }
647 
648 
649 
650 inline void
652 {
654  failure_residual = 0;
655  check_failure = false;
656 }
657 
658 
659 
660 inline double
662 {
663  return tol;
664 }
665 
666 
667 
668 inline double
669 SolverControl::set_tolerance(const double t)
670 {
671  double old = tol;
672  tol = t;
673  return old;
674 }
675 
676 
677 inline void
678 SolverControl::log_history(const bool newval)
679 {
680  m_log_history = newval;
681 }
682 
683 
684 
685 inline bool
687 {
688  return m_log_history;
689 }
690 
691 
692 inline void
693 SolverControl::log_result(const bool newval)
694 {
695  m_log_result = newval;
696 }
697 
698 
699 inline bool
701 {
702  return m_log_result;
703 }
704 
705 
706 inline double
708 {
709  return reduce;
710 }
711 
712 
713 inline double
714 ReductionControl::set_reduction(const double t)
715 {
716  double old = reduce;
717  reduce = t;
718  return old;
719 }
720 
721 #endif // DOXYGEN
722 
724 
725 #endif
ConsecutiveControl & operator=(const SolverControl &c)
virtual ~ConsecutiveControl() override=default
ConsecutiveControl(const unsigned int maxiter=100, const double tolerance=1.e-10, const unsigned int n_consecutive_iterations=2, const bool log_history=false, const bool log_result=false)
unsigned int n_consecutive_iterations
unsigned int n_converged_iterations
virtual State check(const unsigned int step, const double check_value) override
virtual State check(const unsigned int step, const double check_value) override
IterationNumberControl(const unsigned int maxiter=100, const double tolerance=1e-12, const bool log_history=false, const bool log_result=true)
IterationNumberControl(const SolverControl &c)
IterationNumberControl & operator=(const SolverControl &c)
virtual ~IterationNumberControl() override=default
double set_reduction(const double)
void parse_parameters(ParameterHandler &param)
virtual ~ReductionControl() override=default
double reduction() const
virtual State check(const unsigned int step, const double check_value) override
static void declare_parameters(ParameterHandler &param)
ReductionControl & operator=(const SolverControl &c)
ReductionControl(const unsigned int maxiter=100, const double tolerance=1.e-10, const double reduce=1.e-2, const bool log_history=false, const bool log_result=true)
const unsigned int last_step
NoConvergence(const unsigned int last_step, const double last_residual)
virtual void print_info(std::ostream &out) const override
virtual ~NoConvergence() noexcept override=default
void log_history(const bool)
static void declare_parameters(ParameterHandler &param)
State last_check() const
double average_reduction() const
virtual ~SolverControl() override=default
const std::vector< double > & get_history_data() const
void clear_failure_criterion()
unsigned int lstep
unsigned int last_step() const
double last_value() const
void log_result(const bool)
unsigned int m_log_frequency
unsigned int log_frequency(unsigned int)
virtual State check(const unsigned int step, const double check_value)
unsigned int maxsteps
void set_failure_criterion(const double rel_failure_residual)
bool log_history() const
void enable_history_data()
double step_reduction(unsigned int step) const
std::vector< double > history_data
double failure_residual
double relative_failure_residual
unsigned int set_max_steps(const unsigned int)
double set_tolerance(const double)
unsigned int max_steps() const
SolverControl(const unsigned int n=100, const double tol=1.e-10, const bool log_history=false, const bool log_result=true)
double initial_value() const
double tolerance() const
bool log_result() const
void parse_parameters(ParameterHandler &param)
double final_reduction() const
@ iterate
Continue iteration.
@ success
Stop iteration, goal reached.
@ failure
Stop iteration, goal not reached.
bool history_data_enabled
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:442
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:443
#define DeclException0(Exception0)
Definition: exceptions.h:464
static ::ExceptionBase & ExcHistoryDataRequired()
SymmetricTensor< 2, dim, Number > e(const Tensor< 2, dim, Number > &F)