Skip to content

Commit 175fe62

Browse files
lukelowrylukelowry
committed
Move docs to EMT and refine READMEs [skip ci]
1 parent 6565915 commit 175fe62

8 files changed

Lines changed: 233 additions & 69 deletions

File tree

GridKit/Model/PhasorDynamics/BranchEMT/README.md renamed to GridKit/Model/EMT/Branch/BranchLumpedConstant/README.md

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
1-
# BranchEMT Model
1+
# BranchLumpedConstant Model
22

3-
`BranchEMT` represents a lumped-parameter EMT transmission line. The nominal
4-
pi model is obtained by spatially discretizing the telegrapher equations over
3+
`BranchLumpedConstant` represents a lumped-parameter EMT transmission line.
4+
The nominal $\pi$-model is obtained by spatially discretizing the telegrapher equations over
55
a segment of length $\Delta x$, with a half shunt placed at each terminal.
6-
Series current $\mathbf{i}_s$ is directed from bus 1 to bus 2. The positive
7-
flow direction is into buses. All parameters are $3 \times 3$ matrices
8-
capturing self and mutual coupling between phases.
6+
Series current $\mathbf{i}$ is directed from bus 1 to bus 2. Bus residual
7+
current injections are positive into buses. All electrical parameter matrices
8+
are $3 \times 3$ and capture self and mutual coupling between phases.
9+
10+
<div align="center">
11+
<img align="center" src="../../../../../docs/Figures/EMT/lumped_constant_diagram.svg">
12+
13+
Figure 1: Lumped constant EMT branch model
14+
</div>
915

1016
## Model Parameters
1117

@@ -17,7 +23,7 @@ $\mathbf{G}'$ | [S/m] | Shunt conductance matrix per unit length | $
1723
$\mathbf{C}'$ | [F/m] | Shunt capacitance matrix per unit length | $\mathbb{R}^{3 \times 3}$
1824
$\Delta x$ | [m] | Line segment length | $\mathbb{R}$
1925

20-
### Model Derived Parameters
26+
## Model Derived Parameters
2127

2228
``` math
2329
\begin{aligned}
@@ -34,7 +40,7 @@ $\Delta x$ | [m] | Line segment length | $
3440

3541
Symbol | Units | Description | Note
3642
-----------------|--------|-----------------------|---------------------------------
37-
$\mathbf{i}_s$ | [A] | Series branch current | $\mathbb{R}^3$, directed bus 1 to bus 2
43+
$\mathbf{i}$ | [A] | Series branch current, directed bus 1 to bus 2 | $\mathbf{i} = [i_a, i_b, i_c]^T \in \mathbb{R}^3$
3844

3945
#### Algebraic
4046

@@ -51,8 +57,8 @@ of equations.
5157

5258
Symbol | Units | Description | Note
5359
-----------------|--------|--------------------------|------------------
54-
$\mathbf{v}_1$ | [V] | Terminal voltage at bus 1 | $\mathbb{R}^3$, owned by EMT bus
55-
$\mathbf{v}_2$ | [V] | Terminal voltage at bus 2 | $\mathbb{R}^3$, owned by EMT bus
60+
$\mathbf{v}_1$ | [V] | Terminal voltage at bus 1, owned by bus 1 | $\mathbf{v}_1 = [v_{1,a}, v_{1,b}, v_{1,c}]^T \in \mathbb{R}^3$
61+
$\mathbf{v}_2$ | [V] | Terminal voltage at bus 2, owned by bus 2 | $\mathbf{v}_2 = [v_{2,a}, v_{2,b}, v_{2,c}]^T \in \mathbb{R}^3$
5662

5763
#### Algebraic
5864

@@ -62,14 +68,9 @@ None.
6268

6369
### Differential Equations
6470

65-
``` math
66-
\dot{\mathbf{i}}_s = \mathbf{L}^{-1}\left((\mathbf{v}_1 - \mathbf{v}_2) - \mathbf{R}\,\mathbf{i}_s\right)
67-
```
68-
69-
(or, alternatively)
7071

7172
``` math
72-
0 = (\mathbf{v}_1 - \mathbf{v}_2) - \mathbf{R}\,\mathbf{i}_s - \mathbf{L}\dot{\mathbf{i}}_s
73+
0 = \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v}_2 - \mathbf{v}_1
7374
```
7475

7576
### Algebraic Equations
@@ -82,11 +83,11 @@ The lumped line contributes to the KCL residual at each terminal bus.
8283
Each expression is accumulated into the owning bus residual.
8384

8485
``` math
85-
\Delta \mathbf{i}_1 = -\mathbf{i}_s - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_1 - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_1
86+
\mathbf{i}^\text{inj}_1 := - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_1 - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_1 - \mathbf{i}
8687
```
8788

8889
``` math
89-
\Delta \mathbf{i}_2 = +\mathbf{i}_s - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_2 - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_2
90+
\mathbf{i}^\text{inj}_2 := - \dfrac{\mathbf{G}}{2}\,\mathbf{v}_2 - \dfrac{\mathbf{C}}{2}\,\dot{\mathbf{v}}_2 + \mathbf{i}
9091
```
9192

9293
## Initialization
@@ -95,10 +96,10 @@ The initialization assumes a balanced three-phase system. Given bus
9596
voltages $\mathbf{v}_1(0)$, $\mathbf{v}_2(0)$ and their time
9697
derivatives $\dot{\mathbf{v}}_1(0)$, $\dot{\mathbf{v}}_2(0)$ from
9798
the EMT bus, and the power flow phasor series current
98-
$I_s = |I_s| \angle \theta$, the initial series current is:
99+
$I = |I| \angle \theta$, the initial series current is:
99100

100101
``` math
101-
\mathbf{i}_s(0) = \sqrt{2}\,|I_s|
102+
\mathbf{i}(0) = \sqrt{2}\,|I|
102103
\begin{bmatrix}
103104
\cos(\theta) \\
104105
\cos(\theta - \tfrac{2\pi}{3}) \\
@@ -110,5 +111,13 @@ The initial derivative is then given by the series branch equation for
110111
DAE consistency:
111112

