Off-nominal branch tap and phase support

CHANGELOG.md

@@ -59,6 +59,7 @@
 - Remove data copying between system and components in `PowerElectronics` models.
 - Added multi-contingency analysis application.
 - Added `BusToSignalAdapter` component for communicating bus voltages and injection currents.
+- Added off-nominal tap ratio and phase shift support to the PhasorDynamics `Branch` model.
 
 ## v0.1
 

GridKit/Model/PhasorDynamics/Branch/Branch.hpp

@@ -8,6 +8,8 @@
  */
 #pragma once
 
+#include <complex>
+
 #include <GridKit/Model/PhasorDynamics/Branch/BranchData.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
 #include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
@@ -31,7 +33,7 @@ namespace GridKit
   namespace PhasorDynamics
   {
     /**
-     * @brief Implementation of a pi-model branch between two buses.
+     * @brief Implementation of a line or off-nominal transformer branch between two buses.
      *
      * The model is implemented in Cartesian coordinates. Positive current
      * direction is into the busses.
@@ -65,7 +67,14 @@ namespace GridKit
       using MonitorT        = Model::VariableMonitor<Branch, BranchData>;
 
       Branch(bus_type* bus1, bus_type* bus2);
-      Branch(bus_type* bus1, bus_type* bus2, RealT R, RealT X, RealT G, RealT B);
+      Branch(bus_type* bus1,
+             bus_type* bus2,
+             RealT     R,
+             RealT     X,
+             RealT     G,
+             RealT     B,
+             RealT     tap   = 1.0,
+             RealT     phase = 0.0);
       Branch(bus_type* bus1, bus_type* bus2, const model_data_type& data);
       virtual ~Branch();
 
@@ -75,11 +84,7 @@ namespace GridKit
       virtual int tagDifferentiable() override final;
       virtual int evaluateResidual() override final;
       virtual int evaluateJacobian() override final;
-
-      virtual int verify() const override final
-      {
-        return 0;
-      }
+      virtual int verify() const override final;
 
       void setR(RealT R)
       {
@@ -89,7 +94,6 @@ namespace GridKit
 
       void setX(RealT X)
       {
-        // std::cout << "Setting X ...\n";
         X_ = X;
         setDerivedParams();
       }
@@ -106,12 +110,44 @@ namespace GridKit
         setDerivedParams();
       }
 
+      void setTap(RealT tap)
+      {
+        tap_ = tap;
+        setDerivedParams();
+      }
+
+      void setPhase(RealT phase)
+      {
+        phase_ = phase;
+        setDerivedParams();
+      }
+
       const Model::VariableMonitorBase* getMonitor() const override;
 
     private:
-      void initializeParameters(const model_data_type& data);
-      void initializeMonitor();
-      void setDerivedParams();
+      struct AdmittanceBlock
+      {
+        RealT G{0.0};
+        RealT B{0.0};
+      };
+
+      void                                              initializeParameters(const model_data_type& data);
+      void                                              initializeMonitor();
+      void                                              setDerivedParams();
+      void                                              terminalCurrent1(ScalarT& Ir, ScalarT& Ii);
+      void                                              terminalCurrent2(ScalarT& Ir, ScalarT& Ii);
+      bool                                              readRealParameter(const model_data_type&               data,
+                                                                          typename model_data_type::Parameters parameter,
+                                                                          RealT&                               target);
+      static void                                       setAdmittanceBlock(AdmittanceBlock& block, const std::complex<RealT>& y);
+      static __attribute__((always_inline)) inline void addAdmittanceContribution(const AdmittanceBlock& y,
+                                                                                  const ScalarT&         Vr,
+                                                                                  const ScalarT&         Vi,
+                                                                                  ScalarT&               Ir,
+                                                                                  ScalarT&               Ii);
+      static __attribute__((always_inline)) inline void evaluateAdmittanceBlock(const AdmittanceBlock& y,
+                                                                                const ScalarT*         wb,
+                                                                                ScalarT*               h);
 
       ScalarT& Vr1()
       {
@@ -166,12 +202,17 @@ namespace GridKit
       RealT     X_{0.0};
       RealT     G_{0.0};
       RealT     B_{0.0};
+      RealT     tap_{1.0};
+      RealT     phase_{0.0};
       IdxT      bus1_id_{0};
       IdxT      bus2_id_{0};
 
-      /* Derived parameters */
-      RealT b_;
-      RealT g_;
+      AdmittanceBlock y11_;
+      AdmittanceBlock y12_;
+      AdmittanceBlock y21_;
+      AdmittanceBlock y22_;
+
+      int parameter_error_count_{0};
 
       /// Variable monitor
       std::unique_ptr<MonitorT> monitor_;

GridKit/Model/PhasorDynamics/Branch/BranchData.hpp

@@ -1,7 +1,7 @@
 /**
  * @file BranchData.hpp
  * @author Slaven Peles (peless@ornl.gov)
- * @brief Modeling data for branches (transmission lines)
+ * @brief Modeling data for branches
  *
  */
 #pragma once
@@ -15,10 +15,12 @@ namespace GridKit
     /// Initial parameters for a branch
     enum class BranchParameters
     {
-      R, ///< Line series resistance
-      X, ///< Line series reactance
-      G, ///< Line shunt conductance
-      B, ///< Line shunt charging
+      R,     ///< Line series resistance
+      X,     ///< Line series reactance
+      G,     ///< Total shunt conductance
+      B,     ///< Total shunt susceptance
+      tap,   ///< Off-nominal tap magnitude on bus1 side
+      phase, ///< Phase shift angle in radians
     };
 
     /// Ports for a branch