polish bus formulation [skip ci]

Author: lukelowry

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

@@ -1,19 +1,25 @@
 # Bus Model
 
-`Bus` represents a three-phase bus in instantaneous abc coordinates. The
+`Bus` represents an $N$-phase bus in instantaneous phase coordinates. The
 bus voltages are differential variables, and the model equations enforce
-three-phase current balance at the bus.
+current balance at the bus.
 
 ## Model Parameters
 
 Symbol | Units | JSON | Description | Note
 ------ | ----- | ---- | ----------- | ----
-$N$ | [-] | `N` | Number of connected-device ports | Required, positive integer
+$M$ | [-] | `M` | Number of connected-device ports | Required, positive integer
+$N$ | [-] | `N` | Number of phases | Required, positive integer
+$\mathbf{v}_0$ | [V] | `v0` | Initial bus voltage vector | $\mathbf{v}_0 \in \mathbb{R}^N$
 
 ### Parameter Validation
 
 ```math
-N > 0
+\begin{aligned}
+M &> 0 \\
+N &> 0 \\
+\mathbf{v}_0 &\in \mathbb{R}^N
+\end{aligned}
 ```
 
 ### Model Derived Parameters
@@ -28,7 +34,7 @@ None.
 
 Symbol | Units | Description | Note
 ------ | ----- | ----------- | ----
-$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} = [v_a, v_b, v_c]^T \in \mathbb{R}^3$
+$\mathbf{v}$ | [V] | Bus voltage vector | $\mathbf{v} \in \mathbb{R}^N$
 
 #### Algebraic
 
@@ -46,50 +52,39 @@ None.
 
 ## Model Ports
 
-Symbol | Type | Units | Description | Note
------- | ---- | ----- | ----------- | ----
-$\mathbf{i}^{\mathrm{inj}}_e$ | Input | [A] | Current injection from connected device $e$ | $e=1,\ldots,N$
+Symbol | Port | Type | Units | Description | Note
+------ | ---- | ---- | ----- | ----------- | ----
+$\mathbf{i}^{\mathrm{inj}}_m$ | `i` | Input | [A] | Current injection from connected device $m$ | $m=1,\ldots,M$, $\mathbf{i}^{\mathrm{inj}}_m \in \mathbb{R}^N$
 
 ## Model Equations
 
 ### Differential Equations
 
 ```math
 \begin{aligned}
-0 &= \sum_{e=1}^{N} \mathbf{i}^{\mathrm{inj}}_e
+0 &= \sum_{m=1}^{M} \mathbf{i}^{\mathrm{inj}}_m
 \end{aligned}
 ```
 
-Each $\mathbf{i}^{\mathrm{inj}}_e$ may depend on the bus voltage and bus voltage derivative.
+Each $\mathbf{i}^{\mathrm{inj}}_m$ may depend on the bus voltage and bus voltage derivative.
 
 ### Algebraic Equations
 
 None.
 
 ## Initialization
 
-For a balanced three-phase initialization derived from phasor voltage
-$V = |V| \angle \phi$ and nominal angular frequency $\omega_0 = 2 \pi f_0$:
+The initial bus voltage is given by the parameter vector $\mathbf{v}_0$:
 
 ```math
-\begin{aligned}
-\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
-\begin{bmatrix}
-  \sin(\phi) \\
-  \sin(\phi - \tfrac{2\pi}{3}) \\
-  \sin(\phi + \tfrac{2\pi}{3})
-\end{bmatrix}
-\end{aligned}
+\mathbf{v}(0)=\mathbf{v}_0
 ```
 
+Only $\mathbf{v}(0)$ is initialized. The solver computes
+$\dot{\mathbf{v}}(0)$ from the differential residual.
+
 ## Monitors
 
 Monitor | Units | Description | Note
 ------- | ----- | ----------- | ----
-`v` | [V] | Bus voltage | $\mathbf{v} \in \mathbb{R}^3$
+`v` | [V] | Bus voltage | $\mathbf{v} \in \mathbb{R}^N$