[abirchfield]

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]

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.

[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.

[superwhiskers]

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]

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.

[nkoukpaizan]

In the current version, this is the last item before the examples, which I think is fine.

[superwhiskers]

there were several future work comments, not just this one

[abirchfield]

Thanks everyone for helpful input here and in the meeting yesterday!

I think these changes address the core consensus.

• Keep the name "partition" and a separate file.
• Keep partitions focused on parallel solvers, rather than modeling convenience
  (which would be better addressed by subsystem components in the main model
  file)
• Remove Partition Groups and allow partitions to contain other partitions as
  well as internal and external buses.
• Keep the concept of internal and external buses: internal is completely
  contained to the partition itself, external may be globally connected.

[read-the-docs-community]

Documentation build overview

📚 GridKit | 🛠️ Build #35645091 | 📁 Comparing 0e111fa against latest (642d370)

  🔍 Preview build  

2 files changed

± api/reference/file_GridKit_AutomaticDifferentiation_DependencyTracking_VariableOperators.hpp.html
± api/reference/namespace_GridKit__DependencyTracking.html

[nkoukpaizan]

I resolved most of the comments from the previous reviews. There are still a few outstanding items. @abirchfield Will be good to merge after the remaining points are addressed.

• Please use @superwhiskers' suggestion for the introduction, keeping the file format general.
• Please remove the changes in examples/ and the related references in the README.
• Please remove WECC240 from this PR. We'll address this later.

[nkoukpaizan]

Suggested change

File name: `deep.partition.json`