BranchBase Class for Other Branch Types

CHANGELOG.md

@@ -51,6 +51,8 @@
 - Added LoadZIP model component type.
 - Added component model developer checklist to a README file.
 - Added IEEEST Stabilizer Model
+- Added `BranchBase` abstract class and `BranchFactory` to support additional branch types (only LINE phasor $`\pi`$-model currently implemented).
+- Generalized Bus terminal voltage and current accessors.
 
 ## v0.1
 

GridKit/Model/PhasorDynamics/Branch/Branch.hpp

@@ -9,6 +9,7 @@
 #pragma once
 
 #include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
+#include <GridKit/Model/PhasorDynamics/BranchBase.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
 #include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
 #include <GridKit/Model/VariableMonitor.hpp>
@@ -38,7 +39,7 @@ namespace GridKit
      *
      */
     template <class ScalarT, typename IdxT>
-    class Branch : public Component<ScalarT, IdxT>
+    class Branch : public BranchBase<ScalarT, IdxT>
     {
       using Component<ScalarT, IdxT>::gridkit_component_id_;
       using Component<ScalarT, IdxT>::size_;
@@ -57,6 +58,8 @@ namespace GridKit
       using Component<ScalarT, IdxT>::J_vals_buffer_;
       using Component<ScalarT, IdxT>::variable_indices_;
       using Component<ScalarT, IdxT>::residual_indices_;
+      using BranchBase<ScalarT, IdxT>::ports_;
+      using BranchBase<ScalarT, IdxT>::branch_id_;
 
     public:
       using RealT           = typename Component<ScalarT, IdxT>::RealT;
@@ -75,6 +78,8 @@ namespace GridKit
       virtual int tagDifferentiable() override final;
       virtual int evaluateResidual() override final;
       virtual int evaluateJacobian() override final;
+      virtual int setBranchID(IdxT) override final;
+      virtual int verifyPorts() const override final;
 
       virtual int verify() const override final
       {
@@ -115,42 +120,42 @@ namespace GridKit
 
       ScalarT& Vr1()
       {
-        return bus1_->Vr();
+        return this->port(0)->v(0);
       }
 
       ScalarT& Vi1()
       {
-        return bus1_->Vi();
+        return this->port(0)->v(1);
       }
 
       ScalarT& Ir1()
       {
-        return bus1_->Ir();
+        return this->port(0)->i(0);
       }
 
       ScalarT& Ii1()
       {
-        return bus1_->Ii();
+        return this->port(0)->i(1);
       }
 
       ScalarT& Vr2()
       {
-        return bus2_->Vr();
+        return this->port(1)->v(0);
       }
 
       ScalarT& Vi2()
       {
-        return bus2_->Vi();
+        return this->port(1)->v(1);
       }
 
       ScalarT& Ir2()
       {
-        return bus2_->Ir();
+        return this->port(1)->i(0);
       }
 
       ScalarT& Ii2()
       {
-        return bus2_->Ii();
+        return this->port(1)->i(1);
       }
 
     public:
@@ -160,14 +165,10 @@ namespace GridKit
       __attribute__((always_inline)) inline int evaluateBusResidual22(ScalarT*, ScalarT*, ScalarT*, ScalarT*);
 
     private:
-      bus_type* bus1_;
-      bus_type* bus2_;
-      RealT     R_{0.0};
-      RealT     X_{0.0};
-      RealT     G_{0.0};
-      RealT     B_{0.0};
-      IdxT      bus1_id_{0};
-      IdxT      bus2_id_{0};
+      RealT R_{0.0};
+      RealT X_{0.0};
+      RealT G_{0.0};
+      RealT B_{0.0};
 
       /* Derived parameters */
       RealT b_;

GridKit/Model/PhasorDynamics/Branch/BranchData.hpp

@@ -63,6 +63,17 @@ namespace GridKit
       using Parameters           = BranchParameters;
       using Ports                = BranchPorts;
       using MonitorableVariables = BranchMonitorableVariables;
+
+      /// @brief Concrete branch kind this data configures.
+      enum class BranchType
+      {
+        INVALID,
+        LINE,        ///< Phasor pi-model (Branch)
+        LUMPED_EMT,  ///< reserved, not yet implemented
+        TRANSFORMER, ///< reserved, not yet implemented
+      };
+
+      BranchType branch_type{BranchType::LINE};
     };
   } // namespace PhasorDynamics
 } // namespace GridKit

GridKit/Model/PhasorDynamics/Branch/BranchDataJSONParser.hpp

