EMT Enhanced Documentation

GridKit/Model/EMT/Bus/README.md

@@ -1,14 +1,40 @@
 # 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. The bus
+voltage is differential, and the model equations enforce current balance.
+$\mathcal{E}$ denotes the set of connected devices.
+
+> [!NOTE]
+> A template parameter will select whether $\mathbf{v}$ is a differential or
+> algebraic vector. This page documents the nondegenerate differential
+> formulation. Initial end-to-end support is three-phase, although the
+> formulation remains $N$-phase.
+
+## Block Diagram
+
+None.
 
 ## Model Parameters
 
+Symbol | Units | JSON | Description | Note
+------ | ----- | ---- | ----------- | ----
+$N$ | [-] | `N` | Number of phases | Required, positive integer
+
+### Parameter Validation
+
+```math
+N > 0
+```
+
+### Derived Parameters
+
+None.
+
+## Submodels
+
 None.
 
-## Model Derived Parameters
+### Submodel Validation
 
 None.
 
@@ -18,9 +44,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 +62,56 @@ None.
 
 None.
 
+## Model Ports
+
+Symbol | Type | Units | Description | Note
+------ | ---- | ----- | ----------- | ----
+$\mathbf{i}^{\mathrm{inj}}_e$ | Input | [A] | Current injection from connected device $e$ | $e \in \mathcal{E}$, $\mathbf{i}^{\mathrm{inj}}_e \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}^{\mathrm{inj}}_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.
 
+### Wiring
+
+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$,
+### Input Initialization
 
-``` 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}
+```math
+\begin{aligned}
+\mathbf{i}^{\mathrm{inj}}_e
+  &\leftarrow \text{connected-device current},
+     \quad e \in \mathcal{E}
+\end{aligned}
 ```
 
-and
+### Internal Initialization
 
-``` 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}
+Symbol | Units | JSON | Description | Note
+------ | ----- | ---- | ----------- | ----
+$\mathbf{v}_0$ | [V] | `init.v0` | Initial bus-voltage vector | Required, $\mathbf{v}_0 \in \mathbb{R}^N$
+
+```math
+\mathbf{v} \leftarrow \mathbf{v}_0
 ```
 
-## Model Outputs
+### Output Initialization
+
+None.
 
-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$