Reference documentation for deal.II version 9.4.0
\(\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
30#endif
31
34
66{
67public:
72 enum State
73 {
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
329protected:
333 unsigned int maxsteps;
334
338 double tol;
339
344
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{
424public:
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
487protected:
491 double reduce;
492
498};
499
511{
512public:
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{
565public:
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
605protected:
611
616};
617
619//---------------------------------------------------------------------------
620
621#ifndef DOXYGEN
622
623inline unsigned int
625{
626 return maxsteps;
627}
628
629
630
631inline unsigned int
632SolverControl::set_max_steps(const unsigned int newval)
633{
634 unsigned int old = maxsteps;
635 maxsteps = newval;
636 return old;
637}
638
639
640
641inline void
642SolverControl::set_failure_criterion(const double rel_failure_residual)
643{
644 relative_failure_residual = rel_failure_residual;
645 check_failure = true;
646}
647
648
649
650inline void
652{
655 check_failure = false;
656}
657
658
659
660inline double
662{
663 return tol;
664}
665
666
667
668inline double
669SolverControl::set_tolerance(const double t)
670{
671 double old = tol;
672 tol = t;
673 return old;
674}
675
676
677inline void
678SolverControl::log_history(const bool newval)
679{
680 m_log_history = newval;
681}
682
683
684
685inline bool
687{
688 return m_log_history;
689}
690
691
692inline void
693SolverControl::log_result(const bool newval)
694{
695 m_log_result = newval;
696}
697
698
699inline bool
701{
702 return m_log_result;
703}
704
705
706inline double
708{
709 return reduce;
710}
711
712
713inline double
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
IterationNumberControl & operator=(const SolverControl &c)
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)
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)
STL namespace.