Model Math and Documentation Cleanup

GridKit/Model/EMT/Bus/README.md

@@ -1,8 +1,10 @@
 # Bus Model
 
 `Bus` represents an $N$-phase bus in instantaneous phase coordinates. It owns
-the differential bus voltage and contributes the current-balance residual to
-the assembled DAE. $\mathcal{E}$ denotes the set of connected devices.
+the bus voltage and contributes the current-balance residual to
+the assembled DAE. $`\mathcal{D}`$ denotes the set of connected devices.
+Bus voltage and its residual are algebraic when no connected model contributes
+a voltage derivative; see [assembly](../README.md#assembly).
 
 ## Block Diagram
 
@@ -30,7 +32,7 @@ None.
 
 Symbol | Port | Type | Units | Description | Note
 ------ | ---- | ---- | ----- | ----------- | ----
-$\mathbf{i}_e$ | `i` | Input | [A] | Current from connected device $e$ | One port per $e \in \mathcal{E}$, $\mathbf{i}_e \in \mathbb{R}^N$
+$\mathbf{i}_d$ | `i` | Input | [A] | Current from connected device $d$ | One port per $d \in \mathcal{D}$, $\mathbf{i}_d \in \mathbb{R}^N$
 $\mathbf{v}$ | `v` | Output | [V] | Bus voltage supplied to connected devices | $\mathbf{v} \in \mathbb{R}^N$
 
 ## Submodels
@@ -41,6 +43,10 @@ None.
 
 None.
 
+### Submodel Wiring
+
+None.
+
 ## Model Variables
 
 ### Internal Variables
@@ -72,7 +78,7 @@ None.
 #### Differential
 
 ```math
-0 = \sum_{e \in \mathcal{E}} \mathbf{i}_e
+0 = \sum_{d \in \mathcal{D}} \mathbf{i}_d
 ```
 
 #### Algebraic
@@ -83,13 +89,9 @@ None.
 
 None.
 
-### Wiring
-
-None.
-
 ## Initialization
 
-None beyond the EMT initialization contract.
+None.
 
 ## Monitors
 

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

@@ -18,7 +18,7 @@ Define the phase- and conductor-index sets
 ```math
 \mathcal{N} = \{1,\ldots,N\},
 \qquad
-\mathcal{K} = \{1,\ldots,K\}.
+\mathcal{K} = \{1,\ldots,K\}
 ```
 
 Symbol | Units | JSON | Description | Note
@@ -73,7 +73,7 @@ uniform line, so
 ```math
 \mathbf{Y}_1^{\mathrm{c}}(s)=\mathbf{Y}_2^{\mathrm{c}}(s),
 \qquad
-\mathbf{H}_{12}(s)=\mathbf{H}_{21}(s).
+\mathbf{H}_{12}(s)=\mathbf{H}_{21}(s)
 ```
 
 The two terminal-admittance instances maintain independent states, and the two
@@ -137,8 +137,6 @@ None.
 
 #### Algebraic
 
-The residuals use the signals defined under Submodel Wiring.
-
 ```math
 \begin{aligned}
 0 &= -\mathbf{i}_1^\mathrm{ref}
@@ -163,9 +161,7 @@ The residuals use the signals defined under Submodel Wiring.
 
 ## Initialization
 
-The characteristic-admittance and propagation submodels initialize according
-to their own specifications. There is no additional line-level initialization
-procedure.
+Initialize the characteristic-admittance and propagation submodels.
 
 ## Monitors
 
@@ -175,45 +171,3 @@ Monitor | Units | Description | Note
 `i_c2` | [A] | Characteristic-admittance current at terminal 2 | $\mathbf{i}_2^\mathrm{c} \in \mathbb{R}^K$
 `i_inc1` | [A] | Incident current at terminal 1 | $\mathbf{i}_1^\mathrm{inc} \in \mathbb{R}^K$
 `i_inc2` | [A] | Incident current at terminal 2 | $\mathbf{i}_2^\mathrm{inc} \in \mathbb{R}^K$
-
-## Development
-
-The initial three-phase formulation takes $N=K=3$ and
-$\mathbf{P}_\phi=\mathbf{I}_3$.
-
-```math
-\begin{aligned}
-0 &= -\mathbf{i}_1^\mathrm{ref}
-  + 2\mathbf{i}_1^\mathrm{c}
-  - \mathbf{i}_1^\mathrm{inc} \\
-0 &= -\mathbf{i}_2^\mathrm{ref}
-  + 2\mathbf{i}_2^\mathrm{c}
-  - \mathbf{i}_2^\mathrm{inc}
-\end{aligned}
-```
-
-the external equations reduce to
-
-```math
-\begin{aligned}
-\mathbf{i}_1
-  &\leftarrow \mathbf{i}_1^\mathrm{inc}-\mathbf{i}_1^\mathrm{c} \\
-\mathbf{i}_2
-  &\leftarrow \mathbf{i}_2^\mathrm{inc}-\mathbf{i}_2^\mathrm{c}
-\end{aligned}
-```
-
-and the submodel wiring reduces to
-
-```math
-\begin{aligned}
-\mathbf{i}_1^\mathrm{c}
-  &\leftarrow \mathbf{y}_1^\mathrm{c}[\mathbf{v}_1] \\
-\mathbf{i}_2^\mathrm{c}
-  &\leftarrow \mathbf{y}_2^\mathrm{c}[\mathbf{v}_2] \\
-\mathbf{i}_1^\mathrm{inc}
-  &\leftarrow \mathbf{h}_{21}[\mathbf{i}_2^\mathrm{ref}] \\
-\mathbf{i}_2^\mathrm{inc}
-  &\leftarrow \mathbf{h}_{12}[\mathbf{i}_1^\mathrm{ref}]
-\end{aligned}
-```

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

@@ -20,7 +20,7 @@ Define the phase- and conductor-index sets
 ```math
 \mathcal{N} = \{1,\ldots,N\},
 \qquad
-\mathcal{K} = \{1,\ldots,K\}.
+\mathcal{K} = \{1,\ldots,K\}
 ```
 
 Symbol | Units | JSON | Description | Note
@@ -79,6 +79,10 @@ independent states.
 \mathrm{rank}(\mathbf{E}^{\mathbf{z}}) = K
 ```
 
+### Submodel Wiring
+
+None.
+
 ## Model Variables
 
 ### Internal Variables
@@ -124,10 +128,10 @@ None.
 
 ```math
 \begin{aligned}
-0 &= \Delta x\,\mathbf{y}_2[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2]
-  + 2\mathbf{i}_2^\mathrm{sh} \\
 0 &= \Delta x\,\mathbf{y}_1[\mathbf{P}_\phi^\mathsf T\mathbf{v}_1]
-  + 2\mathbf{i}_1^\mathrm{sh}
+  + 2\mathbf{i}_1^\mathrm{sh} \\
+0 &= \Delta x\,\mathbf{y}_2[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2]
+  + 2\mathbf{i}_2^\mathrm{sh}
 \end{aligned}
 ```
 
@@ -136,21 +140,21 @@ None.
 ```math
 \begin{aligned}
 \mathbf{i}_1 &\leftarrow
-  \mathbf{P}_\phi\left(
+  \mathbf{P}_\phi(
     \mathbf{i}_1^\mathrm{sh}
     - \mathbf{i}_{12}
-  \right) \\
+  ) \\
 \mathbf{i}_2 &\leftarrow
-  \mathbf{P}_\phi\left(
+  \mathbf{P}_\phi(
     \mathbf{i}_2^\mathrm{sh}
     + \mathbf{i}_{12}
-  \right)
+  )
 \end{aligned}
 ```
 
 ## Initialization
 
-None beyond the EMT initialization contract.
+None.
 
 ## Monitors
 
@@ -159,40 +163,3 @@ Monitor | Units | Description | Note
 `i12` | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^K$
 `i_sh1` | [A] | Shunt current at terminal 1 | $\mathbf{i}_1^\mathrm{sh} \in \mathbb{R}^K$
 `i_sh2` | [A] | Shunt current at terminal 2 | $\mathbf{i}_2^\mathrm{sh} \in \mathbb{R}^K$
-
-## Development
-
-The initial three-phase formulation is a subset of the generalized formulation
-above.
-
-### Derived Parameters
-
-```math
-\begin{aligned}
-\mathbf{R} &= \Delta x\,\mathbf{R}' \\
-\mathbf{L} &= \Delta x\,\mathbf{L}' \\
-\mathbf{G} &= \Delta x\,\mathbf{G}' \\
-\mathbf{C} &= \Delta x\,\mathbf{C}'
-\end{aligned}
-```
-
-### Differential Equations
-
-```math
-0 = \mathbf{R}\mathbf{i}_{12}
-  + \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}_{12}}{\mathrm{d}t}
-  + \mathbf{v}_2-\mathbf{v}_1
-```
-
-### Algebraic Equations
-
-```math
-\begin{aligned}
-0 &= \mathbf{G}\mathbf{v}_2
-  + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_2}{\mathrm{d}t}
-  + 2\mathbf{i}_2^\mathrm{sh} \\
-0 &= \mathbf{G}\mathbf{v}_1
-  + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_1}{\mathrm{d}t}
-  + 2\mathbf{i}_1^\mathrm{sh}
-\end{aligned}
-```

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

@@ -46,9 +46,13 @@ algebraic when $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$.
 ```math
 \mathbf{E}^{\mathbf{z}}=\mathbf{0}
 \qquad \text{or} \qquad
-\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N.
+\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N
 ```
 
+### Submodel Wiring
+
+None.
+
 ## Model Variables
 
 ### Internal Variables
@@ -95,29 +99,18 @@ For $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$, the same residual is algebraic.
 
 ### External Equations
 
+The load supplies input $d$ of the [bus current balance](../../../Bus/README.md#model-equations):
+
 ```math
-\mathbf{f} \leftarrow \mathbf{i}
+\mathbf{i}_d \leftarrow \mathbf{i}
 ```
 
 ## Initialization
 
-None beyond the EMT initialization contract.
+None.
 
 ## Monitors
 
 Monitor | Units | Description | Note
 ------- | ----- | ----------- | ----
 `i` | [A] | Load current injection | $\mathbf{i} \in \mathbb{R}^N$
-
-## Development
-
-The initial three-phase formulation uses resistance and inductance matrices.
-
-### Differential Equations
-
-```math
-0 =
-\mathbf{R}\mathbf{i}
-+ \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t}
-+ \mathbf{v}
-```

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

@@ -34,7 +34,7 @@ N &\in \mathbb{Z}_{>0} \\
 Define the phase-index set
 
 ```math
-\mathcal{N} = \{1,\ldots,N\}.
+\mathcal{N} = \{1,\ldots,N\}
 ```
 
 ## Model Ports
@@ -54,6 +54,10 @@ $\mathbf{y}$ | Terminal admittance | [VectorFit](../../../Operators/Rational/Vec
 
 None.
 
+### Submodel Wiring
+
+None.
+
 ## Model Variables
 
 ### Internal Variables
@@ -103,26 +107,11 @@ None.
 
 ## Initialization
 
-None beyond the EMT initialization contract.
+None.
 
 ## Monitors
 
 Monitor | Units | Description | Note
 ------- | ----- | ----------- | ----
 `e` | [V] | Source voltage | $\mathbf{e} \in \mathbb{R}^N$
 `i` | [A] | Source current injection | $\mathbf{i} \in \mathbb{R}^N$
-
-## Development
-
-The initial three-phase formulation realizes the terminal admittance as a
-series resistance and inductance, with $\mathbf{i}$ as a differential variable.
-
-### Differential Equations
-
-```math
-0 =
-\mathbf{R}_\mathrm{s}\mathbf{i}
-+ \mathbf{L}_\mathrm{s}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t}
-+ \mathbf{v}
-- \mathbf{e}
-```

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

@@ -46,6 +46,10 @@ None.
 
 None.
 
+### Submodel Wiring
+
+None.
+
 ## Model Variables
 
 ### Internal Variables
@@ -85,8 +89,8 @@ None.
 
 ```math
 \begin{cases}
-\mathbf{i}_{12} = \mathbf{0}, & \text{open}, \\
-\mathbf{v}_2-\mathbf{v}_1 = \mathbf{0}, & \text{closed}.
+\mathbf{i}_{12} = \mathbf{0}, & \text{open}\\
+\mathbf{v}_2-\mathbf{v}_1 = \mathbf{0}, & \text{closed}
 \end{cases}
 ```
 
@@ -95,7 +99,7 @@ None.
 ```math
 \begin{aligned}
 \mathbf{i}_1 &\leftarrow -\mathbf{i}_{12} \\
-\mathbf{i}_2 &\leftarrow \mathbf{i}_{12}.
+\mathbf{i}_2 &\leftarrow \mathbf{i}_{12}
 \end{aligned}
 ```