Add Subsystem and Partition Interfaces for PowerElectronics by abdourahmanbarry · Pull Request #560 · ORNL/GridKit

abdourahmanbarry · 2026-08-28T20:36:16Z

Description

In this PR, we implement SubsystemModel for partitioned Power Electronics simulation. The implementation provides the infrastructure required to partition Power Electronics networks, and to evaluate subsystem residuals and Jacobians independently.

This is the third of four stacked pull requests that split PR #492 into simpler, more manageable chunks.

Proposed changes

We added a SubsystemModel class to represent an individual partition and a BusPartitionInterface component to mark partition boundaries. Together, these enable us to partition larger networks for co-simulation and parallel function evaluation.

Checklist

All tests pass.
Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
The new code follows GridKit™ style guidelines.
There are unit tests for the new code.
The new code is documented.
The feature branch is rebased with respect to the target branch.
The CHANGELOG.md has been updated to reflect the changes. If this is a minor PR that is part of a larger fix already included in the file, state so.

superwhiskers

just an architectural question

superwhiskers · 2026-09-03T20:55:42Z

+  /**
+   * @brief Represents a subset of a PowerElectronicsModel that can be evaluated
+   *        independently.
+   *
+   * A SubsystemModel contains a collection of existing GridKit components and
+   * nodes taken from a larger system. Variables owned by those components and
+   * nodes become internal variables of the subsystem. Variables needed by those
+   * components but owned outside the subsystem become external coupling
+   * variables.
+   *
+   * Components normally store connection indices in the global system indexing.
+   * During subsystem allocation, these indices are temporarily replaced with a
+   * contiguous local subsystem indexing so that the subsystem can be evaluated
+   * like an independent PowerElectronicsModel.
+   *
+   * External coupling values must be supplied before residual or Jacobian
+   * evaluation, either directly through the external-data vectors or through a
+   * forcing function.
+   *
+   * @todo Find a better name for this class and its base class.
+   *
+   * @tparam ScalarT Scalar type used by the model.
+   * @tparam IdxT Index type used for variable and connection indices.
+   */


so, my main question here is why do we need this notion of distinct "systems" and "subsystems" present in the codebase?

when first learning about system partitioning stuff in gridkit, it seemed more natural to me to instead allow the system itself to be a component that can be used in another system. the "non-owning" nature of SubsystemModel as implemented here seems like it could be more naturally captured by a SystemModelRef or some similar type that encapsulates the notion of "referencing" a system model or something like that (perhaps to match the bus partition interface thing for components---SystemModelInterface).

what was the motivation behind this design choice? it seems more natural to build up from smaller components than to break apart.

Good question. There are several reasons for doing it this way.

First, when we partition a system, each subsystem is smaller than the original system, so we can no longer directly use the global indices of the components when evaluating the subsystem. We therefore need to map the global system indices to the corresponding local subsystem indices. This mapping is not needed when evaluating the monolithic system, but it is something we must do before we can evaluate partitions independently.

Second, there is an important difference in how the two models are used. PowerElectronicsModel is designed to construct and own a network. We add components and nodes to it to build up the system. SubsystemModel expects to receive part of an already existing network. It is not trying to construct another network or own those components. If we combine everything into a single class, the same class would need logic for both constructing a network(not need when you are absorbing a part of an already existing network) and representing a partition of an existing network, in addition to handling local/global index mappings and internal/external variables management. I think keeping those responsibilities separate makes the design easier to understand. In addition, the SubsystemModel is still a System model because it inherits and reuses a lot of code from the System Model.

I agree with you that, ideally, we would want a System Model that can be treated as a component, and can be nested hierarchically to arbitrary depth. This was actually one of our design considerations. However, we agreed that supporting that design properly would require a substantial amount time, but we do not have much time left under the scope of the AGM project.

i think that we should open an issue regarding "componentized" system models to replace the partitioning implementation approach implemented in this pull request if doing so right now is too difficult

