REECB Documentation + Implementation

CHANGELOG.md

@@ -60,6 +60,7 @@
 - Added multi-contingency analysis application.
 - Added `BusToSignalAdapter` component for communicating bus voltages and injection currents.
 - Added `REGCA` converter model implementation for PhasorDynamics.
+- Added `REECB` converter model implementation for PhasorDynamics.
 
 ## v0.1
 

GridKit/CommonMath.hpp

@@ -15,7 +15,7 @@ namespace GridKit
      *
      * @note The sigmoid constant (mu) value is chosen to balance accuracy
      * and finite derivatives. Large values more closely approximate a step
-     * function, but lead to inf or NaN derivatives.
+     * function, but can make the transition numerically stiff.
      *
      * @tparam ScalarT - scalar data type
      *
@@ -27,7 +27,7 @@ namespace GridKit
     {
       using RealT               = typename GridKit::ScalarTraits<ScalarT>::RealT;
       static constexpr RealT MU = 240.0;
-      return ONE<RealT> / (ONE<RealT> + std::exp(-MU * x));
+      return HALF<RealT> * (ONE<RealT> + std::tanh(HALF<RealT> * MU * x));
     }
 
     /**
@@ -159,7 +159,8 @@ namespace GridKit
      * passes the input through unchanged outside the band.
      *
      * @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 - Input signal
      * @param[in] lower - Lower breakpoint
@@ -355,13 +356,15 @@ namespace GridKit
      * @return Scalar value in [0, 1]: 1 when dynamics should pass through,
      *         0 when integration should be blocked.
      */
-    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);
@@ -381,20 +384,21 @@ 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
      */
-    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/ComponentLibrary.hpp

@@ -4,6 +4,7 @@
 #include <GridKit/Model/PhasorDynamics/Bus/Bus.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/Converter/REGCA/Regca.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1.hpp>
 #include <GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/SexsPti.hpp>

GridKit/Model/PhasorDynamics/Converter/CMakeLists.txt

@@ -4,3 +4,4 @@
 # ]]
 
 add_subdirectory(REGCA)
+add_subdirectory(REECB)

GridKit/Model/PhasorDynamics/Converter/README.md

@@ -12,3 +12,4 @@ 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,49 @@
+# [[
+#  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)