Final documentation polish [skip ci]

Author: lukelowry

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

@@ -73,13 +73,13 @@ $V = |V| \angle \phi$ and nominal angular frequency $\omega_0 = 2 \pi f_0$:
 
 ```math
 \begin{aligned}
-\mathbf{v}(0) = \sqrt{2}\,|V|
+\mathbf{v}(0) = \sqrt{2}|V|
 \begin{bmatrix}
   \cos(\phi) \\
   \cos(\phi - \tfrac{2\pi}{3}) \\
   \cos(\phi + \tfrac{2\pi}{3})
 \end{bmatrix} \\
-\dot{\mathbf{v}}(0) = -\sqrt{2}\,|V|\,\omega_0
+\dot{\mathbf{v}}(0) = -\sqrt{2}|V|\omega_0
 \begin{bmatrix}
   \sin(\phi) \\
   \sin(\phi - \tfrac{2\pi}{3}) \\

GridKit/Model/EMT/Component/Line/LineDistributed/README.md

@@ -1,7 +1,7 @@
 # LineDistributed Model
 
-`LineDistributed` represents a distributed EMT line with
-characteristic admittance $\mathbf{y}_c$ and propagation model $\mathbf{H}$.
+`LineDistributed` represents a distributed EMT line with characteristic
+admittance $\mathbf{y}_c$ and propagation model $\mathbf{h}$.
 
 ## Block Diagram
 
@@ -13,11 +13,9 @@ characteristic admittance $\mathbf{y}_c$ and propagation model $\mathbf{H}$.
 
 ## Model Parameters
 
-Symbol            | Units       | JSON         | Description                                            | Note
------------------ | ----------- | ------------ | ------------------------------------------------------ | ----
-$\mathbf{P}_\phi$ | [-]         | `conductors` | Permutation matrix mapping each conductor to its phase | $\mathbf{P}_\phi \in \mathbb{R}^{N \times K}$
-$\mathbf{y}_c$    | [S]         | `Yc`         | Characteristic admittance                             | $\mathbf{y}_c \in \mathbb{R}^{K \times N}$
-$\mathbf{h}$      | [-]         | `H`          | Propagation function                                  | $\mathbf{h} \in \mathbb{R}^{K \times K}$
+Symbol            | Units | JSON         | Description                                            | Note
+----------------- | ----- | ------------ | ------------------------------------------------------ | ----
+$\mathbf{P}_\phi$ | [-]   | `conductors` | Permutation matrix mapping each conductor to its phase | $\mathbf{P}_\phi \in \mathbb{R}^{N \times K}$
 
 ### Parameter Validation
 
@@ -28,6 +26,15 @@ None.
 The number of phases $N$ and conductors $K$ are the row and column counts of
 $\mathbf{P}_\phi$, respectively.
 
+### Submodels
+
+Submodel | Inputs | Parameters | Outputs
+-------- | ------ | ---------- | -------
+[`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$
+[`Propagation`](../../../Operators/Shift/Propagation/README.md) $\mathbf{h}$ | $2\mathbf{i}^{\mathrm{sh}}_{1}-\mathbf{i}^{\mathrm{inc}}_{1}$ | `H` | $\mathbf{i}^{\mathrm{inc}}_{2}\in\mathbb{R}^K$
+
 ## Model Variables
 
 ### Internal Variables
@@ -77,18 +84,18 @@ None.
 ```math
 \begin{aligned}
 \mathbf{i}^{\mathrm{sh}}_{1} &=
-  \mathbf{y}_c*\,\mathbf{v}_{1} \\
+  \mathbf{y}_c*\mathbf{v}_{1} \\
 \mathbf{i}^{\mathrm{sh}}_{2} &=
-  \mathbf{y}_c*\,\mathbf{v}_{2} \\
+  \mathbf{y}_c*\mathbf{v}_{2} \\
 \mathbf{i}^{\mathrm{inc}}_{1} &=
-  \mathbf{h}*\,\left(
-  2\,\mathbf{i}^{\mathrm{sh}}_{2}
+  \mathbf{h}*\left(
+  2\mathbf{i}^{\mathrm{sh}}_{2}
   -
   \mathbf{i}^{\mathrm{inc}}_{2}
   \right) \\
 \mathbf{i}^{\mathrm{inc}}_{2} &=
-  \mathbf{h}*\,\left(
-  2\,\mathbf{i}^{\mathrm{sh}}_{1}
+  \mathbf{h}*\left(
+  2\mathbf{i}^{\mathrm{sh}}_{1}
   -
   \mathbf{i}^{\mathrm{inc}}_{1}
   \right) \\
@@ -115,10 +122,10 @@ equations:
 
 ```math
 \begin{aligned}
