Stabilizer Docs + IEEEST Implementation

CHANGELOG.md

@@ -20,7 +20,7 @@
 - Added clang formatting pre-commit.
 - CMake fixes.
 - Fixed warnings, memory leaks, and failed asserts.
-- Added Tgov1 example. 
+- Added Tgov1 example.
 - Added 10 generator example.
 - Improved data structures.
 - Removed dead code.
@@ -50,6 +50,7 @@
 - Added phasor dynamics application to generalize examples
 - Added LoadZIP model component type.
 - Added component model developer checklist to a README file.
+- Added IEEEST Stabilizer Model
 
 ## v0.1
 

GridKit/Model/PhasorDynamics/CMakeLists.txt

@@ -37,6 +37,7 @@ add_subdirectory(Exciter)
 add_subdirectory(Governor)
 add_subdirectory(Load)
 add_subdirectory(LoadZIP)
+add_subdirectory(Stabilizer)
 add_subdirectory(SynchronousMachine)
 
 add_subdirectory(SignalNode)

GridKit/Model/PhasorDynamics/ComponentLibrary.hpp

@@ -8,5 +8,6 @@
 #include <GridKit/Model/PhasorDynamics/Load/Load.hpp>
 #include <GridKit/Model/PhasorDynamics/LoadZIP/LoadZIP.hpp>
 #include <GridKit/Model/PhasorDynamics/SignalNode/SignalNode.hpp>
+#include <GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/Ieeest.hpp>
 #include <GridKit/Model/PhasorDynamics/SynchronousMachine/GENROUwS/Genrou.hpp>
 #include <GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/GenClassical.hpp>

GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1.hpp

@@ -60,6 +60,7 @@ namespace GridKit
         OMEGA, ///< Generator speed deviation
         VREAL, ///< Real bus voltage
         VIMAG, ///< Imaginary bus voltage
+        VS,    ///< Stabilizer output signal
         MAXIMUM,
       };
 

GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1Data.hpp

@@ -40,6 +40,7 @@ namespace GridKit
         bus,   ///< Unique ID of the terminal bus
         speed, ///< Unique ID of the generator speed signal
         efd,   ///< Unique ID of the output efd signal
+        vs,    ///< Unique ID of the stabilizer output signal (optional)
       };
 
       /// Variables able to be monitored for a IEEET1 Exciter model

GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1Impl.hpp

@@ -129,10 +129,12 @@ namespace GridKit
         wb_.resize(2);
 
         // Resize signal variable data
-        ws_.resize(1);
-        ws_indices_.resize(1);
+        ws_.resize(2);
+        ws_indices_.resize(2);
         ws_[0]         = 0.0;
         ws_indices_[0] = INVALID_INDEX<IdxT>;
+        ws_[1]         = 0.0;
+        ws_indices_[1] = INVALID_INDEX<IdxT>;
 
         // Default variable and residual index mapping to local index
         for (IdxT j = 0; j < size_; ++j)
@@ -157,6 +159,7 @@ namespace GridKit
       int Ieeet1<ScalarT, IdxT>::verify() const
       {
         static constexpr auto OMEGA = Ieeet1ExternalVariables::OMEGA;
+        static constexpr auto VS    = Ieeet1ExternalVariables::VS;
 
         int ret = 0;
 
@@ -169,6 +172,15 @@ namespace GridKit
           }
         }
 
+        if (signals_.template isAttached<VS>())
+        {
+          if (!signals_.template isLinked<VS>())
+          {
+            Log::error() << "Ieeet1: VS signal attached with no linked source\n";
+            ret += 1;
+          }
+        }
+
         return ret;
       }
 
@@ -202,24 +214,29 @@ namespace GridKit
         ScalarT vimag = bus_->Vi();
         ScalarT Ec    = std::sqrt(vreal * vreal + vimag * vimag);
 
-        // Derived from External initial values
-        ScalarT vr  = Ke_ * efd0;
+        // Saturation at the initial operating point
+        ScalarT efd_sat = (efd0 - SA_) * Math::sigmoid(efd0 - SA_);
+        ScalarT ksat0   = SB_ * efd_sat * efd_sat;
+        ScalarT ve0     = ksat0 * efd0;
+
+        // Derived from External initial values (includes saturation)
+        ScalarT vr  = Ke_ * efd0 + ve0;
         ScalarT vfx = Kf_ / Tf_ * efd0;
