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