-\mathbf{i}^{\mathrm{sh}}_{1,0} &= \mathbf{y}_c*\,\mathbf{v}_{1,0} \\
-\mathbf{i}^{\mathrm{sh}}_{2,0} &= \mathbf{y}_c*\,\mathbf{v}_{2,0} \\
-\mathbf{i}^{\mathrm{inc}}_{1,0} &= \mathbf{h}*\,\left(2\,\mathbf{i}^{\mathrm{sh}}_{2,0} - \mathbf{i}^{\mathrm{inc}}_{2,0}\right) \\
-\mathbf{i}^{\mathrm{inc}}_{2,0} &= \mathbf{h}*\,\left(2\,\mathbf{i}^{\mathrm{sh}}_{1,0} - \mathbf{i}^{\mathrm{inc}}_{1,0}\right)
+\mathbf{i}^{\mathrm{sh}}_{1,0} &= \mathbf{y}_c*\mathbf{v}_{1,0} \\
+\mathbf{i}^{\mathrm{sh}}_{2,0} &= \mathbf{y}_c*\mathbf{v}_{2,0} \\
+\mathbf{i}^{\mathrm{inc}}_{1,0} &= \mathbf{h}*\left(2\mathbf{i}^{\mathrm{sh}}_{2,0} - \mathbf{i}^{\mathrm{inc}}_{2,0}\right) \\
+\mathbf{i}^{\mathrm{inc}}_{2,0} &= \mathbf{h}*\left(2\mathbf{i}^{\mathrm{sh}}_{1,0} - \mathbf{i}^{\mathrm{inc}}_{1,0}\right)
 \end{aligned}
 ```
 

GridKit/Model/EMT/Component/Line/LineLumped/README.md

@@ -5,9 +5,9 @@ $\pi$-section equivalent over length $\Delta x$. Series current $\mathbf{i}$
 is directed from terminal 1 to terminal 2.
 
 Notes:
-- Alternatively, $\mathbf{Z}'$ and $\mathbf{Y}'$ may be given directly as
-  `VectorFit` models. Otherwise, they are derived from constant `R`, `L`,
-  `G`, and `C` matrices.
+- $\mathbf{Z}'$ and $\mathbf{Y}'$ may be supplied as per-unit-length
+  `VectorFit` models or derived from constant `Rp`, `Lp`, `Gp`, and `Cp`
+  matrices.
 
 ## Block Diagram
 
@@ -19,41 +19,43 @@ Notes:
 
 ## Model Parameters
 
-Symbol           | Units          | JSON | Description                              | Note
----------------- | -------------- | ---- | ---------------------------------------- | ----
-$\mathbf{R}'$    | [$\Omega$/m]   | `R`  | Series resistance matrix per unit length | $\mathbb{R}^{N \times N}$
-$\mathbf{L}'$    | [H/m]          | `L`  | Series inductance matrix per unit length | $\mathbb{R}^{N \times N}$
-$\mathbf{G}'$    | [S/m]          | `G`  | Shunt conductance matrix per unit length | $\mathbb{R}^{N \times N}$
-$\mathbf{C}'$    | [F/m]          | `C`  | Shunt capacitance matrix per unit length | $\mathbb{R}^{N \times N}$
-$\Delta x$       | [m]            | `dx` | Line segment length                      | $\mathbb{R}$
-$\mathbf{Z}'$    | [$\Omega$/m]   | `Z`  | Series impedance per unit length         | $\mathbb{C}^{N\times N}$, optional `VectorFit` model 
-$\mathbf{Y}'$    | [S/m]          | `Y`  | Shunt admittance per unit length         | $\mathbb{C}^{N\times N}$, optional `VectorFit` model 
+Symbol           | Units        | JSON | Description                        | Note
+---------------- | ------------ | ---- | ---------------------------------- | ----
+$\mathbf{Z}'$    | [$\Omega$/m] | `Zp` | Series impedance per unit length   | $\mathbf{Z}'\in\mathbb{C}^{N \times N}$
+$\mathbf{Y}'$    | [S/m]        | `Yp` | Shunt admittance per unit length   | $\mathbf{Y}'\in\mathbb{C}^{N \times N}$
+$\Delta x$       | [m]          | `dx` | Line segment length                | $\mathbb{R}$
 
 ### Parameter Validation
 
 None.
 
 ### Model Derived Parameters
 
-For the constant `R`, `L`, `G`, and `C` alternative:
+The per-unit-length impedance and admittance models are:
 
 ```math
 \begin{aligned}
