Design for PowerFlow and PhasorDynamics Interoperability

GridKit/Model/PhasorDynamics/BusFault/BusFault.hpp

@@ -4,6 +4,7 @@
 #include <GridKit/Model/PhasorDynamics/BusBase.hpp>
 #include <GridKit/Model/PhasorDynamics/BusFault/BusFaultData.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
+#include <GridKit/Model/PhasorDynamics/SignalPorts.hpp>
 #include <GridKit/Model/VariableMonitor.hpp>
 
 namespace GridKit
@@ -40,6 +41,8 @@ namespace GridKit
       using ModelDataT = BusFaultData<RealT, IdxT>;
       using MonitorT   = Model::VariableMonitor<BusFault, BusFaultData>;
 
+      using SignalPortsT = SignalPorts<ScalarT, ModelDataT>;
+
       BusFault(BusT* bus);
       BusFault(BusT* bus, RealT R, RealT X, int status);
       BusFault(BusT* bus, const ModelDataT& data);
@@ -63,6 +66,11 @@ namespace GridKit
       }
 
     public:
+      SignalPortsT& getPorts()
+      {
+        return ports_;
+      }
+
       void setR(RealT R)
       {
         R_ = R;
@@ -112,6 +120,8 @@ namespace GridKit
           const ScalarT*, const ScalarT*, const ScalarT*, ScalarT*);
 
     private:
+      SignalPortsT ports_;
+
       BusT* bus_;
       RealT R_{0.0};
       RealT X_{0.0};

GridKit/Model/PhasorDynamics/BusFault/BusFaultData.hpp

@@ -35,6 +35,8 @@ namespace GridKit
     /// Signal outputs supported for a bus fault
     enum class BusFaultSignalOutputs : size_t
     {
+      ir, ///< Real terminal current
+      ii, ///< Imaginary terminal current
     };
 
     /// Variables able to be monitored for a bus fault

GridKit/Model/PhasorDynamics/BusFault/BusFaultImpl.hpp

@@ -135,6 +135,15 @@ namespace GridKit
         this->setResidualIndex(j, j);
       }
 
+      if (auto port = ports_.out.template port<BusFaultSignalOutputs::ir>())
+      {
+        port.link(&y_.getData()[0], &(this->getVariableIndex(0)));
+      }
+      if (auto port = ports_.out.template port<BusFaultSignalOutputs::ii>())
+      {
+        port.link(&y_.getData()[1], &(this->getVariableIndex(1)));
+      }
+
       allocated_ = true;
       return 0;
     }

GridKit/Model/PhasorDynamics/BusFault/CMakeLists.txt

@@ -28,6 +28,13 @@ gridkit_add_library(
   SOURCES BusFaultDependencyTracking.cpp
   LINK_LIBRARIES PUBLIC GridKit::phasor_dynamics_core)
 