We are already heading down that direction with this implementation. It might need couple of cycles to get there. This is a good starting point I think. I have attached a snapshot of a design document I shared with Slaven couple of months ago. It needs to be update, but this section talks about doing exactly what you are thinking.

This chart is more applicable to multimethod implementation rather than co-simulations. You can indeed use SystmModel in cosimulation framework, where all system components would be connected through signal ports. But to @superwhiskers point, SystemModel could (and probably should) behave as a component.

nkoukpaizan

A few specific comments.

This seems to work, but I find the logic of the BusPartitionInterface constructor and SubsystemModel index maps hard to follow. I would like to get inputs from @alexander-novo on those implementations.

I'll take another look after the initial comments have been addressed.

nkoukpaizan · 2026-09-10T20:45:52Z

+  template <class ScalarT, typename IdxT>
+  class HiresComponent1 : public CircuitComponent<ScalarT, IdxT>


Will need to update the namespaces after #576

abdourahmanbarry · 2026-09-19T00:49:09Z

@nkoukpaizan @alexander-novo @superwhiskers I have updated the code to incorporate the suggestions and improved the documentation to make the implementation easier to follow. Let me know what you think.

superwhiskers

just one minor comment

abdourahmanbarry · 2026-10-12T15:40:34Z

@nkoukpaizan I have added the partition interface that we discussed last time. It is simpler (and hopefully more efficient), but it only supports partitioning between a MicrogridBus and a MicrogridLine. I believe this covers the most common use cases for partitioning in cosim for PowerElectronics. I still advice we keep the other partition interface for partitioning test problems that are not necessarily PowerElectronics such as the Hires test problem.

CC: @pelesh @alexander-novo @superwhiskers

superwhiskers

looks good. all of these are nitpicks. SubsystemModelWithHires passes just fine on my machine.

nkoukpaizan

I like the BusLinePartitionInterface. Please see my related comments and other comments below.

nkoukpaizan · 2026-10-14T20:34:20Z

+     * @param id Unique identifier for the partition interface.
+     */
+    template <class ScalarT, typename IdxT>
+    BusLinePartitionInterface<ScalarT, IdxT>::BusLinePartitionInterface(node_type* bus, component_type* component, IdxT id)


Yes, this is much simpler and easier to understand than BusPartitionInterface. I recommend adding a unit test for this approach or updating the existing test. My preference would be to only keep BusLinePartitionInterface for now and only introduce BusPartitionInterface if/when the need arises.

Also, I believe we don't need clone() in this approach. We can directly compute and store the relevant indices and signs in the constructor.

Since the BusLinePartitionInterface is specific to the connection between a bus and a line, removing BusPartitionInterface means the Hires Test problem can no longer be partitioned as in the current design, since it does not contain a line.

I plan to keep the BusPartitionInterface and the Hires test problem in a separate branch for order testing of my cosims methods, without any plans of merging to develop. For now I have removed the Hires test and added a new Power Electronics test to validate the partitioning implementation.

Since Hires is not specific to PowerElectronics, I recommend a custom evaluator with the partitions in the unit test, similar to what's being done in #614. A PR with Hires testing the (higer-order) co-simulation methods is welcome.

nkoukpaizan · 2026-10-14T20:49:00Z

+  /**
+   * @todo Move all PowerElectronics models into the PowerElectronics namespace
+   *       for consistency.
+   */


We merged the namespace fix. Rebasing would help (and reduce the conflicts with develop).

This is now rebased with respect to develop. You can have a look again if you have time.

…onstructor

read-the-docs-community · 2026-10-30T20:07:13Z

Documentation build overview

📚 GridKit | 🛠️ Build #35533010 | 📁 Comparing c96a613 against latest (94c9766)

🔍 Preview build

29 files changed · + 7 added · ± 22 modified

+ Added

± Modified

abdourahmanbarry self-assigned this Aug 28, 2026

abdourahmanbarry force-pushed the abdou/subsystem_model branch from 45b0f43 to c90bae2 Compare September 3, 2026 18:56

