GAST-PTI Documentation + Implementation

CHANGELOG.md

@@ -61,6 +61,7 @@
 - Added `BusToSignalAdapter` component for communicating bus voltages and injection currents.
 - Added cmake-format hooks, including in pre-commit.
 - Added off-nominal tap ratio and phase shift support to the PhasorDynamics `Branch` model.
+- Added `GASTPTI` governor model implementation for PhasorDynamics.
 
 ## v0.1
 

GridKit/Model/PhasorDynamics/ComponentLibrary.hpp

@@ -6,6 +6,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/GASTPTI/GastPti.hpp>
 #include <GridKit/Model/PhasorDynamics/Governor/Tgov1/Tgov1.hpp>
 #include <GridKit/Model/PhasorDynamics/Load/Load.hpp>
 #include <GridKit/Model/PhasorDynamics/LoadZIP/LoadZIP.hpp>

GridKit/Model/PhasorDynamics/Governor/CMakeLists.txt

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

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

@@ -0,0 +1,54 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers GastPti.hpp GastPtiData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(
+    phasor_dynamics_governor_gastpti
+    SOURCES GastPtiEnzyme.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_gastpti
+    SOURCES GastPti.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_gastpti_dependency_tracking
+  SOURCES GastPtiDependencyTracking.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_gastpti)
+target_link_libraries(
+  phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_governor_gastpti_dependency_tracking)

GridKit/Model/PhasorDynamics/Governor/GASTPTI/GastPti.cpp

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

GridKit/Model/PhasorDynamics/Governor/GASTPTI/GastPti.hpp