112113
``` math
113-
\dot{\mathbf{i}}_s(0) = \mathbf{L}^{-1}\left((\mathbf{v}_1(0) - \mathbf{v}_2(0)) - \mathbf{R}\,\mathbf{i}_s(0)\right)
114+
\dot{\mathbf{i}}(0) = \mathbf{L}^{-1}\left(\mathbf{v}_1(0) - \mathbf{v}_2(0) - \mathbf{R}\,\mathbf{i}(0)\right)
114115
```
116+
117+
## Model Outputs
118+
119+
Candidate monitorable outputs include the series branch current components
120+
$i_a$, $i_b$, and $i_c$.
121+
122+
Terminal current injection expressions are documented above as
123+
$\mathbf{i}^\text{inj}_1$ and $\mathbf{i}^\text{inj}_2$.

‎GridKit/Model/EMT/Branch/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Branch Model
2+
3+
## Introduction
4+
5+
EMT branch models represent three-phase network connections between buses in instantaneous abc coordinates.
6+
7+
## Types
8+
9+
### Lumped Parameter
10+
11+
Lumped transmission line models approximate the branch with finite network elements (sometimes referred to as the $\pi$-model). GridKit currently only implements constant parameter.
12+
13+
- `BranchLumpedConstant` (See [BranchLumpedConstant](BranchLumpedConstant/README.md))
14+
- `BranchLumpedFrequencyDependent`
15+
16+
### Distributed Parameter
17+
18+
Distributed transmission line models preserve traveling-wave propagation and delay. GridKit cannot implement these until model internal signal delays are supported.
19+
20+
- `BranchDistributedConstant`
21+
- `BranchDistributedFrequencyDependent`

GridKit/Model/PhasorDynamics/BusEMT/README.md renamed to GridKit/Model/EMT/Bus/README.md

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# EMT Bus Model
1+
# Bus Model
22

3-
`BusEMT` represents a three-phase bus in instantaneous abc coordinates. The
3+
`Bus` represents a three-phase bus in instantaneous abc coordinates. The
44
bus voltages are differential variables, and the model equations enforce
55
three-phase current balance at the bus.
66

@@ -20,9 +20,7 @@ None.
2020

2121
Symbol | Units | Description | Note
2222
---------|-------|--------------------|--------------------------------
23-
$v_a$ | [V] | Bus voltage, phase a |
24-
$v_b$ | [V] | Bus voltage, phase b |
25-
$v_c$ | [V] | Bus voltage, phase c |
23+
$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
2624

2725
#### Algebraic
2826

@@ -42,20 +40,18 @@ None.
4240

4341
### Differential Equations
4442

45-
An explicit $\dot{\mathbf{v}} = \ldots$ form is not used because the
46-
effective shunt admittances depends on connected components and is not
43+
An explicit representation for $\dot{\mathbf{v}}$ is not used because
44+
the effective shunt admittances depend on connected components and are not
4745
known at the bus level. The implicit DAE solver operates directly on
48-
the accumulated KCL residual.
46+
the accumulated KCL residual:
4947

