ESDC1A Documentation + Implementation

CHANGELOG.md

@@ -52,6 +52,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

@@ -6,6 +6,7 @@
 #include <GridKit/Model/PhasorDynamics/BusFault/BusFault.hpp>
 #include <GridKit/Model/PhasorDynamics/BusToSignalAdapter/BusToSignalAdapter.hpp>
 #include <GridKit/Model/PhasorDynamics/Converter/REGCA/Regca.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,54 @@
+# [[
+#  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
+      PUBLIC
+      GridKit::phasor_dynamics_core
+      PUBLIC
+      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
+    PUBLIC
+    GridKit::phasor_dynamics_core
+    PUBLIC
+    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,30 @@
+/**
+ * @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
+    {
+      /**
+       * @brief Report that a separate Jacobian is unavailable in the plain build.
+       */
+      template <typename scalar_type, typename index_type>
+      int Esdc1a<scalar_type, index_type>::evaluateJacobian()
+      {
+        Log::misc() << "Evaluate Jacobian for Esdc1a..." << std::endl;
+        Log::misc() << "Jacobian evaluation is 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,186 @@
+/**
+ * @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 <typename scalar_type, typename index_type>
+    class BusBase;
+
+    template <typename scalar_type, typename index_type>
+    class SignalNode;
+
+    namespace Exciter
+    {
+      /// Internal variables of an `Esdc1a`.
+      enum class Esdc1aInternalVariables : size_t
+      {
+        EFDP,    ///< \f$E_{\mathrm{fd}}'\f$ Differential exciter field-voltage state [p.u.]
+        VC,      ///< \f$V_C\f$ Differential filtered terminal-voltage magnitude [p.u.]
+        VR,      ///< \f$V_R\f$ Differential voltage-regulator output [p.u.]
+        VF,      ///< \f$V_F\f$ Differential stabilizing feedback state [p.u.]
+        XLL,     ///< \f$x_{\mathrm{LL}}\f$ Differential input lead-lag denominator state [p.u.]
+        EV,      ///< \f$e_V\f$ Algebraic voltage-error summing output [p.u.]
+        VLL,     ///< \f$V_{\mathrm{LL}}\f$ Algebraic input lead-lag output [p.u.]
+        VHV,     ///< \f$V_{\mathrm{HV}}\f$ Algebraic high-value gate output [p.u.]
+        SE,      ///< \f$S_E\f$ Algebraic exciter saturation coefficient [p.u.]
+        VFE,     ///< \f$V_{\mathrm{FE}}\f$ Algebraic exciter feedback drive [p.u.]
+        EFD,     ///< \f$E_{\mathrm{fd}}\f$ Algebraic field-voltage output [p.u.]
+        MAXIMUM, ///< Number of ESDC1A internal variables
+      };
+
+      /// External signal variables read or initialized by an `Esdc1a`.
+      enum class Esdc1aExternalVariables : size_t
+      {
+        OMEGA,   ///< \f$\omega\f$ Known machine speed deviation [p.u.]
+        VREF,    ///< \f$V_{\mathrm{ref}}\f$ Unknown voltage-control reference [p.u.]
+        VS,      ///< \f$V_S\f$ Known stabilizer input signal [p.u.]
+        VUEL,    ///< \f$V_{\mathrm{UEL}}\f$ Known under-excitation limiter input [p.u.]
+        MAXIMUM, ///< Number of ESDC1A external signal variables
+      };
+
+      /**
+       * @brief IEEE DC1A excitation-system model (ESDC1A).
+       *
+       * @tparam scalar_type Plain real or differentiable scalar type.
+       * @tparam index_type Integer index type.
+       */
+      template <typename scalar_type, typename index_type>
+      class Esdc1a : public Component<scalar_type, index_type>
+      {
+        using Component<scalar_type, index_type>::abs_tol_;
+        using Component<scalar_type, index_type>::allocated_;
+        using Component<scalar_type, index_type>::alpha_;
+        using Component<scalar_type, index_type>::f_;
+        using Component<scalar_type, index_type>::gridkit_component_id_;
+        using Component<scalar_type, index_type>::J_cols_buffer_;
+        using Component<scalar_type, index_type>::J_rows_buffer_;
+        using Component<scalar_type, index_type>::J_vals_buffer_;
+        using Component<scalar_type, index_type>::nnz_;
+        using Component<scalar_type, index_type>::residual_indices_;
+        using Component<scalar_type, index_type>::size_;
+        using Component<scalar_type, index_type>::tag_;
+        using Component<scalar_type, index_type>::variable_indices_;
+        using Component<scalar_type, index_type>::wb_;
+        using Component<scalar_type, index_type>::y_;
+        using Component<scalar_type, index_type>::yp_;
+
+      public:
+        using ScalarT            = scalar_type;
+        using IdxT               = index_type;
+        using RealT              = typename Component<ScalarT, IdxT>::RealT;
+        using BusT               = BusBase<ScalarT, IdxT>;
+        using SignalT            = SignalNode<ScalarT, IdxT>;
+        using ModelDataT         = Esdc1aData<RealT, IdxT>;
+        using MonitorT           = Model::VariableMonitor<Esdc1a, Esdc1aData>;
+        using InternalVariablesT = Esdc1aInternalVariables;
+        using ExternalVariablesT = Esdc1aExternalVariables;
+
+        Esdc1a(BusT* bus);
+        Esdc1a(BusT* bus, const ModelDataT& data);
+        ~Esdc1a();
+
+        int setGridKitComponentID(IdxT component_id) override final;
+        int allocate() override final;
+        int verify() const override final;
+        int initialize() override final;
+        int tagDifferentiable() override final;
+        int setAbsoluteTolerance(RealT rel_tol) 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(
+            const ScalarT* y,
+            const ScalarT* yp,
+            const ScalarT* wb,
+            const ScalarT* ws,
+            ScalarT*       f);
+
+      private:
+        void initializeParameters(const ModelDataT& data);
+        void initializeMonitor();
+        void setDerivedParameters();
+
+        static __attribute__((always_inline)) inline ScalarT awmin(
+            ScalarT x,
+            ScalarT f,
+            RealT   xmin);
+
+        /// Recover the input that the smooth CommonMath ramp maps to a
+        /// requested strictly positive output.
+        RealT inverseRamp(RealT ramp_output) const;
+
+        ScalarT& Vr();
+        ScalarT& Vi();
+
+        static constexpr RealT TIME_CONSTANT_MINIMUM = static_cast<RealT>(1.0e-3);
+
+        BusT* bus_{nullptr};
+
+        RealT Tr_{ZERO<RealT>};
+        RealT Ka_{static_cast<RealT>(40.0)};
+        RealT Ta_{static_cast<RealT>(0.1)};
+        RealT Tb_{ZERO<RealT>};
+        RealT Tc_{ZERO<RealT>};
+        RealT Vrmax_{ONE<RealT>};
+        RealT Vrmin_{static_cast<RealT>(-1.0)};
+        RealT Ke_{static_cast<RealT>(0.1)};
+        RealT Te_{static_cast<RealT>(0.5)};
+        RealT Kf_{static_cast<RealT>(0.05)};
+        RealT Tf1_{static_cast<RealT>(0.7)};
+        bool  Spdmlt_{false};
+        RealT E1_{static_cast<RealT>(2.8)};
+        RealT Se1_{static_cast<RealT>(0.08)};
+        RealT E2_{static_cast<RealT>(3.7)};
+        RealT Se2_{static_cast<RealT>(0.33)};
+        IdxT  UEL_{0};
+        bool  exclim_{true};
+        RealT spd_on_{0};
+        RealT uel_on_{0};
+        RealT lim_on_{1};
+        RealT SA_{0};
+        RealT SB_{0};
+
+        IdxT parameter_error_count_{0};
+
+        ScalarT omega_set_{0};
+        ScalarT vref_set_{0};
+        ScalarT vs_set_{0};
+        ScalarT vuel_set_{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