HYGOV Documentation + Implementation

CHANGELOG.md

@@ -67,6 +67,7 @@
 - Added `ConstantSignalSource` component as first use case for `BusToSignalAdapter`.
 - Added IDA option to suppress algebraic variables in local error tests.
 - Removed `COO_Matrix` class.
+- Added `HYGOV` governor model implementation for PhasorDynamics.
 
 ## v0.1
 

GridKit/CommonMath.hpp

@@ -162,7 +162,31 @@ namespace GridKit
     }
 
     /**
-     * @brief Smooth two-sided deadband function
+     * @brief Smooth Type 1 no-offset two-sided deadband function
+     *
+     * Smooth approximation to a deadband that returns zero inside the band and
+     * passes the input through unchanged outside the band.
+     *
+     * @tparam ScalarT - scalar data type
+     * @tparam RealT - Real data type (see GridKit::ScalarTraits<ScalarT>::RealT)
+     *
+     * @param[in] x - Input signal
+     * @param[in] lower - Lower breakpoint
+     * @param[in] upper - Upper breakpoint
+     * @return Smooth no-offset deadbanded value
+     */
+    template <class ScalarT, typename RealT>
+    __attribute__((always_inline)) inline ScalarT deadband1(
+        const ScalarT x,
+        const RealT   lower,
+        const RealT   upper)
+    {
+      assert(lower <= upper);
+      return x * (sigmoid(lower - x) + sigmoid(x - upper));
+    }
+
+    /**
+     * @brief Smooth Type 2 offset two-sided deadband function
      *
      * Smooth approximation to x - min(max(x, lower), upper), composed from the
      * smooth ramp function.
@@ -173,10 +197,10 @@ namespace GridKit
      * @param[in] x - Input signal
      * @param[in] lower - Lower breakpoint
      * @param[in] upper - Upper breakpoint
-     * @return Smooth deadbanded value
+     * @return Smooth offset deadbanded value
      */
     template <class ScalarT, typename RealT>
-    __attribute__((always_inline)) inline ScalarT deadband(
+    __attribute__((always_inline)) inline ScalarT deadband2(
         const ScalarT x,
         const RealT   lower,
         const RealT   upper)

GridKit/Model/PhasorDynamics/Component.hpp

@@ -112,6 +112,15 @@ namespace GridKit
         return abs_tol_;
       }
 
