REECB 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 `REECB` converter model 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)
@@ -315,22 +339,28 @@ namespace GridKit
      * @brief Smooth anti-windup indicator for a limited state variable
      *
      * @tparam ScalarT - Scalar data type
-     * @tparam RealT - Real data type (see GridKit::ScalarTraits<ScalarT>::RealT)
+     * @tparam LowerT - data type of the lower limit
+     * @tparam UpperT - data type of the upper limit
      *
      * @param[in] x - State variable
      * @param[in] f - Pre-limit derivative of the state variable
      * @param[in] limit_min - Minimum limit
      * @param[in] limit_max - Maximum limit
      * @return Scalar value in [0, 1]: 1 when dynamics should pass through,
      *         0 when integration should be blocked.
+     *
+     * @note The limit types intentionally may differ from the scalar type so
+     * that constant Real limits and algebraic-variable limits both work.
      */
-    template <class ScalarT, typename RealT>
+    template <class ScalarT, typename LowerT, typename UpperT>
     __attribute__((always_inline)) inline ScalarT indicator(
         const ScalarT x,
         const ScalarT f,
-        const RealT   limit_min,
-        const RealT   limit_max)
+        const LowerT  limit_min,
+        const UpperT  limit_max)
     {
+      using RealT = typename GridKit::ScalarTraits<ScalarT>::RealT;
+
       assert(limit_min <= limit_max);
 
       ScalarT above_min = above(x, limit_min);
@@ -350,20 +380,24 @@ namespace GridKit
      * and blocks motion that would push further into saturation.
      *
      * @tparam ScalarT - Scalar data type
-     * @tparam RealT - Real data type (see GridKit::ScalarTraits<ScalarT>::RealT)
+     * @tparam LowerT - data type of the lower limit
+     * @tparam UpperT - data type of the upper limit
      *
      * @param[in] x - Limited state or limited output signal
      * @param[in] f - Pre-limit derivative
      * @param[in] limit_min - Minimum limit
      * @param[in] limit_max - Maximum limit
      * @return Smooth anti-windup limited derivative
+     *
+     * @note The limit types intentionally may differ from the scalar type so
+     * that constant Real limits and algebraic-variable limits both work.
      */
-    template <class ScalarT, typename RealT>
+    template <class ScalarT, typename LowerT, typename UpperT>
     __attribute__((always_inline)) inline ScalarT antiwindup(
         const ScalarT x,
         const ScalarT f,
-        const RealT   limit_min,
-        const RealT   limit_max)
+        const LowerT  limit_min,
+        const UpperT  limit_max)
     {
       return indicator(x, f, limit_min, limit_max) * f;
     }

GridKit/Model/PhasorDynamics/CMakeLists.txt

@@ -33,6 +33,7 @@ add_subdirectory(Branch)
 add_subdirectory(Bus)
 add_subdirectory(BusFault)
 add_subdirectory(BusToSignalAdapter)
+add_subdirectory(Converter)
 add_subdirectory(Exciter)
 add_subdirectory(Governor)
 add_subdirectory(Load)

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

@@ -5,6 +5,7 @@
 #include <GridKit/Model/PhasorDynamics/Bus/BusInfinite.hpp>
 #include <GridKit/Model/PhasorDynamics/BusFault/BusFault.hpp>
 #include <GridKit/Model/PhasorDynamics/BusToSignalAdapter/BusToSignalAdapter.hpp>
+#include <GridKit/Model/PhasorDynamics/Converter/REECB/Reecb.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(REECB)

GridKit/Model/PhasorDynamics/Converter/README.md

@@ -9,6 +9,6 @@ models and the bus equations, typically through commanded active and reactive cu
 
 The GridKit converter documentation includes:
 
-- Renewable Energy Generator/Converter Model REGCA (See [REGCA](REGCA/README.md))
 - Renewable Energy Generator/Converter Model REGCB (See [REGCB](REGCB/README.md))
 - Renewable Energy Electrical Control Model REECA (See [REECA](REECA/README.md))
+- Renewable Energy Electrical Control Model REECB (See [REECB](REECB/README.md))

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

@@ -0,0 +1,54 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers Reecb.hpp ReecbData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(
+    phasor_dynamics_converter_reecb
+    SOURCES ReecbEnzyme.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_reecb
+    SOURCES Reecb.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_reecb_dependency_tracking
+  SOURCES ReecbDependencyTracking.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_reecb)
+target_link_libraries(
+  phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_converter_reecb_dependency_tracking)