[lukelowry]

Description

Partially addresses #466, #405, and allow us to close related PR #391

Introduce .state.json as a shared initialization/state artifact for PowerFlow and PhasorDynamics (and compatible with EMT), separating operating state and dispatch from the static .case.json model definition. This provides a file-based interoperability boundary without coupling the model implementations.

The proposed format is documented in STATE.md. Further justification for the design is provided in that document

Proposed changes

• Document the proposed state-file structure and migration path.
• Store bus voltages and device current injections under buses.
• Store device dispatch, connectivity, tap, phase, and other initialization states under devices.
• Add a Hawaii example at nominal steady-state dispatch.

If approved, I would like to include a *.state.json for each case as an initial artifact. I only committed an example for the Hawaii case.

[lukelowry]

Using this approach its very easy to exchange states between PowerFlow, PhasorDynamics, and OPF (experimental), see this downstream branch. I can reliably start in steady state after changing the generator dispatch using OPF! And the only shared knowledge between the OPF/ and PhasorDynamics/ is the proposed *.state.json. This contract would make initialization of EMT much easier (which is notoriously hard)

[lukelowry]

Drafting since not likely to be done before release but is very important for the development of EMT and practical use.

[read-the-docs-community]

Documentation build overview

📚 GridKit | 🛠️ Build #35598468 | 📁 Comparing 7607f67 against latest (c9a6497)

  🔍 Preview build  

216 files changed · + 120 added · ± 91 modified · - 5 deleted

+ Added

• api/reference/classAnalysisManager_1_1SteadyState_1_1IpoptInterface.html
• api/reference/classGridKit_1_1Model_1_1OptimizationEvaluator.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Branch.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Bus.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Component.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Generator.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1Load.html
• api/reference/classGridKit_1_1OptimalPowerFlow_1_1SystemModel.html
• api/reference/dir_GridKit_Model_OptimalPowerFlow.html
• api/reference/dir_GridKit_Model_OptimalPowerFlow_Branch.html
• and 110 more...

± Modified

• genindex.html
• cases/README.html
• development/CHANGELOG.html
• examples/README.html
• api/reference/classGridKit_1_1Model_1_1ParameterReader.html
• api/reference/classGridKit_1_1Model_1_1VariableMonitorBase.html
• api/reference/classGridKit_1_1Model_1_1VariableMonitorController.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Component.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Controller_1_1Reecb.html
• api/reference/classGridKit_1_1PhasorDynamics_1_1Controller_1_1Repca.html
• and 81 more...

- Deleted

• api/reference/function_namespaceGridKit_1_1Model_1_1VariableMonitorDetail_1a3739d7ddea33e27e0a5c6a24cb5a6e25.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Csv.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Json.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorBase_1_1Yaml.html
• api/reference/structGridKit_1_1Model_1_1VariableMonitorController_1_1Variable.html

[lukelowry]

This is highest value right now

[nkoukpaizan]

Looks good to me!

[pelesh]

lgtm

[lukelowry]

alright, this is ready. This sets a good direction for how to adjust PhasorDynamics and OPF accordingly.