Add partition docs by abirchfield · Pull Request #622 · ORNL/GridKit

abirchfield · 2026-10-15T04:10:19Z

Description

Adding documentation for JSON format for Partitions. See the README for detailed description and justification

Proposed changes

Add README for partitions, along with examples for TenGen and WECC240. Implementation out-of-scope, but see
lukel/partitioned-case-dev branch for a working prototype.

Checklist

N/A - no new code

nkoukpaizan

The ideas in the specifications overall look good to me. A few comments about wording and what's included in this PR.

I would keep the two cases in examples/ out of this PR. The figures are already in GridKit/Model/PhasorDynamics/Partition and nicely rendered in the README. And for now, I wouldn't include *partition.json files for larger systems as in WECC240.partition.json.
I would also remove WECC240.png for now. The notional diagrams are sufficient to illustrate the specifications. If/when we implement WECC240, we can revisit the figure. @lukelowry if you want to improve it in the meantime, I recommend making it publication-ready (larger fonts for buses, bolder lines, etc).

nkoukpaizan · 2026-10-16T11:23:30Z

+This example shows how multi-level hierarchical partitions can be implemented
+with partition groups.
+
+File name: `deep.partition.json`


deep.partition.json is missing from this PR, but is on lukel/partition-dev. I would only keep the inlined json code for this PR.

nkoukpaizan · 2026-10-16T11:45:06Z

+2. A `PartitionGroup` is a container for partitions and other 
+partition groups. It functions as an intermediate node 
+in the partition hierarchy.
+Partition groups do not contain any buses directly.


Suggested change

Partition groups do not contain any buses directly.

Partition groups do not list any buses directly.

I wouldn't make the ownership of external buses a hard requirement in the specifications. Implementation-wise, #620 supports either, and lukel/partition-dev keeps all of them at the root level.

nkoukpaizan · 2026-10-16T11:47:25Z

+3. Every bus must appear somewhere,
+either as `external` or `internal`, but not both.
+4. Internal buses must only appear uniquely in one `Partition`.


We need a rule to reject systems where an external bus is only listed in one partition. It should be internal there, or also listed in the partitions it connects to.

My suggestion would be to have coupling buses belong to the system and be at the same level as partitions. I understand in that case there would ambiguity where components connected directly to the coupling bus belong, but I think that could be addressed.

nkoukpaizan · 2026-10-16T12:00:02Z

+5. Each `Component` that has bus ports shall be assigned to the first 
+`Partition` containing all its bus ports. If none exists,


"First" in the json file order?

nkoukpaizan · 2026-10-16T12:03:32Z

+4. Internal buses must only appear uniquely in one `Partition`.
+5. Each `Component` that has bus ports shall be assigned to the first 
+`Partition` containing all its bus ports. If none exists,
+raise a `BadPartition` exception. 


Suggested change

raise a `BadPartition` exception.

raise an error/exception.

nkoukpaizan · 2026-10-16T12:09:09Z

+The concept of "Partition" is used in phasor dynamics in GridKit to refer
+to dividing up a system model into smaller parts
+**for the purpose of parallel simulation** and other
+solver acceleration techniques. 
+Dividing up a system for _modeling convenience_ (like having physically
+meaningful areas corresponding to particular utilities, 
+containerized subcomponents, template aggregate models
+for multi-instantiation, etc.) 
+is a fundamentally different goal. It is not
+appropriate to use divisions driven by modeling for solver acceleration.


I don't think the partition specification ties us to either goal. We could still express modeling choices in the same format, only that we may ignore load balance, etc.

I agree and I think at this point we only need to have specs on how to define subsystems within a larger system in a JSON input. We can use that definition to create meaningful physical subsystems such as areas within a grid or coarse-grained partitions for parallel computations or partitions for a multimethod integration.

nkoukpaizan · 2026-10-16T12:28:00Z

+If a `Component` assigned to a partition is 
+connected to an unassigned `Component`, 
+assign to the same partition. This process needs to be repeated until no further
+assignments occur.


Suggested change

If a `Component` assigned to a partition is

connected to an unassigned `Component`,

assign to the same partition. This process needs to be repeated until no further

assignments occur.

Place signal-connected devices together, in the first partition containing all bus ports of all of them. Signal nodes go with the devices that use them.

nkoukpaizan · 2026-10-16T12:30:43Z

+assignments occur.
+If a `Component` is left unassigned or if two connected
+components are assigned to different partitions,
+raise a `BadPartition` exception.


Suggested change

raise a `BadPartition` exception.

raise an error/exception.

nkoukpaizan · 2026-10-16T12:32:43Z

+
+## Validation Rules and Component Assignment
+
+Any violation of the rules below results in a `BadPartition` exception.


Suggested change

Any violation of the rules below results in a `BadPartition` exception.

Any violation of the rules below results in an error/exception.

pelesh

This is a very good starting point.

I would limit the scope of this PR just to addressing #619 and specifying JSON input file format for hierarchical modeling. I would focus here on a JSON specs for uniquely defining (arbitrary) subsystems within a system model. Some of the documentation is implementation specific but I don't think we need to go in that detail here.

pelesh · 2026-10-16T19:09:17Z

+This file defines a nested, hierarchical structure of containers
+of type `Partition` and `PartitionGroup`.


I would prefer name Subsystem rather than partition. It would follow current engineering-inspired naming scheme component --> subsystem -->system.

I also don't see a need for PartitionGroup. A subsystem may be composed of components or other subsystems. I don't see significant difference between Partition and PartitionGroup objects as defined and would suggest the simpler solution.

