REGCA Implementation

CHANGELOG.md

@@ -56,6 +56,7 @@
 - Added node objects to `PowerElectronics` module & updated all examples to make use of them.
 - Separated internal and external residuals of `PowerElectronics` models.
 - Added `CliArgs` class for better management of command-line options.
+- Added `REGCA` converter model implementation for PhasorDynamics.
 
 ## v0.1
 

GridKit/Model/PhasorDynamics/CMakeLists.txt

@@ -35,6 +35,7 @@ target_link_libraries(phasor_dynamics_components_dependency_tracking
 add_subdirectory(Branch)
 add_subdirectory(Bus)
 add_subdirectory(BusFault)
+add_subdirectory(Converter)
 add_subdirectory(Exciter)
 add_subdirectory(Governor)
 add_subdirectory(Load)

GridKit/Model/PhasorDynamics/ComponentLibrary.hpp

@@ -3,6 +3,7 @@
 #include <GridKit/Model/PhasorDynamics/Branch/Branch.hpp>
 #include <GridKit/Model/PhasorDynamics/Bus/Bus.hpp>
 #include <GridKit/Model/PhasorDynamics/BusFault/BusFault.hpp>
+#include <GridKit/Model/PhasorDynamics/Converter/REGCA/Regca.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/SexsPti.hpp>
 #include <GridKit/Model/PhasorDynamics/Governor/Tgov1/Tgov1.hpp>

GridKit/Model/PhasorDynamics/Converter/CMakeLists.txt

@@ -0,0 +1,6 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+add_subdirectory(REGCA)

GridKit/Model/PhasorDynamics/Converter/REGCA/CMakeLists.txt

@@ -0,0 +1,49 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers
+  Regca.hpp
+  RegcaData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(phasor_dynamics_converter_regca
+    SOURCES
+      RegcaEnzyme.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_converter_regca
+    SOURCES
+      Regca.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_converter_regca_dependency_tracking
+  SOURCES
+    RegcaDependencyTracking.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_converter_regca)
+target_link_libraries(phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_converter_regca_dependency_tracking)

GridKit/Model/PhasorDynamics/Converter/REGCA/README.md

@@ -25,7 +25,7 @@ Symbol                           | Units    | Description
 ---------------------------------|----------|-------------------------------------------------------|---------------|------
 $P_{\mathrm{0}}$                 | [p.u.]   | Initial active power injection                        |               | On system base
 $Q_{\mathrm{0}}$                 | [p.u.]   | Initial reactive power injection                      |               | On system base
-$S^{\mathrm{conv}}$              | [MVA]    | Converter/model power base                            | TBD           |
+$S^{\text{base}}$                | [MVA]    | REGCA model power base                                | TBD           | JSON key: `mva_base`
 $T_{\mathrm{g}}$                 | [sec]    | Converter current-control lag time constant           | TBD           |
 $T_M$                            | [sec]    | Terminal voltage sensor time constant                 | TBD           | Block name: `Tfltr`
 $R_{\mathrm{q}}^{\max}$           | [p.u./s] | Reactive-current recovery positive rate limit         | TBD           | Block name: `Iqrmax`
@@ -45,7 +45,7 @@ Implementations should reject or report invalid parameter sets:
 
 ```math
 \begin{aligned}
-  S^{\mathrm{conv}} &> 0 &
+  S^{\text{base}} &> 0 &
   T_{\mathrm{g}} &> 0 &
   T_M &> 0 \\
   R_{\mathrm{p}}^{\max} &> 0 &
@@ -241,8 +241,8 @@ REGCA currents:
 
 ```math
 \begin{aligned}
-  I_{\mathrm{r}}^{\mathrm{inj}} &:= I_{\mathrm{r}}\dfrac{S^{\mathrm{conv}}}{S^{\mathrm{sys}}} \\
-  I_{\mathrm{i}}^{\mathrm{inj}} &:= I_{\mathrm{i}}\dfrac{S^{\mathrm{conv}}}{S^{\mathrm{sys}}}
+  I_{\mathrm{r}}^{\mathrm{inj}} &:= I_{\mathrm{r}}\dfrac{S^{\text{base}}}{S^{\text{sys}}} \\
+  I_{\mathrm{i}}^{\mathrm{inj}} &:= I_{\mathrm{i}}\dfrac{S^{\text{base}}}{S^{\text{sys}}}
 \end{aligned}
 ```
 
@@ -257,9 +257,9 @@ steady-state initial values:
 \begin{aligned}
   V_T                    &= \sqrt{V_\mathrm{r}^2 + V_\mathrm{i}^2} \\
   I_\mathrm{r0}           &= \dfrac{P_0 V_\mathrm{r} + Q_0 V_\mathrm{i}}{V_T^2}
-                              \dfrac{S^\mathrm{sys}}{S^\mathrm{conv}} \\
+                              \dfrac{S^{\text{sys}}}{S^{\text{base}}} \\
   I_\mathrm{i0}           &= \dfrac{P_0 V_\mathrm{i} - Q_0 V_\mathrm{r}}{V_T^2}
-                              \dfrac{S^\mathrm{sys}}{S^\mathrm{conv}} \\
+                              \dfrac{S^{\text{sys}}}{S^{\text{base}}} \\
   V_{M0}                  &= V_T \\
   I_{L0}                  &= \text{linseg}(V_T;\ V_{L0},\ V_{L1},\ I_{L1}) \\
   I_\mathrm{p0}           &= \dfrac{I_\mathrm{r0}}

GridKit/Model/PhasorDynamics/Converter/REGCA/Regca.cpp

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

GridKit/Model/PhasorDynamics/Converter/REGCA/Regca.hpp

@@ -0,0 +1,193 @@
+/**
+ * @file Regca.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Declaration of the REGCA phasor-dynamics converter 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/Converter/REGCA/RegcaData.hpp>
+#include <GridKit/Model/VariableMonitor.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    template <class ScalarT, typename IdxT>
+    class BusBase;
+
+    template <class ScalarT, typename IdxT>
+    class SignalNode;
+  } // namespace PhasorDynamics
+} // namespace GridKit
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Converter
+    {
+      /// Internal variables of a `Regca`
+      enum class RegcaInternalVariables : size_t
+      {
+        VM,      ///< Filtered terminal voltage
+        IQ,      ///< Reactive-current state
+        IP,      ///< Active-current state
+        VT,      ///< Terminal voltage magnitude
+        II,      ///< Imaginary injected current
+        IQEXTRA, ///< HVRCM extra reactive current
+        IL,      ///< LVPL upper-limit current curve
+        IR,      ///< Real injected current
+        LP,      ///< Active-current lower rate bound
+        UP,      ///< Active-current upper rate bound
+        MAXIMUM,
+      };
+
+      /// External variables of a `Regca`
+      enum class RegcaExternalVariables : size_t
+      {
+        IPCMD, ///< Active-current command signal
+        IQCMD, ///< Reactive-current command signal
+        MAXIMUM,
+      };
+
+      template <class ScalarT, typename IdxT>
+      class Regca : public Component<ScalarT, IdxT>
+      {
+        using Component<ScalarT, IdxT>::gridkit_component_id_;
+        using Component<ScalarT, IdxT>::alpha_;
+        using Component<ScalarT, IdxT>::f_;
+        using Component<ScalarT, IdxT>::h_;
+        using Component<ScalarT, IdxT>::J_;
+        using Component<ScalarT, IdxT>::J_cols_buffer_;
+        using Component<ScalarT, IdxT>::J_rows_buffer_;
+        using Component<ScalarT, IdxT>::J_vals_buffer_;
+        using Component<ScalarT, IdxT>::nnz_;
+        using Component<ScalarT, IdxT>::residual_indices_;
+        using Component<ScalarT, IdxT>::size_;
+        using Component<ScalarT, IdxT>::tag_;
+        using Component<ScalarT, IdxT>::time_;
+        using Component<ScalarT, IdxT>::va_system_base_;
+        using Component<ScalarT, IdxT>::variable_indices_;
+        using Component<ScalarT, IdxT>::wb_;
+        using Component<ScalarT, IdxT>::y_;
+        using Component<ScalarT, IdxT>::yp_;
+
+      public:
+        using RealT           = typename Component<ScalarT, IdxT>::RealT;
+        using bus_type        = BusBase<ScalarT, IdxT>;
+        using signal_type     = SignalNode<ScalarT, IdxT>;
+        using model_data_type = RegcaData<RealT, IdxT>;
+        using MonitorT        = Model::VariableMonitor<Regca, RegcaData>;
+
+        Regca(bus_type* bus);
+        Regca(bus_type* bus, const model_data_type& data);
+        ~Regca();
+
+        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,
+                                RegcaInternalVariables,
+                                RegcaExternalVariables>&
+        {
+          return signals_;
+        }
+
+        const Model::VariableMonitorBase* getMonitor() const override;
+
+        __attribute__((always_inline)) inline int evaluateInternalResidual(
+            ScalarT*, ScalarT*, ScalarT*, ScalarT*, ScalarT*);
+        __attribute__((always_inline)) inline int evaluateBusResidual(
+            ScalarT*, ScalarT*, ScalarT*, ScalarT*);
+
+      private:
+        void initializeParameters(const model_data_type& data);
+        void initializeMonitor();
+        void setDerivedParameters();
+
+        ScalarT toComponentBase(ScalarT value) const
+        {
+          return value * va_system_base_ / va_converter_base_;
+        }
+
+        ScalarT toSystemBase(ScalarT value) const
+        {
+          return value / toComponentBase(static_cast<ScalarT>(ONE<RealT>));
+        }
+
+        ScalarT activeCurrentLowerRateBound(ScalarT ip) const;
+        ScalarT activeCurrentUpperRateBound(ScalarT ip, ScalarT il) const;
+
+        ScalarT& Vr()
+        {
+          return bus_->Vr();
+        }
+
+        ScalarT& Vi()
+        {
+          return bus_->Vi();
+        }
+
+        ScalarT& Ir()
+        {
+          return bus_->Ir();
+        }
+
+        ScalarT& Ii()
+        {
+          return bus_->Ii();
+        }
+
+        bus_type* bus_{nullptr};
+
+        RealT P0_{0};
+        RealT Q0_{0};
+        RealT mva_base_{0};
+        RealT Tg_{0};
+        RealT TM_{0};
+        RealT Rqmax_{0};
+        RealT Rqmin_{0};
+        RealT Rpmax_{0};
+        bool  sL_{false};
+        RealT IL1_{0};
+        RealT VL0_{0};
+        RealT VL1_{0};
+        RealT VA0_{0};
+        RealT VA1_{0};
+        RealT Vhvmax_{0};
+        IdxT  bus_id_{0};
+
+        IdxT  parameter_error_count_{0};
+        RealT Mp_{0};
+        RealT va_converter_base_{0};
+        RealT use_lvpl_{0};
+        RealT bypass_lvpl_{1};
+        RealT iq_use_upper_{0};
+        RealT iq_use_lower_{1};
+
+        ScalarT ipcmd_set_{0};
+        ScalarT iqcmd_set_{0};
+
+        ComponentSignals<ScalarT, IdxT, RegcaInternalVariables, RegcaExternalVariables> signals_;
+        std::unique_ptr<MonitorT>                                                       monitor_;
+
+        std::vector<ScalarT> ws_;
+        std::vector<IdxT>    ws_indices_;
+      };
+    } // namespace Converter
+  } // namespace PhasorDynamics
+} // namespace GridKit