-  \mathbf{R} &= \mathbf{R}'\Delta x   & \mathbf{G} &= \dfrac{\mathbf{G}'\Delta x}{2} \\
-  \mathbf{L} &= \mathbf{L}'\Delta x   & \mathbf{C} &= \dfrac{\mathbf{C}'\Delta x}{2}
+  \mathbf{Z}'(s) &= \mathbf{R}' + s\mathbf{L}' + \mathbf{Z}'_{\mathrm{rat}}(s) \\
+  \mathbf{Y}'(s) &= \mathbf{G}' + s\mathbf{C}' + \mathbf{Y}'_{\mathrm{rat}}(s)
 \end{aligned}
 ```
 
-If `Z` and `Y` are not given, they are derived as:
+The segment impedance and shunt admittance operators used by the equations are:
 
 ```math
 \begin{aligned}
-  \mathbf{Z} &= \mathbf{R} + s\mathbf{L} \qquad \text{or} \qquad = \Delta x \mathbf{Z}'\\
-  \mathbf{Y} &= \mathbf{G} + s\mathbf{C} \qquad \text{or} \qquad = \dfrac{\Delta x \mathbf{Y}'}{2}
+  \mathbf{Z} &= \Delta x \mathbf{Z}' \\
+  \mathbf{Y} &= \dfrac{\Delta x \mathbf{Y}'}{2}
 \end{aligned}
 ```
 
-and modeled via `VectorFit`.
+### Submodels
+
+Submodel | Inputs | Parameters | Outputs
+-------- | ------ | ---------- | -------
+[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) series impedance $\mathbf{z}$ | $\mathbf{i}\in\mathbb{R}^N$ | `Zp`, `dx` | $\mathbf{z}*\mathbf{i}$
+[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) shunt admittance $\mathbf{y}_1$ | $\mathbf{v}_1\in\mathbb{R}^N$ | `Yp`, `dx` | $\mathbf{y}_1*\mathbf{v}_1$
+[`VectorFit`](../../../Operators/Rational/VectorFit/README.md) shunt admittance $\mathbf{y}_2$ | $\mathbf{v}_2\in\mathbb{R}^N$ | `Yp`, `dx` | $\mathbf{y}_2*\mathbf{v}_2$
 
 ## Model Variables
 
@@ -106,10 +108,10 @@ None.
 ```math
 \begin{aligned}
 \mathbf{i}^{\mathrm{inj}}_{1} &=
-  - \mathbf{y}*\mathbf{v}_1
+  - \mathbf{y}_1*\mathbf{v}_1
   - \mathbf{i} \\
 \mathbf{i}^{\mathrm{inj}}_{2} &=
-  - \mathbf{y}*\mathbf{v}_2
+  - \mathbf{y}_2*\mathbf{v}_2
   + \mathbf{i}
 \end{aligned}
 ```

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

@@ -28,10 +28,10 @@ The nominal pi model is the constant-parameter lumped case.
 {
   "class": "LineLumped",
   "params": {
-    "R": ...,
-    "L": ...,
-    "G": ...,
-    "C": ...,
+    "Rp": ...,
+    "Lp": ...,
+    "Gp": ...,
+    "Cp": ...,
     "dx": ...
   }
 }
@@ -41,14 +41,16 @@ The nominal pi model is the constant-parameter lumped case.
 
 The frequency-dependent pi model keeps the lumped topology and replaces the
 constant line matrices with rational parameter models.
-Note: using a `VectorFit` model with only $\mathbf{D}$ nonzero is an equivalent
-way to define the nominal pi model.
+Note: using `VectorFit` models for `Zp` and `Yp` with no poles or residues
+is an equivalent way to define the nominal pi model: for `Zp`,
+$\mathbf{D}=\mathbf{R}'$ and $\mathbf{E}=\mathbf{L}'$. For `Yp`,
+$\mathbf{D}=\mathbf{G}'$ and $\mathbf{E}=\mathbf{C}'$.
 
 ```js
 {
   "class": "LineLumped",
   "params": {
-    "Z": {
+    "Zp": {
       "class": "VectorFit",
       "params": {
         "D": ...,
@@ -57,7 +59,7 @@ way to define the nominal pi model.
         "residues": [...]
       }
     },
-    "Y": {
+    "Yp": {
       "class": "VectorFit",
       "params": {
         "D": ...,
@@ -96,9 +98,8 @@ $\mathbf{H}(s)=e^{-s\tau}$.
 
 ### Universal Line Model
 
-The ULM is the general case where a `VectorFit` model defines the
-characteristic admittance $\mathbf{y}_c$ and a `Propagation` model defines the
-current-form propagation function $\mathbf{H}_i$.
+The ULM is the general case with characteristic admittance `Yc` and
+current-form propagation function `H`.
 
 ```js
 {

GridKit/Model/EMT/Component/Load/LoadRL/README.md

@@ -72,7 +72,7 @@ $\mathbf{i}^{\mathrm{inj}}$ | `i` | Output | [A] | Current injection at load por
 ### Differential Equations
 
 ```math
-0 = \mathbf{R}\,\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v}
+0 = \mathbf{R}\mathbf{i} + \mathbf{L}\dot{\mathbf{i}} + \mathbf{v}
 ```
 
 ### Algebraic Equations
@@ -91,7 +91,7 @@ For a balanced three-phase initialization derived from phasor current injection
 $I^{\mathrm{inj}} = |I^{\mathrm{inj}}| \angle \theta$:
 
 ```math
-\mathbf{i}_0 = \sqrt{2}\,|I^{\mathrm{inj}}|
+\mathbf{i}_0 = \sqrt{2}|I^{\mathrm{inj}}|
 \begin{bmatrix}
   \cos(\theta) \\
   \cos(\theta - \tfrac{2\pi}{3}) \\

GridKit/Model/EMT/Component/Source/VoltageSource/README.md

@@ -10,7 +10,7 @@ For phase count $N$:
 
 Symbol                         | Units   | JSON     | Description                       | Note
 -------------------------------|---------|----------|-----------------------------------|-----
-$\mathbf{E}$                   | [V]     | `E`      | Source voltage magnitudes         | RMS, $\mathbf{E}\in\mathbb{R}^N$
+$\mathbf{E}$                   | [V]     | `E`      | Source voltage magnitudes         | $\mathbf{E}\in\mathbb{R}^N$, RMS
 $\boldsymbol{\phi}$            | [rad]   | `phi`    | Source phase offsets              | $\boldsymbol{\phi}\in\mathbb{R}^N$
 $\omega$                       | [rad/s] | `omega`  | Source angular frequency          |
 $\mathbf{g}_{\mathrm{s}}$      | [S]     | `G`      | Terminal conductance              | $\mathbf{g}_{\mathrm{s}}\in\mathbb{R}^N$
@@ -78,7 +78,7 @@ i^{\mathrm{inj}}_n
 =
 g_{\mathrm{s},n}
 \left(
-\sqrt{2}\,E_n\cos\left(\omega t + \phi_n\right) - v_n
+\sqrt{2}E_n\cos\left(\omega t + \phi_n\right) - v_n
 \right)
 ```
 
@@ -91,7 +91,7 @@ i^{\mathrm{inj}}_{n,0}
 =
 g_{\mathrm{s},n}
 \left(
-\sqrt{2}\,E_n\cos\left(\phi_n\right) - v_{n,0}
+\sqrt{2}E_n\cos\left(\phi_n\right) - v_{n,0}
 \right)
 ```
 

GridKit/Model/EMT/Operators/Coordinate/README.md

@@ -6,4 +6,3 @@ Operator models are reusable EMT signal blocks used by component models.
 
 - `Rational` (See [Rational](Rational/README.md))
 - `Shift` (See [Shift](Shift/README.md))
-- `Coordinate` (See [Coordinate](Coordinate/README.md))

GridKit/Model/EMT/Operators/README.md

@@ -7,7 +7,7 @@ The rational approximation is represented in pole form:
 
 ```math
 \mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E}
-  + \sum_{q=1}^{Q} \frac{\mathbf{R}^q}{s - p_q}
+  + \sum_{q=1}^{Q} \frac{\mathbf{R}_q}{s - p_q}
 ```
 
 The Laplace domain representation of this model is:

GridKit/Model/EMT/Operators/Rational/VectorFit/README.md

@@ -4,8 +4,8 @@
 The model maps input signal $u$ to delayed output $y_{\mathrm{out}}$.
 
 Note:
-- This is an exact approximation when used with forward-euler.
-- For other integration methods this is a smooth approximation only.
+- This is exact with forward Euler when the integration step satisfies $h=T$.
+- For other integration methods or time steps, this is a smooth approximation only.
 
 ## Block Diagram