Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <memory>
       7             : #include <optional>
       8             : #include <pup.h>
       9             : #include <string>
      10             : 
      11             : #include "Utilities/Gsl.hpp"
      12             : #include "Utilities/Serialization/CharmPupable.hpp"
      13             : 
      14             : /// \cond
      15             : namespace control_system::size {
      16             : struct Info;
      17             : struct CrossingTimeInfo;
      18             : }  // namespace control_system::size
      19             : /// \endcond
      20             : 
      21             : namespace control_system::size {
      22             : 
      23             : /*!
      24             :  * \brief Packages some of the inputs to the State::update, so that
      25             :  * State::update doesn't need a large number of arguments.
      26             :  */
      27           1 : struct StateUpdateArgs {
      28             :   /// min_char_speed is the minimum over the excision boundary
      29             :   /// of Eq. 89 of \cite Hemberger2012jz.
      30           1 :   double min_char_speed;
      31             :   /// min_comoving_char_speed is the minimum over the excision boundary
      32             :   /// of Eq. 28 of \cite Hemberger2012jz.
      33           1 :   double min_comoving_char_speed;
      34             :   /// horizon_00 is the spherepack coefficient of the apparent
      35             :   /// horizon.
      36           1 :   double horizon_00;
      37             :   /// control_error_delta_r is the control error when the control system
      38             :   /// is in state Label::DeltaR.
      39             :   /// This is Q in Eq. 96 of \cite Hemberger2012jz.
      40           1 :   double control_error_delta_r;
      41             :   /// average_radial_distance is the average distance between the horizon and
      42             :   /// the excision boundary. Used only for state DeltaRDriftOutward.
      43             :   /// If std::nullopt, then DeltaRDriftOutward will not be used.
      44           1 :   std::optional<double> average_radial_distance;
      45             :   /// max_allowed_radial_distance is the minimum distance between the horizon
      46             :   /// and the excision boundary that will trigger state
      47             :   /// Label::DeltaRDriftOutward.  If std::nullopt, then DeltaRDriftOutward
      48             :   /// will never be triggered.
      49           1 :   std::optional<double> max_allowed_radial_distance;
      50             :   /// avg_distorted_normal_dot_unit_coord_vector is the same quantity as
      51             :   /// ControlErrorArgs::avg_distorted_normal_dot_unit_coord_vector.
      52           1 :   double avg_distorted_normal_dot_unit_coord_vector;
      53             :   /// inward_drift_velocity is a positive quantity that represents how
      54             :   /// fast the horizon and the excision boundary move apart in state
      55             :   /// DeltaRDriftInward.  If std::nullopt, then DeltaRDriftInward will
      56             :   /// never be triggered.
      57           1 :   std::optional<double> inward_drift_velocity;
      58             :   /// min_allowed_radial_distance is the minimum distance between the horizon
      59             :   /// and the excision boundary that will trigger state
      60             :   /// Label::DeltaRDriftInward.
      61           1 :   std::optional<double> min_allowed_radial_distance;
      62             :   /// min_allowed_char_speed is the minimum char speed that will
      63             :   /// trigger state DeltaRDriftInward.  If both
      64             :   /// min_allowed_radial_distance and min_allowed_char_speed are
      65             :   /// std::nullopt, then DeltaRDriftInward will never be triggered.
      66           1 :   std::optional<double> min_allowed_char_speed;
      67             :   /// comoving_char_speed_increasing_inward is true if the comoving char speed
      68             :   /// increases as the excision boundary is moved inward.
      69           1 :   bool comoving_char_speed_increasing_inward;
      70             : };
      71             : 
      72             : /*!
      73             :  * \brief Packages some of the inputs to the State::control_error, so that
      74             :  * State::control_error doesn't need a large number of arguments.
      75             :  */
      76           1 : struct ControlErrorArgs {
      77           0 :   double min_char_speed;
      78           0 :   double control_error_delta_r;
      79             :   /*!
      80             :    * \brief control_error_delta_r_outward is the control error in the
      81             :    * case DeltaRDriftOutward, the state where there is an outward drift
      82             :    * caused by too large separation between the horizon and the excision
      83             :    * boundary.  If std::nullopt, then state DeltaRDriftOutward will not be used.
      84             :    */
      85           1 :   std::optional<double> control_error_delta_r_outward;
      86             :   /*!
      87             :    * \brief avg_distorted_normal_dot_unit_coord_vector is the average of
      88             :    * distorted_normal_dot_unit_coord_vector over the excision
      89             :    * boundary.
      90             :    *
      91             :    * \details Here distorted_normal_dot_unit_coord_vector is Eq. 93
      92             :    * of \cite Hemberger2012jz.  distorted_normal_dot_unit_coord_vector is
      93             :    * \f$\hat{n}_i x^i/r\f$ where \f$\nat{n}_i\f$ is the
      94             :    * distorted-frame unit normal to the excision boundary (pointing
      95             :    * INTO the hole, i.e. out of the domain), and \f$x^i/r\f$ is the
      96             :    * distorted-frame (or equivalently the grid frame because it is
      97             :    * invariant between these two frames because of the required
      98             :    * limiting behavior of the map we choose) Euclidean normal vector
      99             :    * from the center of the excision-boundary Strahlkorper to each
     100             :    * point on the excision-boundary Strahlkorper.
     101             :    */
     102           1 :   double avg_distorted_normal_dot_unit_coord_vector;
     103             :   /*!
     104             :    * \brief time_deriv_of_lambda_00 is the time derivative of the quantity
     105             :    * lambda_00 that appears in \cite Hemberger2012jz.
     106             :    *
     107             :    * \details time_deriv_of_lambda_00 is (minus) the radial velocity of the
     108             :    * excision boundary in the distorted frame with respect to the grid frame.
     109             :    */
     110           1 :   double time_deriv_of_lambda_00;
     111             : };
     112             : 
     113             : /*!
     114             :  * \brief Represents a 'state' of the size control system.
     115             :  *
     116             :  * \details Each 'state' of the size control system has a different control
     117             :  * signal, which has a different purpose, even though each state
     118             :  * controls the same map quantity, namely the Y00 coefficient of the
     119             :  * shape map.  For example, state Label::AhSpeed controls
     120             :  * the Y00 coefficient of the shape map so that the minimum
     121             :  * characteristic speed is driven towards a target value, and state
     122             :  * Label::DeltaR controls the Y00 coefficient of the shape
     123             :  * map (or the Y00 coefficient of a separate spherically-symmetric size
     124             :  * map) so that the minimum difference between the horizon radius and
     125             :  * the excision boundary radius is driven towards a constant.
     126             :  *
     127             :  * Each state has its own logic (the 'update' function) that
     128             :  * determines values of certain parameters (i.e. the things in
     129             :  * Info), including whether the control system should
     130             :  * transition to a different state.
     131             :  *
     132             :  * The different states are:
     133             :  * - Initial: drives dr/dt of the excision boundary to
     134             :  *   Info::target_drift_velocity.
     135             :  * - AhSpeed: drives the minimum characteristic speed on the excision boundary
     136             :  *   to Info::target_char_speed.
     137             :  * - DeltaR: drives the minimum distance between the horizon and the excision
     138             :  *   boundary to be constant in time.
     139             :  * - DeltaRDriftInward: Same as DeltaR but the excision boundary has a small
     140             :  *   velocity inward.  This state is triggered when it is deemed that the
     141             :  *   excision boundary and the horizon are too close to each other; the
     142             :  *   small velocity makes the excision boundary and the horizon drift apart.
     143             :  * - DeltaRDriftOutward: Same as DeltaR but the excision boundary has a small
     144             :  *   velocity outward.  This state is triggered when it is deemed that the
     145             :  *   excision boundary and the horizon are too far apart.
     146             :  * - DeltaRNoDrift: Same as DeltaR except for the logic that
     147             :  *   determines how DeltaRNoDrift changes to other states.
     148             :  *   DeltaRNoDrift is allowed (under some circumstances) to change
     149             :  *   to state DeltaR, but DeltaRDriftOutward and DeltaRDriftInward
     150             :  *   are never allowed to change to state DeltaR.  Instead
     151             :  *   DeltaRDriftOutward and DeltaRDriftInward are allowed (under
     152             :  *   some circumstances) to change to state DeltaRNoDrift.
     153             :  *
     154             :  * The reason that DeltaRDriftInward, DeltaRDriftOutward, and
     155             :  * DeltaRNoDrift are separate states is to simplify the logic.  In
     156             :  * principle, all 3 of those states could be merged with state
     157             :  * DeltaR, because the control error is the same for all four states
     158             :  * (except for a velocity term that could be set to zero).  But if that
     159             :  * were done, then there would need to be additional complicated
     160             :  * logic in determining transitions between different states, and
     161             :  * that logic would depend not only on the current state, but also on
     162             :  * the previous state.
     163             :  */
     164           1 : class State : public PUP::able {
     165             :  public:
     166           0 :   State() = default;
     167           0 :   State(const State& /*rhs*/) = default;
     168           0 :   State& operator=(const State& /*rhs*/) = default;
     169           0 :   State(State&& /*rhs*/) = default;
     170           0 :   State& operator=(State&& /*rhs*/) = default;
     171           0 :   virtual ~State() override = default;
     172             : 
     173             :   /// Name of this state
     174           1 :   virtual std::string name() const = 0;
     175             : 
     176             :   /// Return a size_t that corresponds to the state number in SpEC
     177           1 :   virtual size_t number() const = 0;
     178             : 
     179           0 :   virtual std::unique_ptr<State> get_clone() const = 0;
     180             :   /*!
     181             :    * \brief Updates the Info in `info`.
     182             :    *
     183             :    * \note Notice that `info` includes a state, which might be different than
     184             :    * the current state upon return. It is the caller's responsibility to check
     185             :    * if the current state has changed.
     186             :    *
     187             :    * \return The return string is used as a helpful diagnostic that may be
     188             :    * printed to determine what logic decisions the state is making (depends on
     189             :    * the `control_system::Tags::Verbosity` flag).
     190             :    */
     191           1 :   virtual std::string update(
     192             :       const gsl::not_null<Info*> info, const StateUpdateArgs& update_args,
     193             :       const CrossingTimeInfo& crossing_time_info) const = 0;
     194             :   /// Returns the control signal, but does not modify the state or any
     195             :   /// parameters.
     196           1 :   virtual double control_error(
     197             :       const Info& info, const ControlErrorArgs& control_error_args) const = 0;
     198             : 
     199           0 :   WRAPPED_PUPable_abstract(State);  // NOLINT
     200           0 :   explicit State(CkMigrateMessage* msg) : PUP::able(msg) {}
     201             : };
     202             : }  // namespace control_system::size