Model Math and Documentation Cleanup

GridKit/Model/EMT/Operators/Shift/Propagation/README.md

@@ -4,6 +4,13 @@ For input units $[u]$, `Propagation` is the $K$-channel current-form propagation
 operator used by `LineDistributed`. It applies a fitted input factor, one scalar
 delay per mode, and a fitted output factor while preserving the input units.
 
+```math
+\begin{aligned}
+\mathbf{H}(s)
+  &= \sum_{m=1}^M \mathbf{H}^\mathrm{mps}_m(s) e^{-s\tau_m}
+\end{aligned}
+```
+
 ## Block Diagram
 
 ![Propagation operator block diagram](../../../../../../docs/Figures/EMT/Propagation/diagram.png)
@@ -51,29 +58,6 @@ $\mathbf{g}_\mathrm{in}$ | Input factor | [VectorFit](../../Rational/VectorFit/R
 $\mathbf{d}$ | Modal delay bank | [Delay](../Delay/README.md) | History | `delays` | $\mathbb{R}^M$ | $\mathbb{R}^M$
 $\mathbf{g}_\mathrm{out}$ | Output factor | [VectorFit](../../Rational/VectorFit/README.md) | $KQ_{\mathbf{g}_\mathrm{out}}$ | `output` | $\mathbb{R}^M$ | $\mathbb{R}^K$
 
-The offline fitting targets and propagation factorization are
-
-```math
-\begin{aligned}
-\mathbf{G}^\mathrm{in}(s)
-  &\approx \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\
-\mathbf{G}^\mathrm{out}(s) &\approx \mathbf{T}_i(s) \\
-\mathbf{H}^\mathrm{mps}(s)
-  &= \mathrm{diag}(h_1^\mathrm{mps}(s),\ldots,h_M^\mathrm{mps}(s)) \\
-\mathbf{D}_{\boldsymbol{\tau}}(s)
-  &= \mathrm{diag}(\exp(-s\tau_1),\ldots,\exp(-s\tau_M)) \\
-\mathbf{H}(s)
-  &= \mathbf{T}_i(s)\mathbf{D}_{\boldsymbol{\tau}}(s)
-     \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\
-  &\approx \mathbf{G}^\mathrm{out}(s)\mathbf{D}_{\boldsymbol{\tau}}(s)
-     \mathbf{G}^\mathrm{in}(s)
-\end{aligned}
-```
-
-$\mathbf{H}^\mathrm{mps}$ is the diagonal modal minimum-phase-shift propagation
-function with the modal delays removed. The current modal transformation
-$\mathbf{T}_i$ maps modal currents to phase coordinates, and
-$\mathbf{T}_i^{-1}$ maps phase currents to modal coordinates.
 
 ### Submodel Validation
 

GridKit/Model/PhasorDynamics/Branch/README.md

@@ -28,7 +28,7 @@ $\theta$             | [rad]  | `phase` | Phase-shift angle
 
 ### Parameter Validation
 
-Invalid Branch parameter sets are rejected by the following checks:
+A valid Branch parameter set must satisfy the following conditions:
 
 ```math
 \begin{aligned}
@@ -111,6 +111,13 @@ The magnetizing and line shunts are added outside the transformation:
 
 For the equations below, write each entry as $Y_{mn}=G_{mn}+jB_{mn}$.
 
+## Model Ports
+
+Name   | Port | Init  | Description
+-------|------|-------|------------
+`bus1` | Bus  | Known | Required bus-1 terminal; the tapped side
+`bus2` | Bus  | Known | Required bus-2 terminal
+
 ## Model Variables
 
 ### Internal Variables
@@ -140,11 +147,17 @@ $V_{i2}$    | [p.u.]  | Terminal voltage, imaginary component, bus 2 | Owned by
 
 ## Model Equations
 
-### Differential Equations
+### Internal Equations
+
+#### Differential
+
+None.
+
+#### Algebraic
 
 None.
 
-### Algebraic Equations
+### External Equations
 
 The branch current relation is $0 = -\mathbf{I} + \mathbf{Y}\mathbf{V}$.
 
@@ -168,14 +181,14 @@ positive sign because branch current is oriented entering the bus.
 
 The Branch model has no internal state to initialize. During construction or
 parameter updates, the component computes $\mathbf{Y}$ from the current
-parameter values. Initial terminal current and power monitor values are
-evaluated from the connected bus voltages. Parameter verification rejects the
-invalid cases listed above.
+parameter values. Terminal current and power monitor values are evaluated
+from the connected bus voltages when read. Parameter verification enforces the
+conditions in [Parameter Validation](#parameter-validation).
 
-## Model Outputs
+## Monitors
 
-Output | Units  | Description                                  | Note
--------|--------|----------------------------------------------|------
+Monitor | Units  | Description                                  | Note
+--------|--------|----------------------------------------------|------
 `ir1`  | [p.u.] | Terminal current, real component, bus 1      | Oriented entering bus 1
 `ii1`  | [p.u.] | Terminal current, imaginary component, bus 1 | Oriented entering bus 1
 `im1`  | [p.u.] | Terminal current magnitude, bus 1            |

GridKit/Model/PhasorDynamics/Bus/README.md

@@ -1,4 +1,4 @@
-# Bus Model
+# Bus
 
 A bus is a point of interconnection of electrical devices. The bus component
 model also plays a key role in coupling system components. Each bus $k$ owns
@@ -10,7 +10,7 @@ them. Instead, each component connected to the bus adds its contribution to the
 residual. The bus initializes the residual to zero each time the numerical
 integrator requests residual evaluation.
 
-## Sign Convention
+## Notes
 
 Current entering the bus has positive sign, and current exiting the bus has
 negative sign.
@@ -22,9 +22,90 @@ balance instead of power balance.
 
 ## Model Parameters
 
-Buses are uniquely identified by their numeric bus ID. Each bus has an
-associated nominal voltage.
+Symbol            | Units | JSON | Description         | Note
+------------------|-------|------|---------------------|-------
+$V_\mathrm{base}$ | [kV]  | `kv` | Nominal bus voltage | Unused
 
-Symbol              | Units | JSON | Description
---------------------|-------|------|------------
-$V_\mathrm{base}$   | [kV]  | `kv` | Nominal bus voltage
+### Parameter Validation
+
+None.
+
+### Model Derived Parameters
+
+None.
+
+## Model Ports
+
+None.
+
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+Symbol | Units  | Description
+-------|--------|------------
+$V_r$  | [p.u.] | Bus voltage, real component
+$V_i$  | [p.u.] | Bus voltage, imaginary component
+
+### External Variables
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+None.
+
+## Model Equations
+
+### Internal Equations
+
+#### Differential
+
+None.
+
+#### Algebraic
+
+Let $\mathcal{E}$ denote the set of components connected to the bus.
+
+```math
+\begin{aligned}
+0 &= \sum_{e \in \mathcal{E}} I_{r,e} \\
+0 &= \sum_{e \in \mathcal{E}} I_{i,e}
+\end{aligned}
+```
+
+### External Equations
+
+None.
+
+## Initialization
+
+### Internal Initialization
+
+Bus initializes its algebraic voltage variables as
+
+```math
+\begin{aligned}
+V_r &\leftarrow \text{bus voltage, real component} \\
+V_i &\leftarrow \text{bus voltage, imaginary component}
+\end{aligned}
+```
+
+The derivative vector entries initialize to zero.
+
+## Monitors
+
+Monitor | Units  | Description                     | Note
+--------|--------|---------------------------------|-----
+`Vr`    | [p.u.] | Bus voltage, real component      |
+`Vi`    | [p.u.] | Bus voltage, imaginary component |
+`Vm`    | [p.u.] | Bus voltage magnitude            | $\sqrt{V_r^2+V_i^2}$
+`Va`    | [rad]  | Bus voltage angle                | $\operatorname{atan2}(V_i,V_r)$

GridKit/Model/PhasorDynamics/BusFault/README.md

@@ -4,11 +4,11 @@ Represents an impedance fault at a bus. This device can exist in two states, on
 
 ## Model Parameters
 
-Symbol   | Units      | Description                     | Note
----------|------------|---------------------------------|-------
-$R$      | [p.u.]     | Fault resistance                | 
-$X$      | [p.u.]     | Fault reactance                 | 
-$U$      | [unitless] | Binary status $$\in \{0, 1\}$$  | Set by user to put fault on or off.
+Symbol   | Units     | JSON     | Description                     | Note
+---------|-----------|----------|---------------------------------|-------
+$R$      | [p.u.]    | `R`      | Fault resistance                | 
+$X$      | [p.u.]    | `X`      | Fault reactance                 | 
+$U$      | [boolean] | `state0` | Initial fault status            | JSON boolean; `true` puts the fault on. Changed at run time through `setStatus()`.
 
 ### Model Derived Parameters
 ``` math
@@ -18,12 +18,19 @@ $U$      | [unitless] | Binary status $$\in \{0, 1\}$$  | Set by user to put fau
 \end{aligned}
 ```
 
+## Model Ports
+
+Name             | Port  | Init  | Description
+-----------------|-------|-------|------------
+`bus`            | Bus   | Known | Required bus where the fault is applied
+`control_signal` | Input | N/A   | Accepted by the parser but not read by the model; fault status is set through `state0` and `setStatus()`
 
 ## Model Variables
 
 ### Internal Variables
 
 #### Differential
+
 None.
 
 #### Algebraic
@@ -37,9 +44,11 @@ $I_i$       | [p.u.]  | Terminal current, imaginary component |  Read by bus
 ### External Variables
 
 #### Differential
+
 None.
 
 #### Algebraic
+
 Symbol      | Units   | Description                           | Note
 ------------|---------|---------------------------------------| ------
 $V_r$       | [p.u.]  | Terminal voltage, real component      | owned by bus object
@@ -48,13 +57,50 @@ $V_i$       | [p.u.]  | Terminal voltage, imaginary component | owned by bus obj
 
 ## Model Equations
 
-### Differential Equations
+### Internal Equations
+
+#### Differential
+
 None.
 
-### Algebraic Equations
+#### Algebraic
+
 ``` math
 \begin{aligned}
 0 &= -I_{r} + U (-G V_{r} + B V_{i}) \\
 0 &= -I_{i} + U (-B V_{r} - G V_{i})
 \end{aligned}
 ```
+
+### External Equations
+
+The fault currents are added to the connected bus residuals:
+
+```math
+\begin{aligned}
+I_r^{\mathrm{bus}} &\leftarrow I_r^{\mathrm{bus}} + I_r \\
+I_i^{\mathrm{bus}} &\leftarrow I_i^{\mathrm{bus}} + I_i.
+\end{aligned}
+```
+
+## Initialization
+
+For the initial fault status $U_0$, the algebraic fault currents are initialized
+from the connected-bus voltage:
+
+```math
+\begin{aligned}
+I_{r,0} &= U_0\left(-G V_{r,0}+B V_{i,0}\right) \\
+I_{i,0} &= U_0\left(-B V_{r,0}-G V_{i,0}\right).
+\end{aligned}
+```
+
+The derivative-vector entries are initialized to zero.
+
+## Monitors
+
+Monitor | Units    | Description                               | Note
+--------|----------|-------------------------------------------|-----
+`state` | [binary] | Fault status                              | `1` when on; `0` when off
+`ir`    | [p.u.]   | Fault-current real component              | Added to the connected-bus residual
+`ii`    | [p.u.]   | Fault-current imaginary component         | Added to the connected-bus residual