EMT 1

Author: lukelowry

CHANGELOG.md

@@ -28,6 +28,7 @@
 - Added a `TwoArea` integration test comparing flat and hierarchical PhasorDynamics systems.
 - Added rate feedback (`Kf`, `Tf`) to the IEEET1 exciters in the `TwoArea` case, whose generators lost synchronism without a fault.
 - Added the `state_file` solver option, which sets PhasorDynamics initial bus voltages from a state file.
+- Added the EMT model family with `Bus`, `LoadZ` and the `VectorFit` operator, and `Testing::jacobianMatchesResidual`.
 
 ## v0.2
 

GridKit/Constants.hpp

@@ -31,4 +31,8 @@ namespace GridKit
 
   template <typename RealT>
   inline constexpr RealT MINUS_ONE = -1.0;
+
+  /// SI prefix kilo
+  template <typename RealT>
+  inline constexpr RealT KILO = 1.0e3;
 } // namespace GridKit

GridKit/Model/CMakeLists.txt

@@ -5,6 +5,7 @@
 #    - Cameron Rutherford <cameron.rutherford@pnnl.gov>
 #]]
 
+add_subdirectory(EMT)
 add_subdirectory(PhasorDynamics)
 add_subdirectory(PowerFlow)
 add_subdirectory(PowerElectronics)

GridKit/Model/EMT/Bus/Bus.cpp

@@ -0,0 +1,16 @@
+/**
+ * @file Bus.cpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief EMT bus instantiation.
+ */
+
+#include "BusImpl.hpp"
+
+namespace GridKit
+{
+  namespace EMT
+  {
+    // Available template instantiations
+    template class Bus<double, size_t>;
+  } // namespace EMT
+} // namespace GridKit

GridKit/Model/EMT/Bus/Bus.hpp

@@ -0,0 +1,50 @@
+/**
+ * @file Bus.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Declaration of an EMT bus.
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <string_view>
+
+#include <GridKit/Model/EMT/Bus/BusData.hpp>
+#include <GridKit/Model/EMT/Component.hpp>
+
+namespace GridKit
+{
+  namespace EMT
+  {
+    /// Internal variables of a `Bus`, each of size N
+    enum class BusInternalVariables : size_t
+    {
+      v, ///< \f$\mathbf{v}\f$ Bus voltage [V]
+    };
+
+    /// N-phase bus, whose residuals collect the injected currents
+    template <typename scalar_type, typename index_type>
+    class Bus final : public Component<scalar_type, index_type>
+    {
+      using ComponentT = Component<scalar_type, index_type>;
+      using IdxT       = index_type;
+      using RealT      = typename ComponentT::RealT;
+
+    public:
+      using ModelDataT         = BusData<RealT, IdxT>;
+      using InternalVariablesT = BusInternalVariables;
+      using PortsT             = Utilities::EmptyEnum;
+
+      static constexpr std::string_view CLASS_NAME = "Bus";
+
+      explicit Bus(const ModelDataT& data);
+
+      Model::ConfigurationChecks verify() const override;
+      int                        setAbsoluteTolerance(RealT rel_tol) override;
+
+    private:
+      IdxT  N_{0};
+      RealT kv_{ZERO<RealT>};
+    };
+  } // namespace EMT
+} // namespace GridKit

GridKit/Model/EMT/Bus/BusData.hpp

@@ -0,0 +1,37 @@
+/**
+ * @file BusData.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Modeling data for EMT buses.
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <tuple>
+
+#include <GridKit/Model/EMT/ComponentData.hpp>
+
+namespace GridKit
+{
+  namespace EMT
+  {
+    /// Parameters of a `Bus`
+    enum class BusParameters : size_t
+    {
+      N,  ///< \f$N\f$ Number of phases
+      kv, ///< \f$V^\mathrm{base}\f$ Base voltage [kV]
+    };
+
+    /// Data of a `Bus`
+    template <typename RealT, typename IdxT>
+    struct BusData
+    {
+      using Parameters = BusParameters;
+
+      IdxT  N{0};
+      RealT kv{ZERO<RealT>};
+
+      static constexpr std::tuple PARAMETERS{Parameter{Parameters::N, &BusData::N}, Parameter{Parameters::kv, &BusData::kv}};
+    };
+  } // namespace EMT
+} // namespace GridKit

GridKit/Model/EMT/Bus/BusImpl.hpp

@@ -0,0 +1,43 @@
+/**
+ * @file BusImpl.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Definition of an EMT bus.
+ */
+
+#pragma once
+
+#include <algorithm>
+
+#include <GridKit/Model/EMT/Bus/Bus.hpp>
+#include <GridKit/Model/EMT/ComponentImpl.hpp>
+
+namespace GridKit
+{
+  namespace EMT
+  {
+    template <typename scalar_type, typename index_type>
+    Bus<scalar_type, index_type>::Bus(const ModelDataT& data)
+      : N_(data.N),
+        kv_(data.kv)
+    {
+      this->setLayout({N_}, {});
+    }
+
+    template <typename scalar_type, typename index_type>
+    Model::ConfigurationChecks Bus<scalar_type, index_type>::verify() const
+    {
+      Model::ConfigurationChecks checks("Bus");
+      checks.check(N_ > 0, "N must be positive");
+      checks.check(kv_ > ZERO<RealT>, "kv must be positive");
+      return checks;
+    }
+
+    /// Voltages at the bus base voltage
+    template <typename scalar_type, typename index_type>
+    int Bus<scalar_type, index_type>::setAbsoluteTolerance(RealT rel_tol)
+    {
+      std::ranges::fill(this->absoluteTolerance(BusInternalVariables::v), rel_tol * KILO<RealT> * kv_);
+      return 0;
+    }
+  } // namespace EMT
+} // namespace GridKit