@@ -0,0 +1,50 @@
+/**
+ * @file BranchDataJSONParser.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief JSON parser for BranchData.
+ */
+
+#pragma once
+
+#include <string>
+
+#include <nlohmann/json.hpp>
+
+#include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
+#include <GridKit/Model/PhasorDynamics/ComponentDataJSONParser.hpp>
+#include <GridKit/Utilities/Logger/Logger.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    using json = nlohmann::json;
+    using Log  = ::GridKit::Utilities::Logger;
+
+    /// JSON parser for `BranchData`: fills the generic `ComponentData`
+    /// fields, then maps the JSON `class` string to `BranchType`.
+    template <typename RealT, typename IdxT>
+    void from_json(const json& j, BranchData<RealT, IdxT>& bd)
+    {
+      // Qualified call with explicit template args: prevents rebinding
+      // to this overload instead of the generic ComponentData from_json.
+      using BaseT = ComponentData<RealT, IdxT, BranchParameters, BranchPorts, BranchMonitorableVariables>;
+      ::GridKit::PhasorDynamics::from_json<RealT, IdxT, BranchParameters, BranchPorts, BranchMonitorableVariables>(
+          j, static_cast<BaseT&>(bd));
+
+      auto string_class = j.at("class").get<std::string>();
+      if (string_class == "Branch")
+      {
+        bd.branch_type = BranchData<RealT, IdxT>::BranchType::LINE;
+      }
+      else
+      {
+        Log::error() << "\n\tInvalid branch class: \"" << string_class
+                     << "\".\n\tSee the device with \"id\": \""
+                     << bd.disambiguation_string
+                     << "\" in the \"devices\" list of your JSON file."
+                     << std::endl;
+      }
+    }
+  } // namespace PhasorDynamics
+} // namespace GridKit

GridKit/Model/PhasorDynamics/Branch/BranchEnzyme.cpp

