Line data    Source code

       1            0 : // Distributed under the MIT License.
       2              : // See LICENSE.txt for details.
       3              : 
       4              : // Tests for the VariableOrderAlgorithm class are performed in
       5              : // Test_ChangeTimeStepperOrder.cpp.  The class is split into this file
       6              : // to avoid include loops with the associated tags.
       7              : 
       8              : #pragma once
       9              : 
      10              : #include <array>
      11              : #include <cstddef>
      12              : #include <optional>
      13              : 
      14              : #include "Options/String.hpp"
      15              : #include "Time/History.hpp"
      16              : #include "Time/StepperErrorEstimate.hpp"
      17              : #include "Time/StepperErrorTolerances.hpp"
      18              : #include "Utilities/ErrorHandling/Assert.hpp"
      19              : #include "Utilities/TMPL.hpp"
      20              : 
      21              : /// \cond
      22              : namespace Options {
      23              : template <typename... AlternativeLists>
      24              : struct Alternatives;
      25              : }  // namespace Options
      26              : /// \endcond
      27              : 
      28              : /*!
      29              :  * \ingroup TimeGroup
      30              :  * \brief Class encapsulating the time-stepper order changing algorithms
      31              :  *
      32              :  * \details Supports two modes: driving the order to a specified constant, and
      33              :  * measuring the convergence of the error estimates.
      34              :  *
      35              :  * When driving to a constant, the order is changed by one towards the
      36              :  * goal if it is not at the goal.
      37              :  *
      38              :  * When measuring convergence, let the relative error estimate from
      39              :  * the time stepper for order-$k$ integration be $e_k$, and $\lambda
      40              :  * \le 1$ be the falloff this class was constructed with.  Then, we
      41              :  * decrease the order by one if, for any $k \ge 2$ and less than the
      42              :  * current integration order,
      43              :  *
      44              :  * \f{equation}
      45              :  *   \frac{e_k}{e_{k-1}} >
      46              :  *   \left(\min_{2 \le j < k} \frac{e_j}{e_{j-1}}\right)^\lambda,
      47              :  * \f}
      48              :  *
      49              :  * with the right-hand side taken to be $1$ for $k = 2$.  If the order
      50              :  * is not decreased, it is kept the same if the above condition holds
      51              :  * for $k$ equal to the current integration order, and is increased by
      52              :  * one otherwise.  If the current integration order is $1$ (not
      53              :  * possible for predictor-corrector methods), it is always increased.
      54              :  * This algorithm will almost never prefer an integration order less
      55              :  * than three.
      56              :  *
      57              :  * \note This is currently all implemented in one class for simplicity
      58              :  * with dealing with templates.  If we add more algorithms splitting
      59              :  * into a base class with implementations would be appropriate.
      60              :  */
      61            1 : class VariableOrderAlgorithm {
      62              :  public:
      63            0 :   struct GoalOrder {
      64            0 :     using type = size_t;
      65            0 :     static constexpr Options::String help = "Order to drive the integrator to.";
      66              :   };
      67              : 
      68            0 :   struct OrderFalloff {
      69            0 :     using type = double;
      70            0 :     static constexpr Options::String help =
      71              :         "Threshold for changing time-stepper order, as a logarithmic "
      72              :         "fraction of the best order-to-order improvement.";
      73              :   };
      74              : 
      75            0 :   using options = tmpl::list<
      76              :       Options::Alternatives<tmpl::list<GoalOrder>, tmpl::list<OrderFalloff>>>;
      77            0 :   static constexpr Options::String help =
      78              :       "Algorithm for choosing the time-stepper order in a variable-order "
      79              :       "evolution.";
      80              : 
      81            0 :   VariableOrderAlgorithm();
      82            0 :   explicit VariableOrderAlgorithm(size_t goal_order);
      83            0 :   explicit VariableOrderAlgorithm(double order_falloff);
      84              : 
      85            0 :   StepperErrorTolerances::Estimates required_estimates() const;
      86              : 
      87              :   template <typename... VariablesTags>
      88            0 :   size_t choose_order(
      89              :       const TimeSteppers::History<typename VariablesTags::type>&... histories,
      90              :       const typename tmpl::has_type<
      91              :           VariablesTags,
      92              :           std::array<std::optional<StepperErrorEstimate>, 2>>::type&... errors)
      93              :       const {
      94              :     const auto history_order =
      95              :         get_first_argument(histories...).integration_order();
      96              :     ASSERT((... and (history_order == histories.integration_order())),
      97              :            "Multiple histories with different integration orders.");
      98              : 
      99              :     if (goal_order_.has_value()) {
     100              :       ASSERT(not order_falloff_.has_value(),
     101              :              "Internal error: should not have multiple algorithms active");
     102              :       return choose_order_goal(history_order);
     103              :     } else {
     104              :       ASSERT(order_falloff_.has_value(),
     105              :              "VariableOrderAlgorithm not initialized");
     106              :       return choose_order_falloff(history_order, std::array{&errors[1]...});
     107              :     }
     108              :   }
     109              : 
     110            0 :   void pup(PUP::er& p);
     111              : 
     112              :  private:
     113            0 :   size_t choose_order_goal(size_t current_order) const;
     114              : 
     115              :   template <size_t NVars>
     116            0 :   size_t choose_order_falloff(
     117              :       size_t current_order,
     118              :       const std::array<const std::optional<StepperErrorEstimate>*, NVars>&
     119              :           errors) const;
     120              : 
     121            0 :   friend bool operator==(const VariableOrderAlgorithm& a,
     122              :                          const VariableOrderAlgorithm& b);
     123              : 
     124            0 :   std::optional<size_t> goal_order_{};
     125            0 :   std::optional<double> order_falloff_{};
     126              : };