@@ -0,0 +1,131 @@
+/**
+ * @file GastPti.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Declaration of the GASTPTI governor model.
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <memory>
+#include <vector>
+
+#include <GridKit/Model/PhasorDynamics/Component.hpp>
+#include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
+#include <GridKit/Model/PhasorDynamics/Governor/GASTPTI/GastPtiData.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 `GastPti`.
+      enum class GastPtiInternalVariables : size_t
+      {
+        XVALVE, ///< Fuel-valve state
+        XFLOW,  ///< Fuel-flow state
+        XTEMP,  ///< Exhaust-temperature feedback state
+        VLOAD,  ///< Speed/load fuel demand
+        VTEMP,  ///< Temperature-limit fuel demand
+        VLV,    ///< Low-value gate output
+        PMECH,  ///< Mechanical-power output
+        MAXIMUM,
+      };
+
+      /// External variables of a `GastPti`.
+      enum class GastPtiExternalVariables : size_t
+      {
+        OMEGA, ///< Machine speed deviation
+        PREF,  ///< Active-power/load reference
+        MAXIMUM,
+      };
+
+      template <typename scalar_type, typename index_type>
+      class GastPti : public Component<scalar_type, index_type>
+      {
+        using Component<scalar_type, index_type>::alpha_;
+        using Component<scalar_type, index_type>::f_;
+        using Component<scalar_type, index_type>::gridkit_component_id_;
+        using Component<scalar_type, index_type>::J_;
+        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>::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 ModelDataT = GastPtiData<RealT, IdxT>;
+        using SignalT    = SignalNode<ScalarT, IdxT>;
+        using MonitorT   = Model::VariableMonitor<GastPti, GastPtiData>;
+
+        GastPti();
+        GastPti(const ModelDataT& data);
+        ~GastPti() override;
+
+        int setGridKitComponentID(IdxT) override final;
+        int allocate() override final;
+        int verify() const override final;
+        int initialize() override final;
+        int tagDifferentiable() override final;
+        int evaluateResidual() override final;
+        int evaluateJacobian() override final;
+
+        auto getSignals()
+            -> ComponentSignals<ScalarT,
+                                IdxT,
+                                GastPtiInternalVariables,
+                                GastPtiExternalVariables>&
+        {
+          return signals_;
+        }
+
+        const Model::VariableMonitorBase* getMonitor() const override;
+
+        __attribute__((always_inline)) inline int evaluateInternalResidual(
+            ScalarT*, ScalarT*, ScalarT*, ScalarT*, ScalarT*);
+
+      private:
+        void    initModelParams(const ModelDataT& data);
+        void    initializeMonitor();
+        ScalarT toComponentBase(ScalarT value) const;
+        ScalarT toSystemBase(ScalarT value) const;
+
+        RealT R_{0};
+        RealT T1_{0};
+        RealT T2_{0};
+        RealT T3_{0};
+        RealT At_{0};
+        RealT Kt_{0};
+        RealT Vmax_{0};
+        RealT Vmin_{0};
+        RealT Dturb_{0};
+        RealT Trate_{0};
+        RealT va_component_base_{0};
+
+        int parameter_error_count_{0};
+
+        ScalarT pref_set_{0};
+
+        ComponentSignals<ScalarT, IdxT, GastPtiInternalVariables, GastPtiExternalVariables> signals_;
+        std::unique_ptr<MonitorT>                                                           monitor_;
+
+        std::vector<ScalarT> ws_;
+        std::vector<IdxT>    ws_indices_;
+      };
+    } // namespace Governor
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Governor/GASTPTI/GastPtiData.hpp

@@ -0,0 +1,68 @@
+/**
+ * @file GastPtiData.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Modeling data for the GASTPTI governor model.
+ */
+
+#pragma once
+
+#include <GridKit/Model/PhasorDynamics/ComponentData.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Governor
+    {
+      /// Parameter keys for the GASTPTI governor model.
+      enum class GastPtiParameters
+      {
+        R,     ///< Permanent droop
+        T1,    ///< Fuel-valve time constant
+        T2,    ///< Fuel-flow time constant
+        T3,    ///< Exhaust-temperature time constant
+        At,    ///< Ambient-temperature load limit
+        Kt,    ///< Exhaust-temperature feedback gain
+        Vmax,  ///< Maximum fuel-valve/turbine-power limit
+        Vmin,  ///< Minimum fuel-valve/turbine-power limit
+        Dturb, ///< Turbine damping coefficient
+        Trate  ///< Turbine-rating power base
+      };
+
+      /// Ports for the GASTPTI governor model.
+      enum class GastPtiPorts
+      {
+        bus,   ///< Optional terminal bus ID for case-format compatibility
+        speed, ///< Machine speed-deviation signal ID
+        pmech, ///< Mechanical-power output signal ID
+        pref   ///< Optional active-power/load reference signal ID
+      };
+
+      /// Variables available through the monitor interface.
+      enum class GastPtiMonitorableVariables
+      {
+        pmech,       ///< Mechanical power output
+        fuelvalve,   ///< Fuel-valve state
+        fuelflow,    ///< Fuel-flow state
+        exhausttemp, ///< Exhaust-temperature feedback state
+        vload,       ///< Speed/load fuel demand
+        vtemp,       ///< Temperature-limit fuel demand
+        vlv          ///< Low-value gate output
+      };
+
+      template <typename real_type, typename index_type>
+      struct GastPtiData : public ComponentData<real_type,
+                                                index_type,
+                                                GastPtiParameters,
+                                                GastPtiPorts,
+                                                GastPtiMonitorableVariables>
+      {
+        GastPtiData() = default;
+
+        using Parameters           = GastPtiParameters;
+        using Ports                = GastPtiPorts;
+        using MonitorableVariables = GastPtiMonitorableVariables;
+      };
+    } // namespace Governor
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Governor/GASTPTI/GastPtiDependencyTracking.cpp

@@ -0,0 +1,27 @@
+/**
+ * @file GastPtiDependencyTracking.cpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Dependency-tracking instantiations for the GASTPTI governor model.
+ */
+
+#include "GastPtiImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Governor
+    {
+      template <typename scalar_type, typename index_type>
+      int GastPti<scalar_type, index_type>::evaluateJacobian()
+      {
+        Log::misc() << "Evaluate Jacobian for GastPti..." << std::endl;
+        Log::misc() << "Jacobian evaluation is not implemented!" << std::endl;
+        return 0;
+      }
+
+      template class GastPti<DependencyTracking::Variable, long int>;
+      template class GastPti<DependencyTracking::Variable, size_t>;
+    } // namespace Governor
+  } // namespace PhasorDynamics
+} // namespace GridKit