EMT Enhanced Documentation

CHANGELOG.md

@@ -72,6 +72,7 @@
 - Added new `Rosenbrock` integrator.
 - Clarified naming conventions for macros.
 - Added `dt_fixed`, `rel_tol`, and `abs_tol` options to phasor dynamics solver JSON files and renamed the `dt` option to `dt_monitor`.
+- Added EMT model and operator documentation.
 
 ## v0.1
 

GridKit/Model/EMT/Bus/README.md

@@ -1,14 +1,36 @@
 # Bus Model
 
-`Bus` represents a three-phase bus in instantaneous abc coordinates. The
-bus voltages are differential variables, and the model equations enforce
-three-phase current balance at the bus.
+`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.
+
+## Block Diagram
+
+![Bus model block diagram](../../../../docs/Figures/EMT/Bus/diagram.png)
+
+Figure 1: Bus model
 
 ## Model Parameters
 
+Symbol | Units | JSON | Description | Note
+------ | ----- | ---- | ----------- | ----
+$N$ | [-] | `N` | Number of phases | Required, positive integer
+
+### Parameter Validation
+
+```math
+N \in \mathbb{Z}_{>0}
+```
+
+### Derived Parameters
+
+None.
+
+## Submodels
+
 None.
 
-## Model Derived Parameters
+### Submodel Validation
 
 None.
 
@@ -18,9 +40,9 @@ None.
 
 #### Differential
 
-Symbol   | Units | Description        | Note
----------|-------|--------------------|--------------------------------
-$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
+Symbol | Units | Description | Note
+------ | ----- | ----------- | ----
+$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} \in \mathbb{R}^N$
 
 #### Algebraic
 
@@ -36,55 +58,35 @@ None.
 
 None.
 
+## Model Ports
+
+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{v}$ | `v` | Output | [V] | Bus voltage supplied to connected devices | $\mathbf{v} \in \mathbb{R}^N$
+
 ## Model Equations
 
 ### Differential Equations
 
-An explicit representation for $\dot{\mathbf{v}}$ is not used because
-the effective shunt admittances depend on connected components and are not
-known at the bus level. The implicit DAE solver operates directly on
-the accumulated KCL residual:
-
-``` math
-\begin{aligned}
-0 &= \sum_{e \in \mathcal{E}} \mathbf{i}^\text{inj}_e
-\end{aligned}
+```math
+0 = \sum_{e \in \mathcal{E}} \mathbf{i}_e
 ```
 
-where $\mathbf{i}^\text{inj}_e$ is the vector of phase-current injections
-of connected component $e$ into the bus, which are a function of the bus voltage and bus voltage derivative.
-
 ### Algebraic Equations
 
 None.
 
-## Initialization
-
-For a balanced three-phase initialization derived from the phasor voltage
-$V = |V| \angle \phi$ and nominal angular frequency $\omega_0 = 2 \pi f_0$,
+### Wiring
 
-``` math
-\mathbf{v}(0) = \sqrt{2}\,|V|
-\begin{bmatrix}
-  \cos(\phi) \\
-  \cos(\phi - \tfrac{2\pi}{3}) \\
-  \cos(\phi + \tfrac{2\pi}{3})
-\end{bmatrix}
-```
-
-and
+None.
 
-``` math
-\dot{\mathbf{v}}(0) = -\sqrt{2}\,|V|\,\omega_0
-\begin{bmatrix}
-  \sin(\phi) \\
-  \sin(\phi - \tfrac{2\pi}{3}) \\
-  \sin(\phi + \tfrac{2\pi}{3})
-\end{bmatrix}
-```
+## Initialization
 
-## Model Outputs
+None beyond the EMT initialization contract.
 
-Phase voltages $v_a$, $v_b$, and $v_c$ are monitorable model outputs.
+## Monitors
 
-Phase-voltage derivatives $\dot{v}_a$, $\dot{v}_b$, and $\dot{v}_c$ are also available as monitorable outputs.
+Monitor | Units | Description | Note
+------- | ----- | ----------- | ----
+`v` | [V] | Bus voltage | $\mathbf{v} \in \mathbb{R}^N$