nkoukpaizan requested review from alexander-novo, nkoukpaizan and superwhiskers September 3, 2026 20:17

nkoukpaizan added the enhancement New feature or request label Sep 3, 2026

superwhiskers reviewed Sep 3, 2026

View reviewed changes

abdourahmanbarry force-pushed the abdou/subsystem_model branch from 6b976de to 1ad85a7 Compare September 8, 2026 16:50

Base automatically changed from abdou/clone to develop September 8, 2026 17:51

nkoukpaizan force-pushed the abdou/subsystem_model branch from 1ad85a7 to e23c7ba Compare September 8, 2026 17:51

abdourahmanbarry mentioned this pull request Sep 8, 2026

Initial Implementation of Subsystem Model for Partition Simulation #492

Closed

7 tasks done

nkoukpaizan reviewed Sep 10, 2026

View reviewed changes

superwhiskers reviewed Sep 25, 2026

View reviewed changes

Comment thread GridKit/Model/PowerElectronics/PartitionInterface/BusPartitionInterface.cpp Resolved

superwhiskers approved these changes Oct 13, 2026

View reviewed changes

Comment thread GridKit/Model/PowerElectronics/PartitionInterface/BusLinePartitionInterface.cpp Resolved

Comment thread GridKit/Model/PowerElectronics/PartitionInterface/BusLinePartitionInterface.hpp Resolved

Comment thread GridKit/Model/PowerElectronics/SubsystemModel.hpp Resolved

nkoukpaizan reviewed Oct 14, 2026

View reviewed changes

abdourahmanbarry and others added 11 commits October 30, 2026 15:15

Add BusPartitionInterface to define partition boundaries

ee0b1b1

Add SubsystemModel for partition evaluation

ca6fe44

Add HIRES test for SubsystemModel

c315040

Add protected access to SystemModelPowerElectronics

ac8769e

Change external data vector to use GridKit vectors

6c76011

Updated SystemModelPowerElectronics.hpp

a67eef2

Update README.md for Hires problem

3d36c47

Minor update

35af962

Apply pre-commit fixes

239fbdd

Address leak in test

4b4c8b6

Change neg1 to INVALID_INDEX

50c8f26

abdourahmanbarry added 19 commits October 30, 2026 15:18

Simplified SubsystemModel code

ac21a74

Update BusPartitionInterface constructor and documentation

e37d476

Update test case

ed86caa

Bug fix

daba0ee

Update SubsystemModel

ceb7c5c

Add BusLinePartitionInterface

bc769a9

Update CMake

88043c4

Forward time updates to enclosed component in BusPartitionInterface

ccfaa9f

Update SubsystemModel

3de0eba

Remove cloned component and move connection index initialization to c…

768622f

…onstructor

Remove Hires Test problem

b023eb3

Add partition PowerElectronics Test problem

39f879c

Update CMake file in tests

73869f1

Remove BusPartitionInterface as requested during code review

489655c

change "counter" to "index"

3c0aa34

Set f_ext_data_ to zero

4a1235e

Updated SystemModels

b6581b6

Update Interfaces

4f1fa56

Update tests

cde9d74

abdourahmanbarry force-pushed the abdou/subsystem_model branch from 33726c6 to cde9d74 Compare October 30, 2026 20:01

Apply pre-commit fixes

c96a613

		template <class ScalarT, typename IdxT>
		class HiresComponent1 : public CircuitComponent<ScalarT, IdxT>

Conversation

abdourahmanbarry commented Aug 28, 2026

Description

Proposed changes

Checklist

Uh oh!

superwhiskers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nkoukpaizan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

abdourahmanbarry commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

superwhiskers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

abdourahmanbarry commented Oct 12, 2026

Uh oh!

superwhiskers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nkoukpaizan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abdourahmanbarry Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

read-the-docs-community Bot commented Oct 30, 2026

Documentation build overview

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

abdourahmanbarry commented Sep 19, 2026 •

edited

Loading

abdourahmanbarry Oct 30, 2026 •

edited

Loading