Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include "DataStructures/DataBox/PrefixHelpers.hpp"
       7             : #include "DataStructures/DataBox/Prefixes.hpp"
       8             : #include "DataStructures/MathWrapper.hpp"
       9             : #include "Time/History.hpp"
      10             : #include "Time/Time.hpp"
      11             : #include "Time/TimeSteppers/TimeStepper.hpp"
      12             : #include "Utilities/GenerateInstantiations.hpp"
      13             : #include "Utilities/Gsl.hpp"
      14             : #include "Utilities/Serialization/CharmPupable.hpp"
      15             : 
      16             : /// \cond
      17             : #define IMEX_TIME_STEPPER_WRAPPED_TYPE(data) BOOST_PP_TUPLE_ELEM(0, data)
      18             : #define IMEX_TIME_STEPPER_DERIVED_CLASS(data) BOOST_PP_TUPLE_ELEM(1, data)
      19             : /// \endcond
      20             : 
      21             : /*!
      22             :  * \ingroup TimeSteppersGroup
      23             :  *
      24             :  * Base class for TimeSteppers with IMEX support, derived from
      25             :  * TimeStepper.
      26             :  *
      27             :  * All supported time-stepping algorithms (both implicit and
      28             :  * explicit) consist of substeps that add linear combinations of
      29             :  * derivative values.  For implicit substeps, it is convenient to
      30             :  * split out the contribution of the final implicit term from
      31             :  * contributions from the history.  We therefore write an implicit
      32             :  * substep as
      33             :  *
      34             :  * \f{equation}{
      35             :  *   Y_{n+1} =
      36             :  *   Y_{n,\text{explicit}} + Y_{n,\text{inhomogeneous}} + w_n S(Y_{n+1})
      37             :  * \f}
      38             :  *
      39             :  * Here \f$Y_{n,\text{explicit}}\f$ is the value of the evolved
      40             :  * variables before the implicit substep is applied,
      41             :  * \f$Y_{n,\text{inhomogeneous}}\f$ is the contribution of the past
      42             :  * values from the implicit derivative history, and \f$S(\cdot)\f$ is
      43             :  * the implicit portion of the right-hand-side (generally source
      44             :  * terms for PDEs).  We call \f$w_n\f$ the *implicit weight*.
      45             :  * This split form is convenient for most consumers of this class, so
      46             :  * we present methods for calculating
      47             :  * \f$Y_{n,\text{inhomogeneous}}\f$ and \f$w_n\f$ individually
      48             :  * instead of a method to perform a full step update.
      49             :  *
      50             :  * History cleanup is the same for the explicit and implicit parts,
      51             :  * and should be done together.
      52             :  *
      53             :  * Dense output formulae are the same for the explicit and implicit
      54             :  * parts of any conservative IMEX stepper.  To evaluate dense output,
      55             :  * call `dense_update_u` with the implicit history after a successful
      56             :  * call to `dense_update_u` with the explicit history.
      57             :  *
      58             :  * Several of the member functions of this class are templated and
      59             :  * perform type erasure before forwarding their arguments to the
      60             :  * derived classes.  This is implemented using the macros \ref
      61             :  * IMEX_TIME_STEPPER_DECLARE_OVERLOADS, which must be placed in a
      62             :  * private section of the class body, and
      63             :  * IMEX_TIME_STEPPER_DEFINE_OVERLOADS(derived_class), which must be
      64             :  * placed in the cpp file.
      65             :  */
      66           1 : class ImexTimeStepper : public virtual TimeStepper {
      67             :  public:
      68           0 :   static constexpr bool imex = true;
      69           0 :   using provided_time_stepper_interfaces =
      70             :       tmpl::list<ImexTimeStepper, TimeStepper>;
      71             : 
      72           0 :   WRAPPED_PUPable_abstract(ImexTimeStepper);  // NOLINT
      73             : 
      74             : /// \cond
      75             : #define IMEX_TIME_STEPPER_DECLARE_VIRTUALS_IMPL(_, data)                      \
      76             :   virtual void add_inhomogeneous_implicit_terms_forward(                      \
      77             :       gsl::not_null<IMEX_TIME_STEPPER_WRAPPED_TYPE(data)*> u,                 \
      78             :       const TimeSteppers::ConstUntypedHistory<IMEX_TIME_STEPPER_WRAPPED_TYPE( \
      79             :           data)>& implicit_history,                                           \
      80             :       const TimeDelta& time_step) const = 0;                                  \
      81             :   virtual double implicit_weight_forward(                                     \
      82             :       const TimeSteppers::ConstUntypedHistory<IMEX_TIME_STEPPER_WRAPPED_TYPE( \
      83             :           data)>& implicit_history,                                           \
      84             :       const TimeDelta& time_step) const = 0;
      85             : 
      86             :   GENERATE_INSTANTIATIONS(IMEX_TIME_STEPPER_DECLARE_VIRTUALS_IMPL,
      87             :                           (MATH_WRAPPER_TYPES))
      88             : #undef IMEX_TIME_STEPPER_DECLARE_VIRTUALS_IMPL
      89             :   /// \endcond
      90             : 
      91             :   /// Convergence order of the integrator when used in IMEX mode.
      92           1 :   virtual size_t imex_order() const = 0;
      93             : 
      94             :   /// Add the change for the current implicit substep,
      95             :   /// \f$Y_{n,\text{inhomogeneous}}\f$, to u, given a past history of
      96             :   /// the implicit derivatives.
      97             :   ///
      98             :   /// Derived classes must implement this as a function with signature
      99             :   ///
     100             :   /// ```
     101             :   /// template <typename T>
     102             :   /// void add_inhomogeneous_implicit_terms_impl(
     103             :   ///     gsl::not_null<T*> u,
     104             :   ///     const ConstUntypedHistory<T>& implicit_history,
     105             :   ///     const TimeDelta& time_step) const;
     106             :   /// ```
     107             :   ///
     108             :   /// \note
     109             :   /// Unlike the `update_u` methods, which overwrite their result
     110             :   /// arguments, this function adds the result to the existing value.
     111             :   template <typename Vars>
     112           1 :   void add_inhomogeneous_implicit_terms(
     113             :       const gsl::not_null<Vars*> u,
     114             :       const TimeSteppers::History<Vars>& implicit_history,
     115             :       const TimeDelta& time_step) const {
     116             :     return add_inhomogeneous_implicit_terms_forward(
     117             :         &*make_math_wrapper(u), implicit_history.untyped(), time_step);
     118             :   }
     119             : 
     120             :   /// The coefficient \f$w_n\f$ of the implicit derivative for the
     121             :   /// current substep.  For a Runge-Kutta method, this is the
     122             :   /// coefficient on the diagonal of the Butcher tableau.
     123             :   ///
     124             :   /// Derived classes must implement this as a function with signature
     125             :   ///
     126             :   /// ```
     127             :   /// template <typename T>
     128             :   /// double implicit_weight_impl(
     129             :   ///     const ConstUntypedHistory<T>& implicit_history,
     130             :   ///     const TimeDelta& time_step) const;
     131             :   /// ```
     132             :   template <typename Vars>
     133           1 :   double implicit_weight(const TimeSteppers::History<Vars>& implicit_history,
     134             :                          const TimeDelta& time_step) const {
     135             :     return implicit_weight_forward(implicit_history.untyped(), time_step);
     136             :   }
     137             : };
     138             : 
     139             : /// \cond
     140             : #define IMEX_TIME_STEPPER_DECLARE_OVERLOADS_IMPL(_, data)                     \
     141             :   void add_inhomogeneous_implicit_terms_forward(                              \
     142             :       gsl::not_null<IMEX_TIME_STEPPER_WRAPPED_TYPE(data)*> u,                 \
     143             :       const TimeSteppers::ConstUntypedHistory<IMEX_TIME_STEPPER_WRAPPED_TYPE( \
     144             :           data)>& implicit_history,                                           \
     145             :       const TimeDelta& time_step) const override;                             \
     146             :   double implicit_weight_forward(                                             \
     147             :       const TimeSteppers::ConstUntypedHistory<IMEX_TIME_STEPPER_WRAPPED_TYPE( \
     148             :           data)>& implicit_history,                                           \
     149             :       const TimeDelta& time_step) const override;
     150             : 
     151             : #define IMEX_TIME_STEPPER_DEFINE_OVERLOADS_IMPL(_, data)                      \
     152             :   void IMEX_TIME_STEPPER_DERIVED_CLASS(data)::                                \
     153             :       add_inhomogeneous_implicit_terms_forward(                               \
     154             :           const gsl::not_null<IMEX_TIME_STEPPER_WRAPPED_TYPE(data)*> u,       \
     155             :           const TimeSteppers::ConstUntypedHistory<                            \
     156             :               IMEX_TIME_STEPPER_WRAPPED_TYPE(data)>& implicit_history,        \
     157             :           const TimeDelta& time_step) const {                                 \
     158             :     return add_inhomogeneous_implicit_terms_impl(u, implicit_history,         \
     159             :                                                  time_step);                  \
     160             :   }                                                                           \
     161             :   double IMEX_TIME_STEPPER_DERIVED_CLASS(data)::implicit_weight_forward(      \
     162             :       const TimeSteppers::ConstUntypedHistory<IMEX_TIME_STEPPER_WRAPPED_TYPE( \
     163             :           data)>& implicit_history,                                           \
     164             :       const TimeDelta& time_step) const {                                     \
     165             :     return implicit_weight_impl(implicit_history, time_step);                 \
     166             :   }
     167             : /// \endcond
     168             : 
     169             : /// \ingroup TimeSteppersGroup
     170             : /// Macro declaring overloaded detail methods in classes derived from
     171             : /// ImexTimeStepper.  Must be placed in a private section of the class
     172             : /// body.
     173           1 : #define IMEX_TIME_STEPPER_DECLARE_OVERLOADS                         \
     174             :   GENERATE_INSTANTIATIONS(IMEX_TIME_STEPPER_DECLARE_OVERLOADS_IMPL, \
     175             :                           (MATH_WRAPPER_TYPES))
     176             : 
     177             : /// \ingroup TimeSteppersGroup
     178             : /// Macro defining overloaded detail methods in classes derived from
     179             : /// ImexTimeStepper.  Must be placed in the cpp file for the derived
     180             : /// class.
     181           1 : #define IMEX_TIME_STEPPER_DEFINE_OVERLOADS(derived_class)          \
     182             :   GENERATE_INSTANTIATIONS(IMEX_TIME_STEPPER_DEFINE_OVERLOADS_IMPL, \
     183             :                           (MATH_WRAPPER_TYPES), (derived_class))