+target_link_libraries(
+  phasor_dynamics_bus_fault
+  PUBLIC GridKit::phasor_dynamics_signal)
+target_link_libraries(
+  phasor_dynamics_bus_fault_dependency_tracking
+  PUBLIC GridKit::phasor_dynamics_signal_dependency_tracking)
+
 # Link to interface target for all components
 target_link_libraries(
   phasor_dynamics_components

GridKit/Model/PhasorDynamics/Converter/REGCA/README.md

@@ -93,8 +93,8 @@ Name       | Port   | Init    | Description
 `bus`      | Bus    | Known   | Terminal bus voltage
 `ipcmd`    | Input  | Unknown | Active-current command input
 `iqcmd`    | Input  | Unknown | Reactive-current command input
-`ibranchr` | Output | Known   | Branch-current real-component output
-`ibranchi` | Output | Known   | Branch-current imaginary-component output
+`ir`       | Output | Known   | Terminal-current real-component output
+`ii`       | Output | Known   | Terminal-current imaginary-component output
 `pbranch`  | Output | Known   | Branch active-power output
 `qbranch`  | Output | Known   | Branch reactive-power output
 
@@ -265,8 +265,8 @@ All internal derivatives initialize to zero.
 
 Monitor | Units  | Description                 | Note
 --------|--------|-----------------------------|------
-`ir`   | [p.u.] | Real current injection      | System base; exported through `ibranchr` when assigned
-`ii`   | [p.u.] | Imaginary current injection | System base; exported through `ibranchi` when assigned
+`ir`   | [p.u.] | Real current injection      | System base; exported through `ir` when assigned
+`ii`   | [p.u.] | Imaginary current injection | System base; exported through `ii` when assigned
 `p`    | [p.u.] | Active-power output         | System base; exported through `pbranch` when assigned
 `q`    | [p.u.] | Reactive-power output       | System base; exported through `qbranch` when assigned
 

GridKit/Model/PhasorDynamics/Converter/REGCA/RegcaData.hpp

@@ -55,10 +55,10 @@ namespace GridKit
       /// Signal outputs for the REGCA converter model.
       enum class RegcaSignalOutputs : size_t
       {
-        ibranchr, ///< Optional branch-current real-component output signal ID
-        ibranchi, ///< Optional branch-current imaginary-component output signal ID
-        pbranch,  ///< Optional branch active-power output signal ID
-        qbranch,  ///< Optional branch reactive-power output signal ID
+        ir,      ///< Optional terminal-current real-component output signal ID
+        ii,      ///< Optional terminal-current imaginary-component output signal ID
+        pbranch, ///< Optional branch active-power output signal ID
+        qbranch, ///< Optional branch reactive-power output signal ID
       };
 
       /// Variables available through the monitor interface.

GridKit/Model/PhasorDynamics/Converter/REGCA/RegcaImpl.hpp

@@ -330,13 +330,13 @@ namespace GridKit
 
         auto* y = y_.getData();
 
-        if (auto port = ports_.out.template port<RegcaSignalOutputs::ibranchr>())
+        if (auto port = ports_.out.template port<RegcaSignalOutputs::ir>())
         {
           port.link(&y[static_cast<size_t>(RegcaInternalVariables::IR)],
                     &(this->getVariableIndex(static_cast<IdxT>(RegcaInternalVariables::IR))));
         }
 
-        if (auto port = ports_.out.template port<RegcaSignalOutputs::ibranchi>())
+        if (auto port = ports_.out.template port<RegcaSignalOutputs::ii>())
         {
           port.link(&y[static_cast<size_t>(RegcaInternalVariables::II)],
                     &(this->getVariableIndex(static_cast<IdxT>(RegcaInternalVariables::II))));

GridKit/Model/PhasorDynamics/Load/LoadZ/CMakeLists.txt

@@ -33,6 +33,13 @@ gridkit_add_library(
   SOURCES LoadZDependencyTracking.cpp
   LINK_LIBRARIES PUBLIC GridKit::phasor_dynamics_core)
 
+target_link_libraries(
+  phasor_dynamics_loadz
+  PUBLIC GridKit::phasor_dynamics_signal)
+target_link_libraries(
+  phasor_dynamics_loadz_dependency_tracking
+  PUBLIC GridKit::phasor_dynamics_signal_dependency_tracking)
+
 # Link to interface target for all components
 target_link_libraries(
   phasor_dynamics_components

GridKit/Model/PhasorDynamics/Load/LoadZ/LoadZ.hpp

@@ -3,6 +3,7 @@
 #include <GridKit/Model/PhasorDynamics/BusBase.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
 #include <GridKit/Model/PhasorDynamics/Load/LoadZ/LoadZData.hpp>
+#include <GridKit/Model/PhasorDynamics/SignalPorts.hpp>
 #include <GridKit/Model/VariableMonitor.hpp>
 
 namespace GridKit
@@ -43,6 +44,8 @@ namespace GridKit
       using ModelDataT = LoadZData<RealT, IdxT>;
       using MonitorT   = Model::VariableMonitor<LoadZ, LoadZData>;
 
+      using SignalPortsT = SignalPorts<ScalarT, ModelDataT>;
+
       LoadZ(BusT* bus);
       LoadZ(BusT* bus, RealT R, RealT X);
       LoadZ(BusT* bus, const ModelDataT& data);
@@ -62,6 +65,11 @@ namespace GridKit
       }
 
     public:
+      SignalPortsT& getPorts()
+      {
+        return ports_;
+      }
+
       void setR(RealT R)
       {
         R_ = R;
@@ -107,6 +115,8 @@ namespace GridKit
           const ScalarT*, const ScalarT*, const ScalarT*, ScalarT*);
 
     private:
+      SignalPortsT ports_;
+
       BusT* bus_{nullptr};
       RealT R_{0.1};
       RealT X_{0.01};

GridKit/Model/PhasorDynamics/Load/LoadZ/LoadZData.hpp

@@ -33,6 +33,8 @@ namespace GridKit
     /// Signal outputs supported for a load
     enum class LoadZSignalOutputs : size_t
     {
+      ir, ///< Real terminal current
+      ii, ///< Imaginary terminal current
     };
 
     /// Variables able to be monitored for a load

GridKit/Model/PhasorDynamics/Load/LoadZ/LoadZImpl.hpp

@@ -105,6 +105,15 @@ namespace GridKit
       wb_.resize(2);
       h_.resize(2);
 
+      if (auto port = ports_.out.template port<LoadZSignalOutputs::ir>())
+      {
+        port.link(&y_.getData()[0], &(this->getVariableIndex(0)));
+      }
+      if (auto port = ports_.out.template port<LoadZSignalOutputs::ii>())
+      {
+        port.link(&y_.getData()[1], &(this->getVariableIndex(1)));
+      }
+
       allocated_ = true;
       return 0;
     }

GridKit/Model/PhasorDynamics/Load/LoadZIP/CMakeLists.txt

@@ -28,6 +28,13 @@ gridkit_add_library(
   SOURCES LoadZIPDependencyTracking.cpp
   LINK_LIBRARIES PUBLIC GridKit::phasor_dynamics_core)
 
+target_link_libraries(
+  phasor_dynamics_loadzip
+  PUBLIC GridKit::phasor_dynamics_signal)
+target_link_libraries(
+  phasor_dynamics_loadzip_dependency_tracking
+  PUBLIC GridKit::phasor_dynamics_signal_dependency_tracking)
+
 # Link to interface target for all components
 target_link_libraries(
   phasor_dynamics_components

GridKit/Model/PhasorDynamics/Load/LoadZIP/LoadZIP.hpp

@@ -3,6 +3,7 @@
 #include <GridKit/Model/PhasorDynamics/BusBase.hpp>
 #include <GridKit/Model/PhasorDynamics/Component.hpp>
 #include <GridKit/Model/PhasorDynamics/Load/LoadZIP/LoadZIPData.hpp>
+#include <GridKit/Model/PhasorDynamics/SignalPorts.hpp>
 #include <GridKit/Model/VariableMonitor.hpp>
 
 namespace GridKit
@@ -43,6 +44,8 @@ namespace GridKit
       using ModelDataT = LoadZIPData<RealT, IdxT>;
       using MonitorT   = Model::VariableMonitor<LoadZIP, LoadZIPData>;
 
+      using SignalPortsT = SignalPorts<ScalarT, ModelDataT>;
+
       LoadZIP(BusT* bus);
       LoadZIP(BusT* bus, RealT Pnom, RealT Qnom, RealT alphaI, RealT alphaP);
       LoadZIP(BusT* bus, const ModelDataT& data);
@@ -62,6 +65,11 @@ namespace GridKit
       }
 
     public:
+      SignalPortsT& getPorts()
+      {
+        return ports_;
+      }
+
       void setPnom(RealT Pnom)
       {
         Pnom_ = Pnom;
@@ -120,6 +128,8 @@ namespace GridKit
           const ScalarT*, const ScalarT*, const ScalarT*, ScalarT*);
 
     private:
+      SignalPortsT ports_;
+
       BusT* bus_{nullptr};
       RealT Pnom_{0};
       RealT Qnom_{0};

GridKit/Model/PhasorDynamics/Load/LoadZIP/LoadZIPData.hpp

@@ -30,6 +30,8 @@ namespace GridKit
     /// Signal outputs supported for a loadZIP
     enum class LoadZIPSignalOutputs : size_t
     {
+      ir, ///< Real terminal current
+      ii, ///< Imaginary terminal current
     };
 
     /// Variables able to be monitored for a loadZIP

GridKit/Model/PhasorDynamics/Load/LoadZIP/LoadZIPImpl.hpp

@@ -118,6 +118,15 @@ namespace GridKit
       wb_.resize(2);
       h_.resize(2);
 
+      if (auto port = ports_.out.template port<LoadZIPSignalOutputs::ir>())
+      {
+        port.link(&y_.getData()[0], &(this->getVariableIndex(0)));
+      }
+      if (auto port = ports_.out.template port<LoadZIPSignalOutputs::ii>())
+      {
+        port.link(&y_.getData()[1], &(this->getVariableIndex(1)));
+      }
+
       allocated_ = true;
       return 0;
     }

