Line data    Source code

       1            0 : // Distributed under the MIT License.
       2              : // See LICENSE.txt for details.
       3              : 
       4              : #pragma once
       5              : 
       6              : #include <cstddef>
       7              : 
       8              : #include "Options/String.hpp"
       9              : #include "Utilities/TMPL.hpp"
      10              : 
      11              : /// \cond
      12              : namespace PUP {
      13              : class er;
      14              : }  // namespace PUP
      15              : /// \endcond
      16              : 
      17              : namespace Convergence {
      18              : 
      19              : /*!
      20              :  * \brief Criteria that determine an iterative algorithm has converged
      21              :  *
      22              :  * \details Most criteria are based on a residual magnitude
      23              :  * \f$r_k\f$ after completion of an iteration \f$k\f$ (see, for instance, the
      24              :  * \ref LinearSolverGroup documentation, `LinearSolver::Tags::Residual` and
      25              :  * `LinearSolver::Tags::Magnitude`).
      26              :  *
      27              :  * The following criteria are implemented, ordered from highest to lowest
      28              :  * priority:
      29              :  *
      30              :  * - AbsoluteResidual: Matches if the residual has reached this magnitude.
      31              :  * - RelativeResidual: Matches if the residual has decreased by this factor,
      32              :  * relative to the start of the first iteration.
      33              :  * - MaxIterations: Matches if the number of iterations exceeds this limit.
      34              :  */
      35            1 : struct Criteria {
      36            0 :   static constexpr Options::String help =
      37              :       "The algorithm terminates when any of these criteria is matched.";
      38              : 
      39            0 :   struct MaxIterations {
      40            0 :     using type = size_t;
      41            0 :     static constexpr Options::String help = {
      42              :         "The number of iterations exceeds this limit."};
      43            0 :     static type lower_bound() { return 0; }
      44              :   };
      45              : 
      46            0 :   struct AbsoluteResidual {
      47            0 :     using type = double;
      48            0 :     static constexpr Options::String help = {
      49              :         "The residual has reached this magnitude."};
      50            0 :     static type lower_bound() { return 0.; }
      51              :   };
      52              : 
      53            0 :   struct RelativeResidual {
      54            0 :     using type = double;
      55            0 :     static constexpr Options::String help = {
      56              :         "The residual has decreased by this factor."};
      57            0 :     static type lower_bound() { return 0.; }
      58            0 :     static type upper_bound() { return 1.; }
      59              :   };
      60              : 
      61            0 :   using options = tmpl::list<MaxIterations, AbsoluteResidual, RelativeResidual>;
      62              : 
      63            0 :   Criteria() = default;
      64            0 :   Criteria(size_t max_iterations_in, double absolute_residual_in,
      65              :            double relative_residual_in);
      66              : 
      67              :   // NOLINTNEXTLINE(google-runtime-references)
      68            0 :   void pup(PUP::er& p);
      69              : 
      70            0 :   size_t max_iterations{};
      71            0 :   double absolute_residual{};
      72            0 :   double relative_residual{};
      73              : };
      74              : 
      75            0 : bool operator==(const Criteria& lhs, const Criteria& rhs);
      76            0 : bool operator!=(const Criteria& lhs, const Criteria& rhs);
      77              : 
      78              : }  // namespace Convergence