+      int setAbsoluteTolerance(RealT rel_tol) override
+      {
+        for (IdxT i = 0; i < size_; ++i)
+        {
+          abs_tol_[static_cast<size_t>(i)] = rel_tol;
+        }
+        return 0;
+      }
+
       std::vector<ScalarT>& getResidual() override
       {
         return f_;

GridKit/Model/PhasorDynamics/ComponentLibrary.hpp

@@ -7,6 +7,7 @@
 #include <GridKit/Model/PhasorDynamics/BusToSignalAdapter/BusToSignalAdapter.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/SexsPti.hpp>
+#include <GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.hpp>
 #include <GridKit/Model/PhasorDynamics/Governor/Tgov1/Tgov1.hpp>
 #include <GridKit/Model/PhasorDynamics/Load/LoadZ/LoadZ.hpp>
 #include <GridKit/Model/PhasorDynamics/Load/LoadZIP/LoadZIP.hpp>

GridKit/Model/PhasorDynamics/Governor/CMakeLists.txt

@@ -4,3 +4,4 @@
 # ]]
 
 add_subdirectory(Tgov1)
+add_subdirectory(HYGOV)

GridKit/Model/PhasorDynamics/Governor/HYGOV/CMakeLists.txt

@@ -0,0 +1,54 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers Hygov.hpp HygovData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(
+    phasor_dynamics_governor_hygov
+    SOURCES HygovEnzyme.cpp
+    HEADERS ${_install_headers}
+    INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
+    LINK_LIBRARIES
+      PUBLIC
+      GridKit::phasor_dynamics_core
+      PUBLIC
+      GridKit::phasor_dynamics_signal
+      PRIVATE
+      ClangEnzymeFlags
+    COMPILE_OPTIONS
+      PRIVATE
+      -mllvm
+      -enzyme-auto-sparsity=1
+      -fno-math-errno)
+else()
+  gridkit_add_library(
+    phasor_dynamics_governor_hygov
+    SOURCES Hygov.cpp
+    HEADERS ${_install_headers}
+    INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
+    LINK_LIBRARIES
+      PUBLIC
+      GridKit::phasor_dynamics_core
+      PUBLIC
+      GridKit::phasor_dynamics_signal)
+endif()
+
+gridkit_add_library(
+  phasor_dynamics_governor_hygov_dependency_tracking
+  SOURCES HygovDependencyTracking.cpp
+  INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
+  LINK_LIBRARIES
+    PUBLIC
+    GridKit::phasor_dynamics_core
+    PUBLIC
+    GridKit::phasor_dynamics_signal_dependency_tracking)
+
+target_link_libraries(
+  phasor_dynamics_components
+  INTERFACE GridKit::phasor_dynamics_governor_hygov)
+target_link_libraries(
+  phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_governor_hygov_dependency_tracking)

GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.cpp

@@ -0,0 +1,27 @@
+/**
+ * @file Hygov.cpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Non-Enzyme instantiation for the HYGOV governor model.
+ */
+
+#include "HygovImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Governor
+    {
+      template <typename scalar_type, typename index_type>
+      int Hygov<scalar_type, index_type>::evaluateJacobian()
+      {
+        Log::misc() << "Evaluate Jacobian for Hygov..." << std::endl;
+        Log::misc() << "Jacobian evaluation is not implemented!" << std::endl;
+        return 0;
+      }
+
+      template class Hygov<double, long int>;
+      template class Hygov<double, size_t>;
+    } // namespace Governor
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.hpp

@@ -0,0 +1,157 @@
+/**
+ * @file Hygov.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Declaration of the HYGOV governor model.
+ */
+
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <memory>
+#include <vector>
+
+#include <GridKit/Model/PhasorDynamics/Component.hpp>
+#include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
+#include <GridKit/Model/PhasorDynamics/Governor/HYGOV/HygovData.hpp>
+#include <GridKit/Model/VariableMonitor.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    template <typename scalar_type, typename index_type>
+    class SignalNode;
+
+    namespace Governor
+    {
+      /// Internal variables of a `Hygov`.
+      enum class HygovInternalVariables : size_t
+      {
+        XN,      ///< Speed lead-lag denominator state
+        XF,      ///< Governor error filter output
+        C,       ///< Desired-gate position
+        G,       ///< Gate position
+        Q,       ///< Turbine flow
+        OMEGADB, ///< Deadbanded speed deviation
+        EF,      ///< Governor error into the filter
+        FC,      ///< Desired-gate derivative target
+        RC,      ///< Rate-limited desired-gate derivative target
+        PGV,     ///< Nonlinear gate-to-power curve output
+        H,       ///< Turbine head
+        PMECH,   ///< Mechanical-power output
+        MAXIMUM,
+      };
+
+      /// External variables of a `Hygov`.
+      enum class HygovExternalVariables : size_t
+      {
+        OMEGA, ///< Machine speed deviation
+        PREF,  ///< Active-power/load reference
+        PAUX,  ///< Auxiliary power input
+        MAXIMUM,
+      };
+
+      template <typename scalar_type, typename index_type>
+      class Hygov : public Component<scalar_type, index_type>
+      {
+        using Component<scalar_type, index_type>::alpha_;
+        using Component<scalar_type, index_type>::abs_tol_;
+        using Component<scalar_type, index_type>::f_;
+        using Component<scalar_type, index_type>::gridkit_component_id_;
+        using Component<scalar_type, index_type>::J_cols_buffer_;
+        using Component<scalar_type, index_type>::J_rows_buffer_;
+        using Component<scalar_type, index_type>::J_vals_buffer_;
+        using Component<scalar_type, index_type>::nnz_;
+        using Component<scalar_type, index_type>::residual_indices_;
+        using Component<scalar_type, index_type>::size_;
+        using Component<scalar_type, index_type>::tag_;
+        using Component<scalar_type, index_type>::va_system_base_;
+        using Component<scalar_type, index_type>::variable_indices_;
+        using Component<scalar_type, index_type>::wb_;
+        using Component<scalar_type, index_type>::y_;
+        using Component<scalar_type, index_type>::yp_;
+
+      public:
+        using ScalarT    = scalar_type;
+        using IdxT       = index_type;
+        using RealT      = typename Component<ScalarT, IdxT>::RealT;
+        using SignalT    = SignalNode<ScalarT, IdxT>;
+        using ModelDataT = HygovData<RealT, IdxT>;
+        using MonitorT   = Model::VariableMonitor<Hygov, HygovData>;
+
+        Hygov();
+        Hygov(const ModelDataT& data);
+        ~Hygov();
+
+        int setGridKitComponentID(IdxT) override final;
+        int allocate() override final;
+        int verify() const override final;
+        int initialize() override final;
+        int tagDifferentiable() override final;
+        int setAbsoluteTolerance(RealT) override final;
+        int evaluateResidual() override final;
+        int evaluateJacobian() override final;
+
+        auto getSignals()
+            -> ComponentSignals<ScalarT,
+                                IdxT,
+                                HygovInternalVariables,
+                                HygovExternalVariables>&
+        {
+          return signals_;
+        }
+
+        const Model::VariableMonitorBase* getMonitor() const override;
+
+        __attribute__((always_inline)) inline int evaluateInternalResidual(
+            const ScalarT*, const ScalarT*, const ScalarT*, const ScalarT*, ScalarT*);
+
+      private:
+        void initModelParams(const ModelDataT& data);
+        void initializeMonitor();
+        void setDerivedParams();
+
+        ScalarT gatePower(ScalarT gate) const;
+        RealT   invertGatePower(RealT pgv) const;
+        ScalarT toComponentBase(ScalarT value) const;
+        ScalarT toSystemBase(ScalarT value) const;
+
+        static constexpr RealT TIME_CONSTANT_MINIMUM = static_cast<RealT>(1.0e-3);
+
+        RealT                Trate_{0};
+        RealT                Rperm_{0};
+        RealT                Rtemp_{0};
+        RealT                Tr_{0};
+        RealT                Tf_{0};
+        RealT                Tg_{0};
+        RealT                Velm_{0};
+        RealT                Gmax_{0};
+        RealT                Gmin_{0};
+        RealT                Tw_{0};
+        RealT                At_{0};
+        RealT                Dturb_{0};
+        RealT                Qnl_{0};
+        RealT                Tn_{0};
+        RealT                Tnp_{0};
+        RealT                leadlag_gain_{0};
+        RealT                db1_{0};
+        RealT                db2_{0};
+        RealT                Hdam_{1};
+        std::array<RealT, 6> Gv_{};
+        std::array<RealT, 6> Pgv_{};
+
+        RealT va_component_base_{0};
+
+        ScalarT pref_set_{0};
+        ScalarT paux_set_{0};
+
+        ComponentSignals<ScalarT, IdxT, HygovInternalVariables, HygovExternalVariables> signals_;
+        std::unique_ptr<MonitorT>                                                       monitor_;
+
+        std::vector<ScalarT> ws_;
+        std::vector<IdxT>    ws_indices_;
+      };
+    } // namespace Governor
+  } // namespace PhasorDynamics
+} // namespace GridKit