ESDC1A Documentation + Implementation

CHANGELOG.md

@@ -51,6 +51,7 @@
 - Added component model developer checklist to a README file.
 - Added `IEEEST` Stabilizer Model
 - Added `SEXS-PTI` Exciter Model
+- Added `ESDC1A` Exciter Model
 - Added `GENSAL` Machine Model
 - Added 200 Bus Synthetic Illinois Case
 - Added node objects to `PowerElectronics` module & updated all examples to make use of them.

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/Exciter/ESDC1A/Esdc1a.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/Exciter/CMakeLists.txt

@@ -3,5 +3,6 @@
 #    - Luke Lowery <lukel@tamu.edu>
 # ]]
 
+add_subdirectory(ESDC1A)
 add_subdirectory(IEEET1)
 add_subdirectory(SEXS-PTI)

GridKit/Model/PhasorDynamics/Exciter/ESDC1A/CMakeLists.txt

@@ -0,0 +1,46 @@
+# [[
+#  Author(s):
+#    - Luke Lowery <lukel@tamu.edu>
+# ]]
+
+set(_install_headers Esdc1a.hpp Esdc1aData.hpp)
+
+if(GRIDKIT_ENABLE_ENZYME)
+  gridkit_add_library(
+    phasor_dynamics_exciter_esdc1a
+    SOURCES Esdc1aEnzyme.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_exciter_esdc1a
+    SOURCES Esdc1a.cpp
+    HEADERS ${_install_headers}
+    INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
+    LINK_LIBRARIES GridKit::phasor_dynamics_core GridKit::phasor_dynamics_signal)
+endif()
+
+gridkit_add_library(
+  phasor_dynamics_exciter_esdc1a_dependency_tracking
+  SOURCES Esdc1aDependencyTracking.cpp
+  INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
+  LINK_LIBRARIES GridKit::phasor_dynamics_core GridKit::phasor_dynamics_signal_dependency_tracking)
+
+target_link_libraries(
+  phasor_dynamics_components
+  INTERFACE GridKit::phasor_dynamics_exciter_esdc1a)
+target_link_libraries(
+  phasor_dynamics_components_dependency_tracking
+  INTERFACE GridKit::phasor_dynamics_exciter_esdc1a_dependency_tracking)

GridKit/Model/PhasorDynamics/Exciter/ESDC1A/Esdc1a.cpp

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

GridKit/Model/PhasorDynamics/Exciter/ESDC1A/Esdc1a.hpp

