Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <optional>
       7             : 
       8             : /// \cond
       9             : namespace PUP {
      10             : class er;
      11             : }  // namespace PUP
      12             : /// \endcond
      13             : 
      14             : /// Information on a requested time-step size returned by `StepChooser`s.
      15             : ///
      16             : /// Requests made using this struct control most of the changing of
      17             : /// slab and local-time-stepping step sizes.  Slab-size changing is
      18             : /// more complex, as it is controlled using the `ChangeSlabSize`
      19             : /// event, which may run zero or more times per slab, and may have the
      20             : /// application of its result delayed.  The step size for LTS is
      21             : /// adjusted using a constant list of `StepChoosers` on every step.
      22             : ///
      23             : /// For slab-size adjustment (including the global time step when not
      24             : /// using LTS), a "goal" step size is maintained from step to step.
      25             : /// It is initially the initial slab size from the input file, and can
      26             : /// be adjusted by any request setting the `size_goal` field of this
      27             : /// struct.  If multiple requests set new goals at the same time, the
      28             : /// smallest value is used.  At the start of each slab, the size is
      29             : /// chosen to be the smallest of the current goal and the temporary
      30             : /// limits imposed by any requests processed at that time.  For the
      31             : /// LTS step size, the current step size is used as the goal if no
      32             : /// request sets a new one.
      33             : ///
      34             : /// Any request with either the `size` or `end` fields set introduces
      35             : /// a temporary step size limit.  If only one of the two is set, the
      36             : /// chosen step size will be limited to be not larger than `*size`, or
      37             : /// not go beyond the time `*end`.  If both are set, the tighter limit
      38             : /// may be ignored if the looser limit is chosen as the actual step,
      39             : /// but the step will not be chosen to be intermediate between two
      40             : /// temporary limits from the same request object.
      41             : ///
      42             : /// The hard limits are not used in setting the step size, but if the
      43             : /// actual step does not satisfy all hard limits from all requests the
      44             : /// evolution will be terminated with an error.
      45             : ///
      46             : /// \note All step sizes are subject to roundoff error in either
      47             : /// direction except for two cases:
      48             : /// * Slab sizes imposed by the `end` limit of a request will always
      49             : ///   end precisely at the requested time.
      50             : /// * LTS step sizes within a single slab will always be considered to
      51             : ///   have size ratios that are exactly powers of two for the purposes
      52             : ///   of the `size_goal` and `size` limits.
      53           1 : struct TimeStepRequest {
      54           0 :   std::optional<double> size_goal{};
      55             : 
      56           0 :   std::optional<double> size{};
      57           0 :   std::optional<double> end{};
      58             : 
      59           0 :   std::optional<double> size_hard_limit{};
      60           0 :   std::optional<double> end_hard_limit{};
      61             : 
      62           0 :   void pup(PUP::er& p);
      63             : };
      64             : 
      65           0 : bool operator==(const TimeStepRequest& a, const TimeStepRequest& b);
      66           0 : bool operator!=(const TimeStepRequest& a, const TimeStepRequest& b);