EMT Enhanced Documentation by lukelowry · Pull Request #451 · ORNL/GridKit

lukelowry · 2026-06-13T08:09:22Z

Description

Improves documentation for EMT line models and adds documentation for other models needed to implement the most capable version of the Universal Line Model (ULM).

Proposed changes

Rename to Line documentation for LineLumped and LineDistributed, replacing the old Branch line docs (existing model documentation functionally unchanged)
Enhanced version of LineLumped which is identical to the previous formulation but more general and future compatible
Add an Operators group for the reusable blocks the models build on
- Rational (VectorFit, StateSpace) for empirical f.d. transmission line models
- Shift (Delay, Propagation) for distributed parameter modeling
Reorganize into Component (Bus, Line, Load, Source) and Operators
Add diagrams for the line and operator models, and update the EMT README indexes and figure paths.

Checklist

N/A All tests pass.
N/A Code compiles cleanly with flags -Wall -Wpedantic -Wconversion -Wextra.
N/A The new code follows GridKit™ style guidelines.
N/A There are unit tests for the new code.
The new code is documented.
The feature branch is rebased with respect to the target branch.
I have updated CHANGELOG.md to reflect the changes in this PR.

Further comments

All the EMT models are now formulated as ODEs

lukelowry · 2026-06-16T10:52:28Z

@pelesh, I made this PR draft so you can see the range of complexity for the models and their needs.

An open-source ULM (LineDistributed) would be invaluable, especially if we scale well to large cases. What most authors call 'EMT' is LineLumped, which is just fancy phasor dynamics. ULM is where the prizes are! To my knowledge, no one has ever tried to model the ULM with adaptive stepping like this.

Discuss later.

pelesh

Looks good. Documentation is consistent and all key parameters and variables are well defined. Some minor formatting issues need to be addressed.

We can merge as soon as @abirchfield approves.

pelesh · 2026-07-03T03:33:03Z

-Bus <Bus/README>
 Component <Component/README>
+Operators <Operators/README>


I would separate buses/nodes from other components.

pelesh · 2026-07-03T03:36:33Z

+-------- | ------ | ---------- | -------
+[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) characteristic admittance $\mathbf{y}_c$ | $\mathbf{v}_{1}\in\mathbb{R}^N$ | `Yc` | $\mathbf{i}^{\mathrm{sh}}_{1}\in\mathbb{R}^K$
+[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) characteristic admittance $\mathbf{y}_c$ | $\mathbf{v}_{2}\in\mathbb{R}^N$ | `Yc` | $\mathbf{i}^{\mathrm{sh}}_{2}\in\mathbb{R}^K$
+[`Propagation`](../../../Operators/Shift/Propagation/README.md) $\mathbf{h}$ | $2\mathbf{i}^{\mathrm{sh}}_{2}-\mathbf{i}^{\mathrm{inc}}_{2}$ | `H` | $\mathbf{i}^{\mathrm{inc}}_{1}\in\mathbb{R}^K$


Expressions for H inputs do not render correctly in Github.

pelesh · 2026-07-03T03:38:04Z

+
+Symbol           | Units        | JSON | Description                        | Note
+---------------- | ------------ | ---- | ---------------------------------- | ----
+$\mathbf{Z}'$    | [$\Omega$/m] | `Zp` | Series impedance per unit length   | $\mathbf{Z}'\in\mathbb{C}^{N \times N}$


Symbol for ohm does not render correctly in GitHub.

pelesh · 2026-07-03T03:40:55Z

+$R_a$   | [$\Omega$] | `Ra` | Load resistance, phase a |
+$R_b$   | [$\Omega$] | `Rb` | Load resistance, phase b |
+$R_c$   | [$\Omega$] | `Rc` | Load resistance, phase c |


Adding space after angle bracket helps symbol for ohm render correctly in GitHub (you do get an ugly space though):

Suggested change

$R_a$ | [$\Omega$] | `Ra` | Load resistance, phase a |

$R_b$ | [$\Omega$] | `Rb` | Load resistance, phase b |

$R_c$ | [$\Omega$] | `Rc` | Load resistance, phase c |

$R_a$ | [ $\Omega$] | `Ra` | Load resistance, phase a |

$R_b$ | [ $\Omega$] | `Rb` | Load resistance, phase b |

$R_c$ | [ $\Omega$] | `Rc` | Load resistance, phase c |

pelesh · 2026-07-03T03:43:23Z

+  \mathbf{R} &= \operatorname{diag}(R_a, R_b, R_c) \\
+  \mathbf{L} &= \operatorname{diag}(L_a, L_b, L_c)


Macro \operatorname is not recognized. Try \mathrm:

Suggested change

\mathbf{R} &= \operatorname{diag}(R_a, R_b, R_c) \\

\mathbf{L} &= \operatorname{diag}(L_a, L_b, L_c)

\mathbf{R} &= \mathrm{diag}(R_a, R_b, R_c) \\

\mathbf{L} &= \mathrm{diag}(L_a, L_b, L_c)

pelesh · 2026-07-03T03:48:24Z