5048
``` math
5149
\begin{aligned}
52-
0 &= \sum_{e \in \mathcal{E}} \Delta i_{a}^{e} \\
53-
0 &= \sum_{e \in \mathcal{E}} \Delta i_{b}^{e} \\
54-
0 &= \sum_{e \in \mathcal{E}} \Delta i_{c}^{e}
50+
0 &= \sum_{e \in \mathcal{E}} \mathbf{i}^\text{inj}_e
5551
\end{aligned}
5652
```
5753

58-
where $\Delta i_{a}^{e}$, $\Delta i_{b}^{e}$, and $\Delta i_{c}^{e}$ are the phase-current contributions
54+
where $\mathbf{i}^\text{inj}_e$ is the vector of phase-current injections
5955
of connected component $e$ into the bus, which are a function of the bus voltage and bus voltage derivative.
6056

6157
### Algebraic Equations

GridKit/Model/PhasorDynamics/LoadEMT/README.md renamed to GridKit/Model/EMT/Component/LoadRL/README.md

Lines changed: 16 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# LoadEMT Model
1+
# LoadRL Model
22

3-
`LoadEMT` represents a three-phase RL load in instantaneous abc coordinates.
4-
The load owns three differential current variables, one for each phase. Load
5-
current $\mathbf{i}$ is directed from the load into the bus.
3+
`LoadRL` represents a three-phase RL load in instantaneous abc coordinates.
4+
The load owns the three-phase differential current vector $\mathbf{i}$,
5+
which is directed from the load into the bus.
66

77
## Model Parameters
88

@@ -30,11 +30,9 @@ $L_c$ | [H] | Load inductance, phase c |
3030

3131
#### Differential
3232

33-
Symbol | Units | Description | Note
34-
--------------------|-------|--------------------------|---------------------------------
35-
$i_a$ | [A] | Load current, phase a | directed from load into bus
36-
$i_b$ | [A] | Load current, phase b | directed from load into bus
37-
$i_c$ | [A] | Load current, phase c | directed from load into bus
33+
Symbol | Units | Description | Note
34+
--------------------|-------|------------------------------------------------|---------------------------------
35+
$\mathbf{i}$ | [A] | Load current vector, directed from load into bus | $\mathbf{i} = [i_a, i_b, i_c]^T \in \mathbb{R}^3$
3836

3937
#### Algebraic
4038

@@ -49,11 +47,9 @@ of equations.
4947

5048
#### Differential
5149

52-
Symbol | Units | Description | Note
53-
--------|-------|-------------------------|------------------
54-
$v_a$ | [V] | Terminal voltage, phase a | owned by EMT bus
55-
$v_b$ | [V] | Terminal voltage, phase b | owned by EMT bus
56-
$v_c$ | [V] | Terminal voltage, phase c | owned by EMT bus
50+
Symbol | Units | Description | Note
51+
-----------------|-------|----------------------------------------------|---------------------------------
52+
$\mathbf{v}$ | [V] | Terminal voltage vector, owned by EMT bus | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
5753

5854
#### Algebraic
5955

@@ -64,13 +60,7 @@ None.
6460
### Differential Equations
6561

6662
``` math
67-
\dot{\mathbf{i}} = -\mathbf{L}^{-1}\left(\mathbf{v} + \mathbf{R}\,\mathbf{i}\right)
68-
```
69-
70-
(or, alternatively)
71-
72-
``` math
73-
0 = \mathbf{v} + \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}}
63+
0 = \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v}
7464
```
7565

7666
### Algebraic Equations
@@ -83,7 +73,7 @@ The RL load contributes to the KCL residual at its terminal bus. The
8373
expression is accumulated into the owning bus residual.
8474

8575
``` math
86-
\Delta \mathbf{i} = \mathbf{i}
76+
\mathbf{i}^\text{inj} := \mathbf{i}
8777
```
8878

8979
## Initialization
@@ -107,3 +97,7 @@ consistency:
10797
``` math
10898
\dot{\mathbf{i}}(0) = -\mathbf{L}^{-1}\left(\mathbf{v}(0) + \mathbf{R}\,\mathbf{i}(0)\right)
10999
```
100+
101+
## Model Outputs
102+
103+
Candidate monitorable outputs include the load current components $i_a$, $i_b$, and $i_c$ (into the bus).

‎GridKit/Model/EMT/Component/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Component Models
2+
3+
This directory contains EMT component model notes for devices connected to EMT
4+
buses.
5+
6+
A component README should include:
7+
1. Model parameters and derived parameters
8+
2. Internal and external variables
9+
3. Differential and algebraic equations
10+
4. Bus residual contributions, when applicable
11+
5. Initialization notes
12+
6. Monitorable outputs
13+
14+
## Types
15+
16+
- `LoadRL` (See [LoadRL](LoadRL/README.md))
17+
- `VoltageSource` (See [VoltageSource](VoltageSource/README.md))