@@ -0,0 +1,152 @@
+/**
+ * @file Esdc1a.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Declaration of the ESDC1A exciter 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/Exciter/ESDC1A/Esdc1aData.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 Exciter
+    {
+      /// Internal variables of an `Esdc1a`.
+      enum class Esdc1aInternalVariables : size_t
+      {
+        EFDP, ///< Field-voltage state before optional speed multiplier
+        VC,   ///< Sensed compensated voltage
+        VR,   ///< Voltage-regulator output
+        VF,   ///< Stabilizing feedback output
+        XLL,  ///< Lead-lag state
+        EV,   ///< Voltage-regulator input error
+        VLL,  ///< Lead-lag block output
+        VHV,  ///< High-value gate output
+        SE,   ///< Saturation coefficient
+        VFE,  ///< Exciter feedback signal
+        EFD,  ///< Field-voltage output
+        MAXIMUM,
+      };
+
+      /// External variables of an `Esdc1a`.
+      enum class Esdc1aExternalVariables : size_t
+      {
+        OMEGA, ///< Machine speed deviation
+        VS,    ///< Stabilizer input signal
+        VUEL,  ///< Under-excitation limiter input
+        MAXIMUM,
+      };
+
+      template <class ScalarT, typename IdxT>
+      class Esdc1a : public Component<ScalarT, IdxT>
+      {
+        using Component<ScalarT, IdxT>::alpha_;
+        using Component<ScalarT, IdxT>::f_;
+        using Component<ScalarT, IdxT>::gridkit_component_id_;
+        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>::residual_indices_;
+        using Component<ScalarT, IdxT>::size_;
+        using Component<ScalarT, IdxT>::tag_;
+        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 = Esdc1aData<RealT, IdxT>;
+        using MonitorT        = Model::VariableMonitor<Esdc1a, Esdc1aData>;
+
+        Esdc1a(bus_type* bus);
+        Esdc1a(bus_type* bus, const model_data_type& data);
+        ~Esdc1a();
+
+        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,
+                                Esdc1aInternalVariables,
+                                Esdc1aExternalVariables>&
+        {
+          return signals_;
+        }
+
+        const Model::VariableMonitorBase* getMonitor() const override;
+
+        __attribute__((always_inline)) inline int evaluateInternalResidual(
+            ScalarT*, ScalarT*, ScalarT*, ScalarT*, ScalarT*);
+
+      private:
+        void initModelParams(const model_data_type& data);
+        void setDerivedParams();
+        void initializeMonitor();
+
+        bus_type* bus_{nullptr};
+
+        RealT Tr_{0.0};
+        RealT Ka_{40.0};
+        RealT Ta_{0.1};
+        RealT Tb_{0.0};
+        RealT Tc_{0.0};
+        RealT Vrmax_{1.0};
+        RealT Vrmin_{-1.0};
+        RealT Ke_{0.1};
+        RealT Te_{0.5};
+        RealT Kf_{0.05};
+        RealT Tf1_{0.7};
+        RealT spdmlt_{0.0};
+        RealT E1_{2.8};
+        RealT Se1_{0.08};
+        RealT E2_{3.7};
+        RealT Se2_{0.33};
+        IdxT  UEL_{0};
+        RealT exclim_{1.0};
+
+        RealT sUEL_{0};
+        RealT sUELoff_{1};
+        RealT slim_{0};
+        RealT slim_off_{1};
+        RealT use_lead_lag_{0};
+        RealT bypass_lead_lag_{1};
+        RealT SA_{0};
+        RealT SB_{0};
+
+        ScalarT vref_{0};
+
+        ComponentSignals<ScalarT, IdxT, Esdc1aInternalVariables, Esdc1aExternalVariables> signals_;
+        std::unique_ptr<MonitorT>                                                         monitor_;
+
+        std::vector<ScalarT> ws_;
+        std::vector<IdxT>    ws_indices_;
+      };
+    } // namespace Exciter
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Exciter/ESDC1A/Esdc1aData.hpp

@@ -0,0 +1,76 @@
+/**
+ * @file Esdc1aData.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Modeling data for the ESDC1A exciter model.
+ */
+
+#pragma once
+
+#include <GridKit/Model/PhasorDynamics/ComponentData.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Exciter
+    {
+      /// Parameter keys for the ESDC1A exciter model.
+      enum class Esdc1aParameters
+      {
+        Tr,     ///< Transducer time constant
+        Ka,     ///< Voltage-regulator gain
+        Ta,     ///< Voltage-regulator time constant
+        Tb,     ///< Lead-lag denominator time constant
+        Tc,     ///< Lead-lag numerator time constant
+        Vrmax,  ///< Maximum voltage-regulator output
+        Vrmin,  ///< Minimum voltage-regulator output
+        Ke,     ///< Exciter field-resistance line-slope margin
+        Te,     ///< Exciter field time constant
+        Kf,     ///< Stabilizing feedback gain
+        Tf1,    ///< Feedback lead time constant
+        Spdmlt, ///< Speed multiplier flag
+        E1,     ///< First saturation voltage point
+        Se1,    ///< Saturation value at E1
+        E2,     ///< Second saturation voltage point
+        Se2,    ///< Saturation value at E2
+        UEL,    ///< UEL input-location selector
+        exclim  ///< Exciter feedback lower-limit flag
+      };
+
+      /// Ports for the ESDC1A exciter model.
+      enum class Esdc1aPorts
+      {
+        bus,   ///< Unique ID of the terminal bus
+        speed, ///< Unique ID of the generator speed-deviation signal
+        efd,   ///< Unique ID of the output EFD signal
+        vs,    ///< Unique ID of the optional stabilizer input signal
+        vuel   ///< Unique ID of the optional UEL input signal
+      };
+
+      /// Variables available through the monitor interface.
+      enum class Esdc1aMonitorableVariables
+      {
+        efd, ///< Field-voltage output
+        vc,  ///< Sensed compensated voltage
+        vr,  ///< Voltage-regulator output
+        vf,  ///< Stabilizing feedback state
+        se,  ///< Saturation coefficient
+        vfe  ///< Exciter feedback signal
+      };
+
+      template <typename RealT, typename IdxT>
+      struct Esdc1aData : public ComponentData<RealT,
+                                               IdxT,
+                                               Esdc1aParameters,
+                                               Esdc1aPorts,
+                                               Esdc1aMonitorableVariables>
+      {
+        Esdc1aData() = default;
+
+        using Parameters           = Esdc1aParameters;
+        using Ports                = Esdc1aPorts;
+        using MonitorableVariables = Esdc1aMonitorableVariables;
+      };
+    } // namespace Exciter
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Exciter/ESDC1A/Esdc1aDependencyTracking.cpp

@@ -0,0 +1,27 @@
+/**
+ * @file Esdc1aDependencyTracking.cpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Dependency-tracking instantiations for the ESDC1A exciter model.
+ */
+
+#include "Esdc1aImpl.hpp"
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    namespace Exciter
+    {
+      template <class ScalarT, typename IdxT>
+      int Esdc1a<ScalarT, IdxT>::evaluateJacobian()
+      {
+        Log::misc() << "Evaluate Jacobian for Esdc1a..." << std::endl;
+        Log::misc() << "Jacobian evaluation not implemented!" << std::endl;
+        return 0;
+      }
+
+      template class Esdc1a<DependencyTracking::Variable, long int>;
+      template class Esdc1a<DependencyTracking::Variable, size_t>;
+    } // namespace Exciter
+  } // namespace PhasorDynamics
+} // namespace GridKit