@@ -38,47 +38,47 @@ namespace GridKit
                                      GridKit::Enzyme::Sparse::MemberFunctions::BusResidual11,
                                      ScalarT,
                                      IdxT>::eval(this,
-                                                 static_cast<size_t>(bus1_->size()),
-                                                 static_cast<size_t>((bus1_->y()).size()),
-                                                 (bus1_->getResidualIndices()).data(),
-                                                 (bus1_->getVariableIndices()).data(),
+                                                 static_cast<size_t>(this->port(0)->size()),
+                                                 static_cast<size_t>((this->port(0)->y()).size()),
+                                                 (this->port(0)->getResidualIndices()).data(),
+                                                 (this->port(0)->getVariableIndices()).data(),
                                                  y_.data(),
                                                  yp_.data(),
-                                                 (bus1_->y()).data(),
+                                                 (this->port(0)->y()).data(),
                                                  J_rows_buffer_,
                                                  J_cols_buffer_,
                                                  J_vals_buffer_,
-                                                 bus1_->getJacobian());
+                                                 this->port(0)->getJacobian());
 
       // Bus 2 diagonal Jacobian block owned by the bus
       GridKit::Enzyme::Sparse::DhDwb<GridKit::PhasorDynamics::Branch<ScalarT, IdxT>,
                                      GridKit::Enzyme::Sparse::MemberFunctions::BusResidual22,
                                      ScalarT,
                                      IdxT>::eval(this,
-                                                 static_cast<size_t>(bus2_->size()),
-                                                 static_cast<size_t>((bus2_->y()).size()),
-                                                 (bus2_->getResidualIndices()).data(),
-                                                 (bus2_->getVariableIndices()).data(),
+                                                 static_cast<size_t>(this->port(1)->size()),
+                                                 static_cast<size_t>((this->port(1)->y()).size()),
+                                                 (this->port(1)->getResidualIndices()).data(),
+                                                 (this->port(1)->getVariableIndices()).data(),
                                                  y_.data(),
                                                  yp_.data(),
-                                                 (bus2_->y()).data(),
+                                                 (this->port(1)->y()).data(),
                                                  J_rows_buffer_,
                                                  J_cols_buffer_,
                                                  J_vals_buffer_,
-                                                 bus2_->getJacobian());
+                                                 this->port(1)->getJacobian());
 
       // Off-diagonal Jacobian block (Bus2 variables) owned by the branch
       GridKit::Enzyme::Sparse::DhDwb<GridKit::PhasorDynamics::Branch<ScalarT, IdxT>,
                                      GridKit::Enzyme::Sparse::MemberFunctions::BusResidual12,
                                      ScalarT,
                                      IdxT>::eval(this,
-                                                 static_cast<size_t>(bus1_->size()),
-                                                 static_cast<size_t>((bus2_->y()).size()),
-                                                 (bus1_->getResidualIndices()).data(),
-                                                 (bus2_->getVariableIndices()).data(),
+                                                 static_cast<size_t>(this->port(0)->size()),
+                                                 static_cast<size_t>((this->port(1)->y()).size()),
+                                                 (this->port(0)->getResidualIndices()).data(),
+                                                 (this->port(1)->getVariableIndices()).data(),
                                                  y_.data(),
                                                  yp_.data(),
-                                                 (bus2_->y()).data(),
+                                                 (this->port(1)->y()).data(),
                                                  J_rows_buffer_,
                                                  J_cols_buffer_,
                                                  J_vals_buffer_,
@@ -90,13 +90,13 @@ namespace GridKit
                                      GridKit::Enzyme::Sparse::MemberFunctions::BusResidual21,
                                      ScalarT,
                                      IdxT>::eval(this,
-                                                 static_cast<size_t>(bus2_->size()),
-                                                 static_cast<size_t>((bus1_->y()).size()),
-                                                 (bus2_->getResidualIndices()).data(),
-                                                 (bus1_->getVariableIndices()).data(),
+                                                 static_cast<size_t>(this->port(1)->size()),
+                                                 static_cast<size_t>((this->port(0)->y()).size()),
+                                                 (this->port(1)->getResidualIndices()).data(),
+                                                 (this->port(0)->getVariableIndices()).data(),
                                                  y_.data(),
                                                  yp_.data(),
-                                                 (bus1_->y()).data(),
+                                                 (this->port(0)->y()).data(),
                                                  J_rows_buffer_,
                                                  J_cols_buffer_,
                                                  J_vals_buffer_,

GridKit/Model/PhasorDynamics/Branch/BranchFactory.hpp

@@ -0,0 +1,71 @@
+/**
+ * @file BranchFactory.hpp
+ * @author Luke Lowery (lukel@tamu.edu)
+ * @brief Factory that constructs concrete BranchBase subclasses from BranchData.
+ */
+
+#pragma once
+
+#include <stdexcept>
+#include <string>
+
+#include <GridKit/Model/PhasorDynamics/Branch/Branch.hpp>
+#include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
+#include <GridKit/Model/PhasorDynamics/BranchBase.hpp>
+#include <GridKit/Utilities/Logger/Logger.hpp>
+
+namespace GridKit
+{
+  namespace PhasorDynamics
+  {
+    /**
+     * @brief Constructs a concrete `BranchBase` from `BranchData`, dispatching
+     * on `BranchData::BranchType`.
+     *
+     * Structural bus/branch compatibility is not checked here; the concrete
+     * branch's `verifyPorts()` (run from `allocate()`) is responsible.
+     *
+     * Throws `std::runtime_error` if `branch_type` is unrecognized so
+     * misconfiguration fails at construction rather than as a `nullptr`
+     * dereference later.
+     */
+    template <typename ScalarT = double, typename IdxT = int>
+    class BranchFactory
+    {
+    public:
+      using RealT       = typename Model::Evaluator<ScalarT, IdxT>::RealT;
+      using BranchData  = GridKit::PhasorDynamics::BranchData<RealT, IdxT>;
+      using BranchTypeT = typename GridKit::PhasorDynamics::BranchData<RealT, IdxT>::BranchType;
+      using bus_type    = BusBase<ScalarT, IdxT>;
+      using Log         = ::GridKit::Utilities::Logger;
+
+      BranchFactory() = delete;
+
+      /**
+       * @brief Construct a concrete branch selected by `data.branch_type`.
+       *
+       * @param data branch data; `branch_type` selects the concrete type.
+       * @param bus1 bus attached to port 0.
+       * @param bus2 bus attached to port 1.
+       * @return owning pointer to a newly-allocated concrete branch.
+       * @throws std::runtime_error if `branch_type` is unrecognized.
+       */
+      static BranchBase<ScalarT, IdxT>* create(const BranchData& data,
+                                               bus_type*         bus1,
+                                               bus_type*         bus2)
+      {
+        switch (data.branch_type)
+        {
+        case BranchTypeT::LINE:
+          return new Branch<ScalarT, IdxT>(bus1, bus2, data);
+        default:
+          Log::error() << "BranchFactory: unrecognized branch_type "
+                       << static_cast<int>(data.branch_type) << std::endl;
+          throw std::runtime_error(
+              "BranchFactory::create: unrecognized branch_type "
+              + std::to_string(static_cast<int>(data.branch_type)));
+        }
+      }
+    };
+  } // namespace PhasorDynamics
+} // namespace GridKit