GridKit/Model/PhasorDynamics/SourceEMT/README.md renamed to GridKit/Model/EMT/Component/VoltageSource/README.md

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# SourceEMT Model
1+
# VoltageSource Model
22

3-
`SourceEMT` represents a three-phase voltage source in instantaneous abc
3+
`VoltageSource` represents a three-phase voltage source in instantaneous abc
44
coordinates. The source waveform is configurable by phase magnitude and phase
55
offset for each phase and is otherwise constant. Each source terminal is
66
connected to the EMT bus through a phase resistance.
@@ -15,6 +15,7 @@ $E_c$ | [V] | Source voltage magnitude, phase c | RMS
1515
$\phi_a$ | [rad] | Source phase offset, phase a |
1616
$\phi_b$ | [rad] | Source phase offset, phase b |
1717
$\phi_c$ | [rad] | Source phase offset, phase c |
18+
$\omega_0$ | [rad/s] | Source angular frequency |
1819
$R_a$ | [$\Omega$] | Terminal resistance, phase a |
1920
$R_b$ | [$\Omega$] | Terminal resistance, phase b |
2021
$R_c$ | [$\Omega$] | Terminal resistance, phase c |
@@ -44,11 +45,9 @@ of equations.
4445

4546
#### Differential
4647

47-
Symbol | Units | Description | Note
48-
--------|-------|-------------------------|------------------
49-
$v_a$ | [V] | Terminal voltage, phase a | owned by EMT bus
50-
$v_b$ | [V] | Terminal voltage, phase b | owned by EMT bus
51-
$v_c$ | [V] | Terminal voltage, phase c | owned by EMT bus
48+
Symbol | Units | Description | Note
49+
-----------------|-------|----------------------------------------------|---------------------------------
50+
$\mathbf{v}$ | [V] | Terminal voltage vector, owned by EMT bus | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
5251

5352
#### Algebraic
5453

@@ -67,8 +66,8 @@ None.
6766
### Bus Residual Contributions
6867

6968
The source contributes current to the KCL residual at its terminal bus.
70-
Each expression is accumulated into the owning bus residual. Given the
71-
nominal angular frequency $\omega_0 = 2\pi f_0$, the source waveform is:
69+
The injection vector is accumulated into the owning bus residual. Given source
70+
angular frequency $\omega_0$, the source waveform is:
7271

7372
``` math
7473
\begin{aligned}
@@ -81,11 +80,12 @@ e_c(t) &= \sqrt{2}\,E_c\cos(\omega_0 t + \phi_c)
8180
The current contribution is positive into the bus:
8281

8382
``` math
84-
\begin{aligned}
85-
\Delta i_a &= \dfrac{e_a(t)-v_a}{R_a} \\
86-
\Delta i_b &= \dfrac{e_b(t)-v_b}{R_b} \\
87-
\Delta i_c &= \dfrac{e_c(t)-v_c}{R_c}
88-
\end{aligned}
83+
\mathbf{i}^\text{inj} :=
84+
\begin{bmatrix}
85+
\dfrac{e_a(t)-v_a}{R_a} \\
86+
\dfrac{e_b(t)-v_b}{R_b} \\
87+
\dfrac{e_c(t)-v_c}{R_c}
88+
\end{bmatrix}
8989
```
9090

9191
## Initialization
@@ -99,3 +99,11 @@ e_b(0) &= \sqrt{2}\,E_b\cos(\phi_b) \\
9999
e_c(0) &= \sqrt{2}\,E_c\cos(\phi_c)
100100
\end{aligned}
101101
```
102+
103+
## Model Outputs
104+
105+
Candidate monitorable outputs include the source waveform components
106+
$e_a(t)$, $e_b(t)$, and $e_c(t)$.
107+
108+
The terminal current injection expression is documented above as
109+
$\mathbf{i}^\text{inj}$.

‎GridKit/Model/EMT/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Electromagnetic Transients (EMT)
2+
3+
This directory contains design documentation for electromagnetic transient
4+
(EMT) component models in instantaneous abc coordinates.
5+
6+
## Conventions
7+
8+
These conventions reflect the current EMT model draft and may change as the
9+
EMT design and implementation develop.
10+
11+
- Phase order is $a$, $b$, $c$.
12+
- Equations use SI units unless a model states otherwise.
13+
- Current injection terms are written as positive into buses.
14+
15+
16+
## Model Families
17+
18+
The current EMT documentation is organized into one of three families:
19+
- `Bus`
20+
- `Branch`
21+
- `Component`
22+
23+
## Open Design Notes
24+
25+
Distributed parameter lines are placeholders until internal signal delay support
26+
is designed.
27+
- Initial electrical wiring will use Delta configuration only

0 commit comments

Comments
 (0)