Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <array>
       7             : #include <cstddef>
       8             : #include <limits>
       9             : 
      10             : #include "DataStructures/DataVector.hpp"
      11             : #include "Options/String.hpp"
      12             : 
      13             : /// \cond
      14             : namespace PUP {
      15             : class er;
      16             : }  // namespace PUP
      17             : /// \endcond
      18             : 
      19             : /// \ingroup ControlSystemGroup
      20             : /// A PND (proportional to Q and N derivatives of Q) controller that computes
      21             : /// the control signal:
      22             : /// \f[ U(t) = \sum_{k=0}^{N} a_{k} \frac{d^kQ}{dt^k} \f]
      23             : /// where N is specified by the template parameter `DerivOrder`.
      24             : ///
      25             : /// If an averager is used for `q_and_derivs` (as we typically do), there is an
      26             : /// induced time offset, \f$\Delta t\f$, due to the time-weighted averaging.
      27             : /// Therefore, the `q_and_derivs` that we have in hand are at some time
      28             : /// \f$t_{0}\f$. However, we desire `q_and_derivs` at the current time
      29             : /// \f$t = t_{0} + \Delta t\f$ to determine the appropriate control
      30             : /// signal. We accomplish this by Taylor expanding
      31             : /// \f$Q(t_{0} + \Delta t)\f$. The averager allows for averaging of
      32             : /// \f$Q\f$ and its derivatives OR to not average \f$Q\f$ while still averaging
      33             : /// the derivatives (the derivatives are always averaged in order to reduce
      34             : /// noise due to numerical differentiation). When they are both averaged, the
      35             : /// time offset will be identical for \f$Q\f$ and the derivatives,
      36             : /// i.e. `q_time_offset` = `deriv_time_offset`. If an unaveraged \f$Q\f$ is
      37             : /// used, then the time offset associated with \f$Q\f$ is zero,
      38             : /// i.e. `q_time_offset`=0. and the derivative time offset, `deriv_time_offset`,
      39             : /// remains non-zero.
      40             : template <size_t DerivOrder>
      41           1 : class Controller {
      42             :  public:
      43           0 :   struct UpdateFraction {
      44           0 :     using type = double;
      45           0 :     static constexpr Options::String help = {
      46             :         "Fraction of damping timescale used to determine how often to update "
      47             :         "functions of time."};
      48             :   };
      49             : 
      50           0 :   using options = tmpl::list<UpdateFraction>;
      51           0 :   static constexpr Options::String help{
      52             :       "Computes control signal used to reset highest derivative of a function "
      53             :       "of time. Also determines when a function of time needs to be updated "
      54             :       "next."};
      55             : 
      56           0 :   Controller(const double update_fraction)
      57             :       : update_fraction_(update_fraction) {}
      58             : 
      59           0 :   Controller() = default;
      60           0 :   Controller(Controller&&) = default;
      61           0 :   Controller& operator=(Controller&&) = default;
      62           0 :   Controller(const Controller&) = default;
      63           0 :   Controller& operator=(const Controller&) = default;
      64           0 :   ~Controller() = default;
      65             : 
      66           0 :   DataVector operator()(const double time, const DataVector& timescales,
      67             :                         const std::array<DataVector, DerivOrder>& q_and_derivs,
      68             :                         double q_time_offset, double deriv_time_offset);
      69             : 
      70             :   /// Takes the current minimum of all timescales for a specific control system
      71             :   /// and uses that to set the time between updates
      72           1 :   void assign_time_between_updates(const double current_min_timescale) {
      73             :     time_between_updates_ = update_fraction_ * current_min_timescale;
      74             :   }
      75             : 
      76             :   /// Returns `true` if the controller is ready to calculate the control signal
      77           1 :   bool is_ready(const double time) {
      78             :     return time >= last_update_time_ + time_between_updates_;
      79             :   }
      80             : 
      81             :   /// Calculates the new expiration time as the old expiration time plus the
      82             :   /// time between updates
      83           1 :   double next_expiration_time(const double current_expiration_time) {
      84             :     return current_expiration_time + time_between_updates_;
      85             :   }
      86             : 
      87             :   /// Sets the last time updated to the initial time
      88           1 :   void set_initial_update_time(const double initial_time) {
      89             :     last_update_time_ = initial_time;
      90             :   }
      91             : 
      92             :   /// Return the update fraction
      93           1 :   double get_update_fraction() const { return update_fraction_; }
      94             : 
      95             :   // NOLINTNEXTLINE(google-runtime-references)
      96           0 :   void pup(PUP::er& p) {
      97             :     p | update_fraction_;
      98             :     p | time_between_updates_;
      99             :     p | last_update_time_;
     100             :   }
     101             : 
     102             :   template <size_t LocalDerivOrder>
     103             :   // NOLINTNEXTLINE(readability-redundant-declaration) false positive
     104           0 :   friend bool operator==(const Controller<LocalDerivOrder>& lhs,
     105             :                          const Controller<LocalDerivOrder>& rhs);
     106             : 
     107             :  private:
     108             :   // If update_fraction_ isn't set we need to error
     109           0 :   double update_fraction_{std::numeric_limits<double>::signaling_NaN()};
     110             :   // If this time_between_updates_ isn't set, the default should just be that
     111             :   // the functions of time are never updated (i.e. infinity)
     112           0 :   double time_between_updates_{std::numeric_limits<double>::infinity()};
     113             :   // Set to a large negative number to signify that we haven't updated yet and
     114             :   // should as early as possible
     115           0 :   double last_update_time_{-std::numeric_limits<double>::max()};
     116             : };
     117             : 
     118             : template <size_t DerivOrder>
     119           0 : bool operator!=(const Controller<DerivOrder>& lhs,
     120             :                 const Controller<DerivOrder>& rhs);