-        ScalarT vtr = Ke_ / Ka_ * efd0;
+        ScalarT vtr = vr / Ka_;
 
         // Vref (setpoint = terminal + error)
         vref_ = Ec + vtr;
 
         // IVP for Internal Variables
-        y_[0] = Ec;   // y0 - vts  - Sensed term volt
-        y_[1] = vr;   // y1 - vr   - Voltage reg
-        y_[2] = efd0; // y2 - efdp - Efd pre mult
-        y_[3] = vfx;  // y3 - vfx  - Exciter feedback
-        y_[4] = vtr;  // y4 - vtr  - Term Volt Err
-        y_[5] = 0;    // y5 - vf   - Feedback volt
-        y_[6] = 0;    // y6 - ve   - Excit. Cntrl Volt
-        y_[7] = efd0; // y7 - efd  - Efd
-        y_[8] = 0;    // y8 - ksat - Saturation
+        y_[0] = Ec;    // y0 - vts  - Sensed term volt
+        y_[1] = vr;    // y1 - vr   - Voltage reg
+        y_[2] = efd0;  // y2 - efdp - Efd pre mult
+        y_[3] = vfx;   // y3 - vfx  - Exciter feedback
+        y_[4] = vtr;   // y4 - vtr  - Term Volt Err
+        y_[5] = 0;     // y5 - vf   - Feedback volt
+        y_[6] = ve0;   // y6 - ve   - Excit. Cntrl Volt
+        y_[7] = efd0;  // y7 - efd  - Efd
+        y_[8] = ksat0; // y8 - ksat - Saturation
 
         // Steady State Conditions
         yp_[0] = 0.0;
@@ -294,7 +311,8 @@ namespace GridKit
         ScalarT vfx_dot  = yp[3];
 
         // Set signal variable aliases
-        ScalarT omega = ws[0];
+        ScalarT omega     = ws[0];
+        ScalarT vs_signal = ws[1];
 
         // The 'pre-limit' derivative of Pv
         ScalarT func            = -vr + Ka_ * vtr;
@@ -308,7 +326,7 @@ namespace GridKit
         f[3] = -vfx_dot + vf / Tf_;
 
         // Internal Algebraic Equations
-        f[4] = -vts + vref_ + vUEL_ + vOEL_ + vS_ - vtr - vf;
+        f[4] = -vts + vref_ + vUEL_ + vOEL_ + vs_signal - vtr - vf;
         f[5] = -vf + (efdp * Kf_) / Tf_ - vfx;
         f[6] = -ve + ksat * efdp;
         f[7] = -efd + efdp + omega * efdp * Ispdlim_;
@@ -341,6 +359,15 @@ namespace GridKit
           ws_indices_[0] = signals_.template readExternalVariableIndex<Ieeet1ExternalVariables::OMEGA>();
         }
 
+        // VS signal (stabilizer output, optional)
+        ws_[1]         = 0.0;
+        ws_indices_[1] = INVALID_INDEX<IdxT>;
+        if (signals_.template isAttached<Ieeet1ExternalVariables::VS>())
+        {
+          ws_[1]         = signals_.template readExternalVariable<Ieeet1ExternalVariables::VS>();
+          ws_indices_[1] = signals_.template readExternalVariableIndex<Ieeet1ExternalVariables::VS>();
+        }
+
         // Bus voltages
         wb_[0] = bus_->Vr();
         wb_[1] = bus_->Vi();

GridKit/Model/PhasorDynamics/INPUT_FORMAT.md

@@ -85,7 +85,7 @@ a bus and has the following fields:
   `class`            | A string indicating the class of node. See the table below for more information
   `name`             | Optional string containing the name of the node. This may be empty or non-unique
   `init`             | Optional object mapping string variable names to floating point values, specifying default voltages or signal values. The available initialization variables are dependent upon the node class. Any variables missing will be given default values, which are specified beneath the table below. If this object is missing, all variables will be given default values. See the table below for more information
-  `v_base`           | Optional floating point value giving the voltage base in volts (V). 
+  `v_base`           | Optional floating point value giving the voltage base in volts (V).
   `mon`              | Optional field, which is an array specifying variables to monitor the value of in an output channel. Available variables include all the initialization variables, along with others as determined by the node class. See the table below for more information
   `freq_base`        | Optional field to override the system frequency base at this bus
   `va_base`          | Optional field to override the system power base at this bus