GridKit/Model/EMT/Bus/CMakeLists.txt

@@ -0,0 +1,9 @@
+gridkit_add_library(
+  emt_bus
+  SOURCES Bus.cpp
+  HEADERS Bus.hpp BusData.hpp
+  LINK_LIBRARIES PUBLIC GridKit::emt_core)
+
+target_link_libraries(
+  emt_components
+  INTERFACE GridKit::emt_bus)

GridKit/Model/EMT/Bus/README.md

@@ -17,11 +17,15 @@ Figure 1: Bus model
 Symbol | Units | JSON | Description | Note
 ------ | ----- | ---- | ----------- | ----
 $N$ | [-] | `N` | Number of phases | Required, positive integer
+$V^\mathrm{base}$ | [kV] | `kv` | Base voltage | Required, positive
 
 ### Parameter Validation
 
 ```math
-N \in \mathbb{Z}_{>0}
+\begin{aligned}
+N &\in \mathbb{Z}_{>0} \\
+V^\mathrm{base} &\in \mathbb{R}_{>0}
+\end{aligned}
 ```
 
 ### Model Derived Parameters
@@ -30,10 +34,7 @@ None.
 
 ## Model Ports
 
-Symbol | Port | Type | Units | Description | Note
------- | ---- | ---- | ----- | ----------- | ----
-$\mathbf{i}_d$ | `i` | Input | [A] | Current from connected device $d$ | One port per $d \in \mathcal{D}$, $\mathbf{i}_d \in \mathbb{R}^N$
-$\mathbf{v}$ | `v` | Output | [V] | Bus voltage supplied to connected devices | $\mathbf{v} \in \mathbb{R}^N$
+None.
 
 ## Submodels
 

GridKit/Model/EMT/CMakeLists.txt

@@ -0,0 +1,46 @@
+if(GRIDKIT_ENABLE_ENZYME)
+  add_library(emt_components INTERFACE)
+
+  gridkit_add_library(
+    emt_core
+    INTERFACE_TARGET
+    HEADERS Component.hpp ComponentData.hpp
+    LINK_LIBRARIES
+      INTERFACE
+      GridKit::definitions
+      INTERFACE
+      GridKit::Utilities
+      INTERFACE
+      GridKit::dense_vector
+      INTERFACE
+      GridKit::sparse_matrix
+      INTERFACE
+      GridKit::utilities_logger)
+
+  target_link_libraries(emt_components INTERFACE GridKit::emt_core)
+
+  add_subdirectory(Bus)
+  add_subdirectory(Component)
+  add_subdirectory(Operators)
+
+  add_library(GridKit::emt_components ALIAS emt_components)
+
+  gridkit_add_library(
+    emt_systemmodel
+    SOURCES SystemModel.cpp SystemModelData.cpp
+    HEADERS SystemModel.hpp
+            SystemModelData.hpp
+            ComponentLibrary.hpp
+            Monitor.hpp
+            StateJSONParser.hpp
+    LINK_LIBRARIES
+      PUBLIC
+      GridKit::emt_components
+      PUBLIC
+      GridKit::dense_vector
+      PUBLIC
+      GridKit::sparse_matrix
+    INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/nlohmann-json/include)
+
+  install(TARGETS emt_components EXPORT gridkit-targets)
+endif()