agreed, i don't think PartitionGroup is necessary. from what i can tell, it should be possible to combine any partitions. delineating when this may occur in the format seems redundant.

I think the reason for this is for validation purposes - PartitionGroups can only contain buses and Partitions while Partitions contain actual components. A partitioned integrator can simulate a PartitionGroup while a normal monolithic integrator can simulate a Partition.

pelesh · 2026-10-16T19:17:24Z

+3. Every bus must appear somewhere,
+either as `external` or `internal`, but not both.
+4. Internal buses must only appear uniquely in one `Partition`.


My suggestion would be to have coupling buses belong to the system and be at the same level as partitions. I understand in that case there would ambiguity where components connected directly to the coupling bus belong, but I think that could be addressed.

superwhiskers · 2026-10-16T20:16:08Z

+Partitions for a system are defined in a JSON file, usually called
+`[model_name].partition.json`, which is separate from the system model 
+definition
+but refers to buses by number from the system model definition.
+Defining a partition file for a system is optional, but needed to enable
+parallel model evaluation for some solvers.


Suggested change

Partitions for a system are defined in a JSON file, usually called

`[model_name].partition.json`, which is separate from the system model

definition

but refers to buses by number from the system model definition.

Defining a partition file for a system is optional, but needed to enable

parallel model evaluation for some solvers.

Partitions are defined in a JSON file with an extension of `partition.json`. Partitions are separate from but reference a system model definition through bus numbers specified in the system model. Defining a partition file for a system is optional, but may be necessary for parallel model evaluation depending upon the solver.

we should remove the reference to [model_name] in the name. in the implementation of this format, i think it would be better to specify the partitioning scheme through the simulation interface. something like

./DynamicSimulation --model [model file] --partition [partition file]

where the --partition argument is optional, as partitioning is not necessary.

superwhiskers · 2026-10-16T20:20:00Z

+The concept of "Partition" is used in phasor dynamics in GridKit to refer
+to dividing up a system model into smaller parts
+**for the purpose of parallel simulation** and other
+solver acceleration techniques. 
+Dividing up a system for _modeling convenience_ (like having physically
+meaningful areas corresponding to particular utilities, 
+containerized subcomponents, template aggregate models
+for multi-instantiation, etc.) 
+is a fundamentally different goal. It is not
+appropriate to use divisions driven by modeling for solver acceleration.


Suggested change

The concept of "Partition" is used in phasor dynamics in GridKit to refer

to dividing up a system model into smaller parts

**for the purpose of parallel simulation** and other

solver acceleration techniques.

Dividing up a system for _modeling convenience_ (like having physically

meaningful areas corresponding to particular utilities,

containerized subcomponents, template aggregate models

for multi-instantiation, etc.)

is a fundamentally different goal. It is not

appropriate to use divisions driven by modeling for solver acceleration.

A partition of a phasor dynamics system model specifies a division of the model into smaller parts. Partitioning may be done to facilitate parallel simulation, for modeling convenience, or for some other reason. This document is only concerned with the manner in which a partition scheme is specified.

i think this better introduces the document

superwhiskers · 2026-10-16T20:25:36Z

+In the future it is envisioned that signals may also be part of the 
+partition definition, allowing connected components to be in separate 
+partitions. For now, only buses can divide partitions.


it would be better to move the comments relating to future work later in the document, in a separate section, so that we can focus on the current iteration of the format (and later, the implementation) at the start.

Steven-Roberts · 2026-10-16T21:38:45Z

+As mentioned above, there are two types of objects in a `partition.json` file:
+partitions and partition groups.
+
+1. A `Partition` is a container for buses that is a leaf node of the partition


I'm curious why a partition is a container of buses rather than components. At the last meeting @abirchfield you hinted there was some issue with that approach. Components seem more natural to me because they would require less JSON configuration. You just need disjoint sets of component ID/indices. In contrast, the approach in this PR requires specifying both internal and external buses for each partition. This seems more error prone for human specification and leaves some ambiguity about what partition a component resides in if it only connects to external buses (if that's possible?).

@Steven-Roberts As I understand from what @abirchfield said in the meeting every bus (more or less) has components which are only attached to those buses (at least in the way the models are currently designed). So any external bus must have components which are attached only to them.

Add partition docs

dc9a9ed

abirchfield requested review from lukelowry, nkoukpaizan and pelesh October 15, 2026 04:10

abirchfield self-assigned this Oct 15, 2026

abirchfield added the documentation Improvements or additions to documentation label Oct 15, 2026

abirchfield assigned lukelowry Oct 15, 2026

abirchfield requested a review from alexander-novo October 15, 2026 04:15

nkoukpaizan reviewed Oct 16, 2026

View reviewed changes

This comment was marked as duplicate.

Sign in to view

pelesh requested a review from superwhiskers October 16, 2026 19:03

pelesh reviewed Oct 16, 2026

View reviewed changes

superwhiskers reviewed Oct 16, 2026

View reviewed changes

Steven-Roberts reviewed Oct 16, 2026

View reviewed changes

	Partition groups do not contain any buses directly.
	Partition groups do not list any buses directly.

		5. Each `Component` that has bus ports shall be assigned to the first
		`Partition` containing all its bus ports. If none exists,


		## Validation Rules and Component Assignment

		Any violation of the rules below results in a `BadPartition` exception.

		This file defines a nested, hierarchical structure of containers
		of type `Partition` and `PartitionGroup`.

Conversation

abirchfield commented Oct 15, 2026

Description

Proposed changes

Checklist

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!

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!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

pelesh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

superwhiskers Oct 16, 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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

superwhiskers Oct 16, 2026 •

edited

Loading