+\mathbf{F}_{\mathrm{in}}(s) &\approx
+\widehat{\mathbf{H}}^{\mathrm{mps}}(s)\mathbf{T}_v(s)^{\mathsf H} \\
+\boldsymbol{\Delta}_{\tau}(s) &=
+\operatorname{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\


Suggested change

\operatorname{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\

\mathrm{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\

See earlier comment about macros.

abirchfield

Changes discussed in person, including
(1) Generic N-phase representation, with comments explaining 3-phase will be implemented first
(2) i-dot notation replaced with either i-prime or di/dt
(3) Describing a non-sub-module version of the lumped line model to accelerate implementation of first EMT cases.
(4) Function instead of convolution notation for submodule processes
(5) For submodules, match up the orders and explain any constraints on the parameters
(6) The delay model is for scalars, but used as vector in the propagation model
(7) Delay model needs to note that the second equation is repeated from 1 to n-1.

…p ci]

lukelowry added the documentation Improvements or additions to documentation label Jun 13, 2026

lukelowry self-assigned this Jun 13, 2026

lukelowry force-pushed the lukel/fd-line-dev branch 3 times, most recently from 9f42d0c to a94de20 Compare June 16, 2026 09:53

lukelowry requested a review from pelesh June 16, 2026 10:41

lukelowry force-pushed the lukel/fd-line-dev branch from 53ed821 to 56330ec Compare June 20, 2026 07:42

lukelowry requested a review from abirchfield June 20, 2026 18:33

lukelowry marked this pull request as ready for review June 20, 2026 18:33

lukelowry force-pushed the lukel/fd-line-dev branch 3 times, most recently from 662f657 to a55ce6a Compare June 25, 2026 21:18

pelesh approved these changes Jul 3, 2026

View reviewed changes

abirchfield requested changes Jul 8, 2026

View reviewed changes

lukelowry force-pushed the lukel/fd-line-dev branch from a55ce6a to ac01b3b Compare July 9, 2026 03:51

lukelowry changed the title ~~EMT Universal Line Model Documentation~~ EMT Enhanced Documentation Jul 9, 2026

lukelowry added 13 commits July 9, 2026 10:10

Document EMT distributed frequency-dependent branch model

d7a1cf5

Document EMT rational transfer and state-space components

3dd0a12

Document EMT propagation component

cee35ff

Diagram and documentation for EMT delay model

e64adcb

Refine and reogranize [skip ci]

09271ae

Update diagrams [skip ci]

78a59bf

Fix GH Math Rendering [skip ci]

ed4a8dc

Fix GH Math render again [skip ci]

7ebd188

Fix GH Math render x3 [skip ci]

b19b2a9

StateSpace and diagram updates

15e9fcf

Polished and corrected Delay

131fc3e

corrected propagation model

62f9908

Polish and standardize VecFit

c96a636

lukelowry added 12 commits July 9, 2026 10:10

StateSpace doc adjust [skip ci]

a752b49

Polish/fix LineDistributed (which is now fully expressed as ODE) [ski…

09b3166

…p ci]

Update Bus docs [skip ci]

f16470a

Refine LineLumped

6c95c7b

Clean LoadRL docs [skip ci]

906f87b

Polish VoltageSource [skip ci]

3d6284d

Final documentation polish [skip ci]

765a20b

image alignment [skip ci]

b8ece09

images in md format [skip ci]

99e34ba

polish bus formulation [skip ci]

65a7cbb

main EMT root and Bus

b820d62

updated EMT docs partially

a7f1f84

lukelowry force-pushed the lukel/fd-line-dev branch from 7fa7ee3 to a7f1f84 Compare July 9, 2026 15:10

lukelowry added 3 commits July 9, 2026 14:55

Directory and Bus

488caf3

initial standardization attempt

e7a73b7

Cleaner more consistant documentation

0be0c88

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

EMT Enhanced Documentation#451

EMT Enhanced Documentation#451
lukelowry wants to merge 28 commits into
developfrom
lukel/fd-line-dev

lukelowry commented Jun 13, 2026 •

edited

Loading

Uh oh!

lukelowry commented Jun 16, 2026

Uh oh!

pelesh left a comment

Uh oh!

pelesh Jul 3, 2026

Uh oh!

pelesh Jul 3, 2026

Uh oh!

pelesh Jul 3, 2026

Uh oh!

pelesh Jul 3, 2026

Uh oh!

pelesh Jul 3, 2026

Uh oh!

pelesh Jul 3, 2026

Uh oh!

abirchfield left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		\mathbf{R} &= \operatorname{diag}(R_a, R_b, R_c) \\
		\mathbf{L} &= \operatorname{diag}(L_a, L_b, L_c)

	\operatorname{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\
	\mathrm{diag}\left(e^{-s\tau_1},\ldots,e^{-s\tau_M}\right) \\

Uh oh!

Conversation

lukelowry commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Proposed changes

Checklist

Further comments

Uh oh!

lukelowry commented Jun 16, 2026

Uh oh!

pelesh left a comment

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

pelesh Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

abirchfield left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lukelowry commented Jun 13, 2026 •

edited

Loading