solver_control.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1998 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_solver_control_h
#define dealii_solver_control_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
 
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
#ifndef DOXYGEN
class ParameterHandler;
#endif
 
class SolverControl : public EnableObserverPointer
{
public:
  enum State
  {
    iterate = 0,
    success,
    failure
  };
 
 
 
  class NoConvergence : public ::ExceptionBase
  {
  public:
    NoConvergence(const unsigned int last_step, const double last_residual)
      : last_step(last_step)
      , last_residual(last_residual)
    {}
 
    virtual ~NoConvergence() noexcept override = default;
 
    virtual void
    print_info(std::ostream &out) const override
    {
      out
        << "Iterative method reported convergence failure in step " << 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;
    }
 
    const unsigned int last_step;
 
    const double last_residual;
  };
 
 
 
  explicit SolverControl(const unsigned int n           = 100,
                         const double       tol         = 1.e-10,
                         const bool         log_history = false,
                         const bool         log_result  = false);
 
  virtual ~SolverControl() override = default;
 
  static void
  declare_parameters(ParameterHandler &param);
 
  void
  parse_parameters(ParameterHandler &param);
 
  virtual State
  check(const unsigned int step, const double check_value);
 
  State
  last_check() const;
 
  double
  initial_value() const;
 
  double
  last_value() const;
 
  unsigned int
  last_step() const;
 
  unsigned int
  max_steps() const;
 
  unsigned int
  set_max_steps(const unsigned int);
 
  void
  set_failure_criterion(const double rel_failure_residual);
 
  void
  clear_failure_criterion();
 
  double
  tolerance() const;
 
  double
  set_tolerance(const double);
 
  void
  enable_history_data();
 
  const std::vector<double> &
  get_history_data() const;
 
  double
  average_reduction() const;
  double
  final_reduction() const;
 
  double
  step_reduction(unsigned int step) const;
 
  void
  log_history(const bool);
 
  bool
  log_history() const;
 
  unsigned int
  log_frequency(unsigned int);
 
  void
  log_result(const bool);
 
  bool
  log_result() const;
 
  DeclException0(ExcHistoryDataRequired);
 
protected:
  unsigned int maxsteps;
 
  double tol;
 
  State lcheck;
 
  double initial_val;
 
  double lvalue;
 
  unsigned int lstep;
 
  bool check_failure;
 
  double relative_failure_residual;
 
  double failure_residual;
 
  bool m_log_history;
 
  unsigned int m_log_frequency;
 
  bool m_log_result;
 
  bool history_data_enabled;
 
  std::vector<double> history_data;
};
 
 
class ReductionControl : public SolverControl
{
public:
  explicit 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  = false);
 
  explicit ReductionControl(const SolverControl &c);
 
  ReductionControl &
  operator=(const SolverControl &c);
 
  virtual ~ReductionControl() override = default;
 
  static void
  declare_parameters(ParameterHandler &param);
 
  void
  parse_parameters(ParameterHandler &param);
 
  virtual State
  check(const unsigned int step, const double check_value) override;
 
  double
  reduction() const;
 
  double
  set_reduction(const double);
 
protected:
  double reduce;
 
  double reduced_tol;
};
 
class IterationNumberControl : public SolverControl
{
public:
  explicit IterationNumberControl(const unsigned int maxiter     = 100,
                                  const double       tolerance   = 1e-12,
                                  const bool         log_history = false,
                                  const bool         log_result  = false);
 
  explicit IterationNumberControl(const SolverControl &c);
 
  IterationNumberControl &
  operator=(const SolverControl &c);
 
  virtual ~IterationNumberControl() override = default;
 
  virtual State
  check(const unsigned int step, const double check_value) override;
};
 
 
class ConsecutiveControl : public SolverControl
{
public:
  explicit 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);
 
  explicit ConsecutiveControl(const SolverControl &c);
 
  ConsecutiveControl &
  operator=(const SolverControl &c);
 
  virtual ~ConsecutiveControl() override = default;
 
  virtual State
  check(const unsigned int step, const double check_value) override;
 
protected:
  unsigned int n_consecutive_iterations;
 
  unsigned int n_converged_iterations;
};
 
//---------------------------------------------------------------------------
 
#ifndef DOXYGEN
 
inline unsigned int
SolverControl::max_steps() const
{
  return maxsteps;
}
 
 
 
inline unsigned int
SolverControl::set_max_steps(const unsigned int newval)
{
  unsigned int old = maxsteps;
  maxsteps         = newval;
  return old;
}
 
 
 
inline void
SolverControl::set_failure_criterion(const double rel_failure_residual)
{
  relative_failure_residual = rel_failure_residual;
  check_failure             = true;
}
 
 
 
inline void
SolverControl::clear_failure_criterion()
{
  relative_failure_residual = 0;
  failure_residual          = 0;
  check_failure             = false;
}
 
 
 
inline double
SolverControl::tolerance() const
{
  return tol;
}
 
 
 
inline double
SolverControl::set_tolerance(const double t)
{
  double old = tol;
  tol        = t;
  return old;
}
 
 
inline void
SolverControl::log_history(const bool newval)
{
  m_log_history = newval;
}
 
 
 
inline bool
SolverControl::log_history() const
{
  return m_log_history;
}
 
 
inline void
SolverControl::log_result(const bool newval)
{
  m_log_result = newval;
}
 
 
inline bool
SolverControl::log_result() const
{
  return m_log_result;
}
 
 
inline double
ReductionControl::reduction() const
{
  return reduce;
}
 
 
inline double
ReductionControl::set_reduction(const double t)
{
  double old = reduce;
  reduce     = t;
  return old;
}
 
#endif // DOXYGEN
 
DEAL_II_NAMESPACE_CLOSE
 
#endif