solver_control.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2017 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_solver_control_h
#define dealii_solver_control_h


#include <deal.II/base/config.h>
#include <deal.II/base/subscriptor.h>

#include <vector>

DEAL_II_NAMESPACE_OPEN

class ParameterHandler;


class SolverControl : public Subscriptor
{
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 = default;

    virtual void print_info (std::ostream &out) const
    {
      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;
  };



  SolverControl (const unsigned int n           = 100,
                 const double       tol         = 1.e-10,
                 const bool         log_history = false,
                 const bool         log_result  = true);

  virtual ~SolverControl() = 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:
  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);

  ReductionControl (const SolverControl &c);

  ReductionControl &operator= (const SolverControl &c);

  virtual ~ReductionControl() = default;

  static void declare_parameters (ParameterHandler &param);

  void parse_parameters (ParameterHandler &param);

  virtual State check (const unsigned int step,
                       const double   check_value);

  double reduction () const;

  double set_reduction (const double);

protected:
  double reduce;

  double reduced_tol;
};

class IterationNumberControl : public SolverControl
{
public:
  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() = default;

  virtual State check (const unsigned int step,
                       const double   check_value);
};


class ConsecutiveControl : public SolverControl
{
public:
  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);

  ConsecutiveControl (const SolverControl &c);

  ConsecutiveControl &operator= (const SolverControl &c);

  virtual ~ConsecutiveControl() = default;

  virtual State check (const unsigned int step,
                       const double   check_value);

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