@@ -146,7 +146,8 @@ are specified:
   `Genrou`      | 6th order machine model                              | `bus`, `pmech`\*, `speed`\*, `efd`\*    | `p0`, `q0`, `H`, `D`, `Ra`, `Tdop`, `Tdopp`, `Tqopp`, `Tqop`, `Xd`, `Xdp`, `Xdpp`, `Xq`, `Xqp`, `Xqpp`, `Xl`, `S10`, `S12`, `mva_base`  | `ir`, `ii`, `p`, `q`, `delta`, `omega`, `speed`
   `GenClassical`| the classical machine model                          | `bus`, `pmech`\*, `speed`\*, `efd`\*  | `p0`, `q0`, `H`, `D`, `Ra`, `Xdp`, `mva_base` | `ir`, `ii`, `p`, `q`, `delta`, `omega`
   `Tgov1 `      | the TGOV1 governor model                             | `pmech`, `speed`                 | `R`, `T1`, `T2`, `T3`, `Pvmax`, `Pvmin`, `Dt` | `none`
-  `Ieeet1`      | the IEEET1 exciter model                             | `bus`, `speed`, `efd`            | `Tr`, `Ka`, `Ta`, `Ke`, `Te`, `Kf`, `Tf`, `Vrmin`, `Vrmax`, `E1`, `E2`, `Se1`, `Se2`, `Ispdlim` | `efd`, `ksat`
+  `Ieeet1`      | the IEEET1 exciter model                             | `bus`, `speed`, `efd`, `vs`\*    | `Tr`, `Ka`, `Ta`, `Ke`, `Te`, `Kf`, `Tf`, `Vrmin`, `Vrmax`, `E1`, `E2`, `Se1`, `Se2`, `Ispdlim` | `efd`, `ksat`
+  `Ieeest`      | the IEEEST stabilizer model                          | `input`, `output`, `cutout`\*    | `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `T1`, `T2`, `T3`, `T4`, `T5`, `T6`, `Ks`, `Lsmin`, `Lsmax`, `Vcl`, `Vcu`, `Tdelay` | `vs`
   `BusFault`    | simple impedance-based fault at a bus                | `bus`, `status`\*                | `state0`, `R`, `X` | `state`, `ir`, `ii`
 
 Ports marked with \* are optional and, if missing, will be assumed to be

GridKit/Model/PhasorDynamics/Stabilizer/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(IEEEST)

GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/CMakeLists.txt

@@ -0,0 +1,50 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers
+  Ieeest.hpp
+  IeeestData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(phasor_dynamics_stabilizer_ieeest
+    SOURCES
+      IeeestEnzyme.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_stabilizer_ieeest
+    SOURCES
+      Ieeest.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_stabilizer_ieeest_dependency_tracking
+  SOURCES
+    IeeestDependencyTracking.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)
+
+# Link to interface target for all components
+target_link_libraries(phasor_dynamics_components
+  INTERFACE GridKit::phasor_dynamics_stabilizer_ieeest)
+target_link_libraries(phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_stabilizer_ieeest_dependency_tracking)

GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/Ieeest.cpp

@@ -0,0 +1,35 @@
+/**
+ * @file Ieeest.cpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Jacobian stub and template instantiations for IEEEST Stabilizer.
+ */
+
+#include "IeeestImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Stabilizer
+    {
+      /**
+       * @brief Jacobian evaluation not implemented yet
+       *
+       * @tparam ScalarT - Scalar data type
+       * @tparam IdxT    - Index data type
+       * @return int - error code, 0 = success
+       */
+      template <class ScalarT, typename IdxT>
+      int Ieeest<ScalarT, IdxT>::evaluateJacobian()
+      {
+        Log::misc() << "Evaluate Jacobian for Ieeest..." << std::endl;
+        Log::misc() << "Jacobian evaluation not implemented!" << std::endl;
+        return 0;
+      }
+
+      // Available template instantiations
+      template class Ieeest<double, long int>;
+      template class Ieeest<double, size_t>;
+    } // namespace Stabilizer
+  } // namespace PhasorDynamics
+} // namespace GridKit