GridKit/Model/PhasorDynamics/STATE.md

@@ -0,0 +1,95 @@
+# State Input Format
+
+A state file separates the model definition from its initial state.
+
+This also separates the case from the dispatch. One canonical `texas.case.json` can have multiple operating points in `examples/`:
+
+- `texas-summer2025.state.json`
+- `texas-winter2025.state.json`
+- `texas-summer2026.state.json`
+
+For example `texas-summer2025.state.json` might be structured as:
+
+```json
+"header":{
+    ...
+},
+"buses":{
+    ...
+},
+"devices":{
+    ...
+}
+```
+
+Each entry gives initial outputs and operating settings. Models use these values and connected inputs to initialize their own state.
+
+Buses own their voltage and shunt outputs. Devices own their terminal current outputs. These values support initialization across PowerFlow, OPF, PhasorDynamics, and EMT.
+
+## Bus
+
+### RMS State (PowerFlow & PhasorDynamics)
+
+RMS voltages use real and imaginary parts:
+
+```json
+"bus_id_2533":{
+    "vr": 0.9289638822595822,
+    "vi": -0.39534548980249884
+}
+```
+
+### ABC State (EMT)
+
+EMT bus entries give instantaneous phase voltages. Device entries give currents. Each model defines any other initial states or history it needs.
+
+```json
+"bus_id_2533":{
+    "va": 0.9289638822595822,
+    "vb": -0.39534548980249884,
+    "vc": -0.39534548980249884
+}
+```
+
+## Devices
+
+Device entries give initial outputs and settings such as `online`, `open`, `tap`, and `phase`.
+
+Use `ir`/`ii` for one terminal and `ir1`/`ii1`, `ir2`/`ii2` for multiple terminals. Numbers follow the model's terminal numbering. Currents are positive into each connected bus. Phasor currents use the system base. EMT uses the model's phase output names and units.
+
+> At nonzero voltage, convert terminal power to initial current with `I = conj((P + jQ) / V)`.
+
+```json
+"gen_id_2":{
+    "online": true,
+    "ir": 0.8,
+    "ii": -0.2
+},
+"br_id_2":{
+    "open": false,
+    "tap": 1,
+    "phase": 0
+}
+```
+
+# Migration
+
+- Initialize components from output values and connected inputs.
+- Derive missing values and check the initialization equations.
+
+`Bus`:
+
+- Treat buses as components with `vr` and `vi` output ports.
+- Move voltage initialization from the case to the state file.
+
+`Branch`:
+
+- Expose `ir1`, `ii1`, `ir2`, and `ii2` as output ports.
+- Make `tap`, `phase`, and `open` input ports.
+
+`REGCA`, `LoadZ`, `LoadZIP`, `GENROU`, `GENSAL`, `GenClassical`:
+
+- Expose `ir` and `ii` as output ports.
+- Initialize from terminal voltage and current.
+- Remove generator and converter `p0`/`q0` parameters.
+- Make `online` an input port.

GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/GenrouData.hpp

@@ -53,6 +53,8 @@ namespace GridKit
     enum class GenrouSignalOutputs : size_t
     {
       speed, ///< Unique ID of the signal receiving speed deviation
+      ir,    ///< Real terminal current
+      ii,    ///< Imaginary terminal current
     };
 
     /// Variables able to be monitored for a Genrou generator model