diff --git a/src/Model/PhasorDynamics/Branch/README.md b/src/Model/PhasorDynamics/Branch/README.md
index 1dd2a89f8..cddc5fc8c 100644
--- a/src/Model/PhasorDynamics/Branch/README.md
+++ b/src/Model/PhasorDynamics/Branch/README.md
@@ -1,11 +1,9 @@
-# Branch Model
+# Transmission Line Branch Model
Transmission lines and different types of transformers (traditional, Load
Tap-Changing transformers (LTC) and Phase Angle Regulators (PARs)) can be
modeled with a common branch model.
-## Transmission Line Model
-
The most common circuit that is used to represent the transmission line model
is $`\pi`$ circuit as shown in Figure 1. The positive flow direction is into
buses. Commonly used convention is to define positive direction to be from
@@ -18,75 +16,74 @@ provides more flexibility for modeling.
Figure 1: Transmission line $`\pi`$ equivalent circuit
-Here
-``` math
-Z = R + jX
-```
-and
+## Model Parameters
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$R$ | [p.u.] | Branch series resistance |
+$X$ | [p.u.] | Branch series reactance |
+$G$ | [p.u.] | Branch shunt conductance |
+$B$ | [p.u.] | Branch shunt susceptance |
+
+### Model Derived Parameters
+Note the difference between little-g and big-G, little-b, big-B in these equations.
``` math
-Y = G + jB,
-```
-where $`R`$ is line series resistance, $`X`$ is line series reactance, $`B`$ is
-line shunt charging, and $`G`$ is line shunt conductance. As can be seen from
-Figure 1 total $`B`$ and $`G`$ are separated between two buses. The current
-entering bus 1 can be obtained from Kirchhoff's current law as
-```math
-I_1 = y(V_2 - V_1) - \frac{Y}{2} V_1,
-```
-where $`V_1`$ and $`V_2`$ are respective bus voltages and
-```math
-y = \frac{1}{Z} = \frac{R}{R^2+X^2} + j\frac{-X}{R^2+X^2} = g + jb.
-```
-Similarly, current entering bus 2 is given as
-```math
-I_2 = y(V_1 - V_2) + \frac{Y}{2} V_2.
-```
-These equations can be written in a compact form as:
-```math
-\begin{bmatrix}
-I_{1}\\
-I_{2}
-\end{bmatrix}
-= \mathbf{Y}
-\begin{bmatrix}
-V_{1}\\
-V_{2}
-\end{bmatrix}
-```
-where:
-```math
-\mathbf{Y}_{TL}=\begin{bmatrix}
--(g + jb) - \dfrac{G+jB}{2} & g + jb \\
- g + jb & -(g + jb) - \dfrac{G+jB}{2}
-\end{bmatrix}
+\begin{aligned}
+ g &=\dfrac{R}{R^2 + X^2} \\
+ b &= -\dfrac{X}{R^2 + X^2}\\
+\end{aligned}
```
-### Branch contributions to residuals at adjacent buses
-After some algebra, one obtains expressions for real and imaginary components
-for the currents entering adjacent buses:
-```math
-I_{r1} = -\left(g + \frac{G}{2}\right) V_{r1} + \left(b + \frac{B}{2} \right) V_{i1}
- + g V_{r2} - b V_{i2}
-```
+## Model Variables
-```math
-I_{i1} = -\left(b + \frac{B}{2} \right) V_{r1} - \left(g + \frac{G}{2}\right) V_{i1}
- + b V_{r2} + g V_{i2}
-```
+### Internal Variables
-```math
-I_{r2} = g V_{r1} - b V_{i1}
- - \left(g + \frac{G}{2}\right) V_{r2} + \left(b + \frac{B}{2} \right) V_{i2}
-```
+#### Differential
+None.
-```math
-I_{i2} = b V_{r1} + g V_{i1}
- - \left(b + \frac{B}{2} \right) V_{r2} - \left(g + \frac{G}{2}\right) V_{i2}
+#### Algebraic
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$I_{r1}$ | [p.u.] | Terminal current, real component, bus 1 | Read by bus
+$I_{i1}$ | [p.u.] | Terminal current, imaginary component, bus 1 | Read by bus
+$I_{r2}$ | [p.u.] | Terminal current, real component, bus 2 | Read by bus
+$I_{i2}$ | [p.u.] | Terminal current, imaginary component, bus 2 | Read by bus
+
+
+### External Variables
+
+#### Differential
+None.
+
+#### Algebraic
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$V_{r1}$ | [p.u.] | Terminal voltage, real component, bus 1 | owned by bus object
+$V_{i1}$ | [p.u.] | Terminal voltage, imaginary component, bus 1 | owned by bus object
+$V_{r2}$ | [p.u.] | Terminal voltage, real component, bus 2 | owned by bus object
+$V_{i2}$ | [p.u.] | Terminal voltage, imaginary component, bus 2 | owned by bus object
+
+
+## Model Equations
+
+### Differential Equations
+None.
+
+### Algebraic Equations
+``` math
+\begin{aligned}
+ 0 &= - I_{r1} -\left(g + \dfrac{G}{2}\right) V_{r1} + \left(b + \dfrac{B}{2}\right) V_{i1} + g V_{r2} - b V_{i2}\\
+ 0 &= I_{i1} - \left(b + \dfrac{B}{2}\right) V_{r1} - \left(g + \dfrac{G}{2}\right) V_{i1} + b V_{r2} + g V_{i2}\\
+ 0 &= I_{r2} + g V_{r1} - b V_{i1} - \left(g + \dfrac{G}{2}\right) V_{r2} + \left(b + \dfrac{B}{2}\right) V_{i2}\\
+ 0 &= I_{i2} + b V_{r1} + g V_{i1} - \left(b + \dfrac{B}{2}\right) V_{r2} - \left(g + \dfrac{G}{2}\right) V_{i2}
+\end{aligned}
```
-## Transformer Branch Model
+
+# Transformer Branch Model
**Note: Transformer model not yet implemented**
diff --git a/src/Model/PhasorDynamics/BusFault/README.md b/src/Model/PhasorDynamics/BusFault/README.md
new file mode 100644
index 000000000..cc10b2fc3
--- /dev/null
+++ b/src/Model/PhasorDynamics/BusFault/README.md
@@ -0,0 +1,60 @@
+# Bus Fault
+
+Represents an impedance fault at a bus. This device can exist in two states, on or off, controlled by the user. Following a state change, generally the solver needs to be reset as this is a discrete event.
+
+## 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.
+
+### Model Derived Parameters
+``` math
+\begin{aligned}
+ G &=\dfrac{R}{R^2+ X^2} \\
+ B &= -\dfrac{X}{R^2 + X^2}\\
+\end{aligned}
+```
+
+
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+None.
+
+#### Algebraic
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$I_r$ | [p.u.] | Terminal current, real component | Read by bus
+$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
+$V_i$ | [p.u.] | Terminal voltage, imaginary component | owned by bus object
+
+
+## Model Equations
+
+### Differential Equations
+None.
+
+### Algebraic Equations
+``` 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}
+```
diff --git a/src/Model/PhasorDynamics/Load/README.md b/src/Model/PhasorDynamics/Load/README.md
index 065dd024d..5d90cb310 100644
--- a/src/Model/PhasorDynamics/Load/README.md
+++ b/src/Model/PhasorDynamics/Load/README.md
@@ -2,27 +2,62 @@
Load modeling is one of the more complex aspects of power system dynamics.
The simplest model, which is used for this challenge problem, is to model
-the load as a complex shunt impedance with the impedance given by:
+the load as a complex shunt impedance $$ R + jX $$.
+
+
+## Model Parameters
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$R$ | [p.u.] | Load resistance |
+$X$ | [p.u.] | Load reactance |
+
+
+### Model Derived Parameters
``` math
-Z = R + jX
-```
-where $`R`$ is the load resistance, $`X`$ is the load reactance. The current
-drawn by the load is then obtained as
-```math
-I_{\mathrm{load}} = \frac{V_{\mathrm{bus}}}{Z},
+\begin{aligned}
+ G &=\dfrac{R}{R^2 + X^2} \\
+ B &= -\dfrac{X}{R^2 + X^2}\\
+\end{aligned}
```
-where $`V_{bus}`$ is the voltage on the bus to which the load is connected.
-After some algebra, one obtains expressions for real and imaginary components
-for the currents entering the bus:
-```math
-I_{r} = -g V_{r} + b V_{i}
-```
-```math
-I_{i} = - b V_{r} - g V_{i}
-```
-where
-```math
-g = \frac{R}{R^2+X^2} ~~~\mathrm{and}~~~ b = \frac{-X}{R^2+X^2}.
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+None.
+
+#### Algebraic
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$I_r$ | [p.u.] | Terminal current, real component | Read by bus
+$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
+$V_i$ | [p.u.] | Terminal voltage, imaginary component | owned by bus object
+
+
+## Model Equations
+
+### Differential Equations
+None.
+
+### Algebraic Equations
+``` math
+\begin{aligned}
+0 &= I_{r} +G V_{r} - B V_{i} \\
+0 &= I_{i} +B V_{r} + G V_{i}
+\end{aligned}
```
diff --git a/src/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md b/src/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md
index 38be4af65..ab2591338 100644
--- a/src/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md
+++ b/src/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md
@@ -1,5 +1,13 @@
# GENROU
+This synchronous machine model is 6th order and is specifically designed for round rotor machines. It is a standard model used in phasor-domain industry stability studies.
+See the [General Synchronous Machine Model](../README.md) for general synchronous machine information.
+
+Notes:
+- $X''_{q}=X''_{d}$ (round rotor assumptions)
+- $X''_{d}$ does not saturate
+- Same relative amount of saturation occurs on both $d$ and $q$ axis
+
## Block Diagram
@@ -8,49 +16,29 @@
[PowerWorld](https://www.powerworld.com/WebHelp/)
-## Simplifications
-The GENROU model is a variation of the
-[General Synchronous Machine Model](../README.md)
-- $`X''_{q}=X''_{d}`$
-- $`X''_{d}`$ does not saturate
-- Same relative amount of saturation occurs on both $`d`$ and $`q`$ axis
-
-## Nomenclature
-### Algebraic Variables
-- $V_d$, $V_q$ Machine Internal Voltage on the machine d-q reference frame
-- $I_d$, $I_q$ Terminal currents on the machine d-q reference frame
-- $V_r$, $V_i$ Terminal voltages on the network reference frame
-- $I_r$, $I_i$ Terminal currents on the network reference frame
-- $\psi''_q$, $\psi''_d$, $\psi''$ Machine Total Subtransient Flux
-- $T_{elec}$ Electrical Torque
-- $P_{mech}$ Mechanical power from the prime mover
-- $E_{fd}$ Field winding voltage from the excitation system
-- $k_{sat}$ Saturation Coefficient
-### Differential Variables
-- $\delta$ Machine Internal Angle
-- $\omega$ Machine Relative Speed
-- $\psi'_d$, $\psi'_q$, $E'_d$, $E'_q$ Machine Internal Flux Values
-### Parameters
-- $\omega_{0}$ - Nominal Frequnecy ($2\pi 60$)
-- $H$ - Intertia constant, sec (3)
-- $D$ - Damping factor, pu (0)
-- $R_{a}$ - Stator winding resistance, pu (0)
-- $X_{\ell}$ - Stator leakage reactance, pu (0.15)
-- $X_{d}$ - Direct axis synchronous reactance, (2.1)
-- $X'_{d}$ - Direct axis transient reactance, (0.2)
-- $X''_{d}$ - Direct axis sub-transient reactance, (0.18)
-- $X_{q}$ - Quadrature axis synchronous reactance, (0.5)
-- $X'_{q}$ - Quadrature axis transient reactance, (0.47619)
-- $X''_{q}$ - Quadrature axis sub-transient reactance, (0.18)
-- $T'_{d0}$ - Open circuit direct axis transient time const., (7)
-- $T''_{d0}$ - Open circuit direct axis sub-transient time const., (0.04)
-- $T'_{q0}$ - Open circuit quadrature axis transient time const., (0.75)
-- $T''_{q0}$ - Open circuit quadrature axis sub-transient time const., (0.05)
-- $S_{10}$ - Saturation factor at 1.0 pu flux, (0)
-- $S_{12}$ - Saturation factor at 1.2 pu flux, (0)
-
-### Auxillary Parameters
-Transformed parameters used during implementation and for readability.
+## Model Parameters
+
+Symbol | Units | Description | Typical Value | Note
+------------|---------|---------------------------------|---------------| ------
+$\omega_0$ | [rad/s] | synchronous frequency | $2\pi \cdot 60$
+$H$ | [s] | rotor inertia | 3
+$D$ | [p.u.] | damping coefficient | 0
+$R_a$ | [p.u.] | winding resistance | 0
+$X_{\ell}$ | [p.u.] | Stator leakage reactance | 0.15 |
+$X_{d}$ | [p.u.] | Direct axis synchronous reactance | 2.1 |
+$X'_{d}$ | [p.u.] | Direct axis transient reactance | 0.2 |
+$X''_{d}$ | [p.u.] | Direct axis sub-transient reactance | 0.18 |
+$X_{q}$ | [p.u.] | Quadrature axis synchronous reactance | 0.5 |
+$X'_{q}$ | [p.u.] | Quadrature axis transient reactance | 0.5 |
+$X''_{q}$ | [p.u.] | Quadrature axis sub-transient reactance | 0.18 |
+$T'_{d0}$ | [s] | Open circuit direct axis transient time const. | 7 |
+$T''_{d0}$ | [s] | Open circuit direct axis sub-transient time const. | 0.04 |
+$T'_{q0}$ | [s] | Open circuit quadrature axis transient time const. | 0.75 |
+$T''_{q0}$ | [s] | Open circuit quadrature axis sub-transient time const. | 0.05 |
+$S_{10}$ | [p.u.] | Saturation factor at 1.0 pu flux | 0 |
+$S_{12}$ | [p.u.] | Saturation factor at 1.2 pu flux | 0 |
+
+### Model Derived Parameters
``` math
\begin{aligned}
G &=\dfrac{R_a}{R_a^2+(X''_q)^2}&
@@ -65,13 +53,56 @@ Transformed parameters used during implementation and for readability.
\end{aligned}
```
-## Equations
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$\delta$ | [rad] | Machine internal rotor angle |
+$\omega$ | [p.u.] | Machine speed | Optionally read by governor or stabilizer component
+$\psi'_d$ | [p.u.] | Direct axis subtransient flux |
+$\psi'_q$ | [p.u.] | Quadrature axis subtransient flux |
+$E'_d$ | [p.u.] | Direct axis transient flux |
+$E'_q$ | [p.u.] | Quadrature axis subtransient flux |
+
+#### Algebraic
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$V_d$ | [p.u.] | Machine internal voltage, d-axis |
+$V_q$ | [p.u.] | Machine internal voltage, q-axis |
+$I_d$ | [p.u.] | Terminal current, d-axis |
+$I_q$ | [p.u.] | Terminal current, q-axis |
+$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Read by bus and optionally by controllers
+$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Read by bus and optionally by controllers
+$\psi''_q$ | [p.u.] | Total q-axis subtransient flux
+$\psi''_d$ | [p.u.] | Total d-axis subtransient flux
+$\psi''$ | [p.u.] | Machine total subtransient flux
+$T_{e}$ | [p.u.] | Electrical torque
+$k_{sat}$ | [p.u.] | Saturation coefficient
+
+### External Variables
+
+#### Differential
+None.
+
+#### Algebraic
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$V_r$ | [p.u.] | Terminal voltage, real component on network reference frame | owned by bus object
+$V_i$ | [p.u.] | Terminal voltage, imaginary component on network reference frame | owned by bus object
+$P_{m}$ | [p.u.] | Mechanical power from the prime mover | Owned by governor, constant if no governor is connected to the machine
+$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by exciter, constant if no exciter is connected to the machine
+
+## Model Equations
### Differential Equations
``` math
\begin{aligned}
- \dot\delta &= \omega\cdot\omega_0 \\
- \dot\omega &= \dfrac{1}{2H}\left(\dfrac{P_{mech}-D\omega}{1+\omega}
+ \dot\delta &= (\omega-1)\cdot\omega_0 \\
+ \dot\omega &= \dfrac{1}{2H}\left(\dfrac{P_{mech}-D(\omega-1)}{\omega}
- T_{elec}\right)\\
\dot{\psi}'_{d} &= \dfrac{1}{T''_{d0}}(E'_{q}-\psi'_{d}-X_{d2}I_{d})\\
\dot{\psi}'_{q} &= \dfrac{1}{T''_{q0}}(E'_{d}-\psi'_{q}+X_{q2}I_{q})\\
@@ -90,64 +121,27 @@ Transformed parameters used during implementation and for readability.
```
### Algebraic Equations
-These algebraic equations define internal variables (7) and the algebraic
-Network Interface Equations (4)
-``` math
-\begin{aligned}
- \psi''_{q} &= -E'_{d}X_{q5} - \psi'_{q}X_{q4} \\
- \psi''_{d} &= +E'_{q}X_{d5} + \psi'_{d}X_{d4}\\
- \psi'' &= \sqrt{(\psi''_{d})^2+(\psi''_{q})^2} \\
- V_{d} &= -\psi''_{q}(1+\omega)\\
- V_{q} &= +\psi''_{d}(1+\omega)\\
- T_{elec} &= (\psi''_{d} - I_dX_d'')I_q-(\psi''_{q} - I_qX_d'')I_d \\
-\end{aligned}
-```
-
-#### Network Interface equations
-The network interface equations provide the algebraic relationship the network
- and internal reference frame.
+Note that for implementation purposes, some of these equations may be simplified into functions and the internal variables eliminated. Nevertheless, for modeling clarity and conformance to typical practice, the full equations are given here.
``` math
\begin{aligned}
- \begin{bmatrix}
- I_d \\ I_q
- \end{bmatrix}
- &=
- \begin{bmatrix}
- \sin \delta & -\cos\delta \\
- \cos\delta & \sin\delta
- \end{bmatrix}
- \begin{bmatrix}
- I_r \\ I_i
- \end{bmatrix}
- \\
- \begin{bmatrix}
- I_r \\ I_i
- \end{bmatrix}
- &=
- \begin{bmatrix}
- G & -B \\
- B & G
- \end{bmatrix}
- \left(
- \begin{bmatrix}
- \sin \delta & \cos\delta \\
- -\cos\delta & \sin\delta
- \end{bmatrix}
- \begin{bmatrix}
- V_d \\ V_q
- \end{bmatrix}
- -
- \begin{bmatrix}
- V_r \\V_i
- \end{bmatrix}
- \right)
+ 0 &= -\psi''_{q} -E'_{d}X_{q5} - \psi'_{q}X_{q4} \\
+ 0 &= -\psi''_{d} +E'_{q}X_{d5} + \psi'_{d}X_{d4}\\
+ 0 &= -\psi'' +\sqrt{(\psi''_{d})^2+(\psi''_{q})^2} \\
+ 0 &= -V_{d} -\psi''_{q}\omega\\
+ 0 &= -V_{q} +\psi''_{d}\omega\\
+ 0 &= -T_{elec} +(\psi''_{d} - I_dX_d'')I_q-(\psi''_{q} - I_qX_d'')I_d \\
+ 0 &= -k_{sat} + S_B (\psi''-S_A)^2 \\
+ 0 &= -I_d + I_r \sin(\delta) - I_i \cos(\delta) \\
+ 0 &= -I_q + I_r \cos(\delta) + I_i \sin(\delta) \\
+ 0 &= -I_r + G (V_d \sin(\delta) + V_q \cos(\delta) - V_r) - B (V_d \cos(\delta) + V_q \sin(\delta) - V_i) \\
+ 0 &= -I_i + B (V_d \sin(\delta) + V_q \cos(\delta) - V_r) + G (V_d \cos(\delta) + V_q \sin(\delta) - V_i)
\end{aligned}
```
## Initialization
### Without Saturation
-Pressume there is no saturation to simplify solution procedure for initial
+Presume there is no saturation to simplify solution procedure for initial
conditions.
Using the power-flow solution, we have explicit solutions for the following
@@ -156,7 +150,7 @@ from the network interface equations. The remaining are algebraically solved
from the steady-state initial conditions.
``` math
\begin{aligned}
-\omega &= 0 \\
+\omega &= 1 \\
\delta &= \text{arg} \left[V_r + jV_i + (R_a + jX_q) (I_r + jI_i)\right] \\
\psi^{''}_{d} &= V_q \\
\psi^{''}_{q} &= -V_d \\
@@ -176,7 +170,7 @@ from the steady-state initial conditions.
### With Saturation
It is important to point out that finding the initial value of $\delta$ for
the model without saturation direct method can be used. In case when saturation
-is considered some "claver" math is needed. Key insight for determining initial
+is considered some "clever" math is needed. Key insight for determining initial
$\delta$ is that the magnitude of the saturation depends upon the magnitude
of $\psi''$, which is independent of $\delta$.
diff --git a/src/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md b/src/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md
index c5c620710..92b6d5a24 100644
--- a/src/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md
+++ b/src/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md
@@ -1,7 +1,14 @@
# GENSAL
-> [!NOTE]
-> This has not yet been implemented
+This synchronous machine model is 5th order and is specifically designed for salient pole machines. It is a standard model used in phasor-domain industry stability studies.
+See the [General Synchronous Machine Model](../README.md) for general synchronous machine information.
+
+Notes:
+- $X''_{q}=X''_{d}$ (no subtransient saliency)
+- $X''_{d}$ does not saturate
+- Only d-axis affected by saturation
+- $X_{q}=X'_{q}$
+- $T'_{q0}$ is neglected
## Block Diagram
@@ -12,143 +19,109 @@
[PowerWorld](https://www.powerworld.com/WebHelp/)
-## Simplifications
-The GENSAL model is a variation of the
-[General Synchronous Machine Model](../README.md)
-- $`X''_{q}=X''_{d}`$
-- $`X''_{d}`$ does not saturate
-- Only d-axis affected by saturation
-- $`X_{q}=X'_{q}`$
-- $T'_{q0}$ is neglected
+## Model Parameters
-## Nomenclature
-### Algebraic Variables
-- $V_d$, $V_q$ Machine Internal Voltage on the machine d-q reference frame
-- $I_d$, $I_q$ Terminal currents on the machine d-q reference frame
-- $V_r$, $V_i$ Terminal voltages on the network reference frame
-- $I_r$, $I_i$ Terminal currents on the network reference frame
-- $\psi''_q$, $\psi''_d$, $\psi''$ Machine Total Subtransient Flux
-- $T_{elec}$ Electrical Torque
-- $P_{mech}$ Mechanical power from the prime mover
-- $E_{fd}$ Field winding voltage from the excitation system
-- $k_{sat}$ Saturation Coefficient
-### Differential Variables
-- $\delta$ Machine Internal Angle
-- $\omega$ Machine Relative Speed
-- $\psi'_d$, $\psi'_q$, $E'_d$, $E'_q$ Machine Internal Flux Values
-### Parameters
-- $\omega_{0}$ - Nominal Frequnecy ($2\pi 60$)
-- $H$ - Intertia constant, sec (3)
-- $D$ - Damping factor, pu (0)
-- $R_{a}$ - Stator winding resistance, pu (0)
-- $X_{\ell}$ - Stator leakage reactance, pu (0.15)
-- $X_{d}$ - Direct axis synchronous reactance, (2.1)
-- $X'_{d}$ - Direct axis transient reactance, (0.2)
-- $X''_{d}$ - Direct axis sub-transient reactance, (0.18)
-- $X_{q}$ - Quadrature axis synchronous reactance, (0.5)
-- $X'_{q}$ - Quadrature axis transient reactance, (0.47619)
-- $X''_{q}$ - Quadrature axis sub-transient reactance, (0.18)
-- $T'_{d0}$ - Open circuit direct axis transient time const., (7)
-- $T''_{d0}$ - Open circuit direct axis sub-transient time const., (0.04)
-- $T'_{q0}$ - Open circuit quadrature axis transient time const., (0.75)
-- $T''_{q0}$ - Open circuit quadrature axis sub-transient time const., (0.05)
-- $S_{10}$ - Saturation factor at 1.0 pu flux, (0)
-- $S_{12}$ - Saturation factor at 1.2 pu flux, (0)
-
-### Auxillary Parameters
-Transformed parameters used during implementation and for readability.
+Symbol | Units | Description | Typical Value | Note
+------------|---------|---------------------------------|---------------| ------
+$\omega_0$ | [rad/s] | synchronous frequency | $2\pi60$
+$H$ | [s] | rotor inertia | 3
+$D$ | [p.u.] | damping coefficient | 0
+$R_a$ | [p.u.] | winding resistance | 0
+$X_{\ell}$ | [p.u.] | Stator leakage reactance | 0.15 |
+$X_{d}$ | [p.u.] | Direct axis synchronous reactance | 2.1 |
+$X'_{d}$ | [p.u.] | Direct axis transient reactance | 0.2 |
+$X''_{d}$ | [p.u.] | Direct axis sub-transient reactance | 0.18 |
+$X_{q}$ | [p.u.] | Quadrature axis synchronous reactance | 0.5 |
+$T'_{d0}$ | [s] | Open circuit direct axis transient time const. | 7 |
+$T''_{d0}$ | [s] | Open circuit direct axis sub-transient time const. | 0.04 |
+$T''_{q0}$ | [s] | Open circuit quadrature axis sub-transient time const. | 0.05 |
+$S_{10}$ | [p.u.] | Saturation factor at 1.0 pu flux | 0 |
+$S_{12}$ | [p.u.] | Saturation factor at 1.2 pu flux | 0 |
+
+### Model Derived Parameters
``` math
\begin{aligned}
G &=\dfrac{R_a}{R_a^2+(X''_q)^2}&
B &= -\dfrac{X''_q}{R_a^2+(X''_q)^2}\\
S_A &= \dfrac{1.2\sqrt{S_{10}/S_{12}} +1}{\sqrt{S_{10}/S_{12}} +1} &
S_B &= \dfrac{1.2\sqrt{S_{10}/S_{12}} -1}{\sqrt{S_{10}/S_{12}} -1} \\
- X_{d1} &= X_d-X_d' & X_{q1} &= X_q-X_q' \\
- X_{d2} &= X_d'-X_\ell & X_{q2} &= X_q'-X_\ell\\
- X_{d3} &= (X_d'-X_d'')/X_{d2}^2 & X_{q3} &= (X_q'-X_q'')/X_{q2}^2 \\
- X_{d5} &= (X_d''-X_\ell)/X_{d2} & X_{q5} &= (X_q''-X_\ell)/X_{q2}\\
+ X_{d1} &= X_d-X_d' \\
+ X_{d2} &= X_d'-X_\ell & X_{q2} = X_q-X''_q \\
+ X_{d3} &= (X_d'-X_d'')/X_{d2}^2 \\
+ X_{d5} &= (X_d''-X_\ell)/X_{d2} \\
X_{qd} &= (X_q-X_\ell)/(X_d-X_\ell)
\end{aligned}
```
-## Equations
+## Model Variables
+
+### Internal Variables
+
+#### Differential
+
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$\delta$ | [rad] | Machine internal rotor angle |
+$\omega$ | [p.u.] | Machine speed | Optionally read by governor or stabilizer component
+$\psi'_d$ | [p.u.] | Direct axis subtransient flux |
+$\psi''_q$ | [p.u.] | Quadrature axis subtransient flux |
+$E'_q$ | [p.u.] | Quadrature axis subtransient flux |
+
+#### Algebraic
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$V_d$ | [p.u.] | Machine internal voltage, d-axis |
+$V_q$ | [p.u.] | Machine internal voltage, q-axis |
+$I_d$ | [p.u.] | Terminal current, d-axis |
+$I_q$ | [p.u.] | Terminal current, q-axis |
+$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Read by bus and optionally by controllers
+$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Read by bus and optionally by controllers
+$\psi''_d$ | [p.u.] | Total d-axis subtransient flux
+$T_{e}$ | [p.u.] | Electrical torque
+
+### External Variables
+
+#### Differential
+None.
+
+#### Algebraic
+Symbol | Units | Description | Note
+------------|---------|---------------------------------| ------
+$V_r$ | [p.u.] | Terminal voltage, real component on network reference frame | owned by bus object
+$V_i$ | [p.u.] | Terminal voltage, imaginary component on network reference frame | owned by bus object
+$P_{m}$ | [p.u.] | Mechanical power from the prime mover | Owned by governor, constant if no governor is connected to the machine
+$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by exciter, constant if no exciter is connected to the machine
+
+## Model Equations
### Differential Equations
``` math
\begin{aligned}
- \dot\delta &= \omega\cdot\omega_0 \\
- \dot\omega &= \dfrac{1}{2H}\left(\dfrac{P_{mech}-D\omega}{1+\omega}
+ \dot\delta &= (\omega-1)\cdot\omega_0 \\
+ \dot\omega &= \dfrac{1}{2H}\left(\dfrac{P_{mech}-D (\omega-1)}{\omega}
- T_{elec}\right)\\
\dot{\psi}'_{d} &= \dfrac{1}{T''_{d0}}(E'_{q}-\psi'_{d}-X_{d2}I_{d})\\
- \dot{\psi}'_{q} &= \dfrac{1}{T''_{q0}}(E'_{d}-\psi'_{q}+X_{q2}I_{q})\\
- \dot{E}'_{d} &= \dfrac{1}{T'_{q0}}
- \left( -E'_{d}+X_{q1}
- (I_{q}-X_{q3}(E'_{d}-\psi'_{q}+X_{q2}I_{q}))
- + X_{qd}\psi''_{q}k_{sat}
- \right) \\
+ \dot{\psi}''_{q} &= \dfrac{1}{T''_{q0}}(-\psi''_{q}-X_{q2}I_{q})\\
\dot{E}'_{q} &= \dfrac{1}{T'_{d0}}
\left(
E_{fd}-E'_{q}-X_{d1}
(I_{d}+X_{d3}(E'_{q}-\psi'_{d}-X_{d2}I_{d}))
- -\psi''_{d}k_{sat}
+ - S_B (E'_q-S_A)^2
\right)\\
\end{aligned}
```
### Algebraic Equations
-These algebraic equations define internal variables (7) and the algebraic
-Network Interface Equations (4)
-``` math
-\begin{aligned}
- \psi''_{q} &= -E'_{d}X_{q5} - \psi'_{q}X_{q4} \\
- \psi''_{d} &= +E'_{q}X_{d5} + \psi'_{d}X_{d4}\\
- \psi'' &= \sqrt{(\psi''_{d})^2+(\psi''_{q})^2} \\
- V_{d} &= -\psi''_{q}(1+\omega)\\
- V_{q} &= +\psi''_{d}(1+\omega)\\
- T_{elec} &= (\psi''_{d} - I_dX_d'')I_q-(\psi''_{q} - I_qX_d'')I_d \\
-\end{aligned}
-```
-
-#### Network Interface equations
-The network interface equations provide the algebraic relationship the
-network and internal reference frame.
+Note that for implementation purposes, some of these equations may be simplified into functions and the internal variables eliminated. Nevertheless, for modeling clarity and conformance to typical practice, the full equations are given here.
``` math
\begin{aligned}
- \begin{bmatrix}
- I_d \\ I_q
- \end{bmatrix}
- &=
- \begin{bmatrix}
- \sin \delta & -\cos\delta \\
- \cos\delta & \sin\delta
- \end{bmatrix}
-
- \begin{bmatrix}
- I_r \\ I_i
- \end{bmatrix}\\
-
- \begin{bmatrix}
- I_r \\ I_i
- \end{bmatrix}
- &=
-
- \begin{bmatrix}
- G & -B \\
- B & G
- \end{bmatrix}
-
- \left(
- \begin{bmatrix}
- \sin \delta & \cos\delta \\
- -\cos\delta & \sin\delta
- \end{bmatrix}
- \begin{bmatrix}
- V_d \\ V_q
- \end{bmatrix}
- -
- \begin{bmatrix}
- V_r \\V_i
- \end{bmatrix}
- \right)
+ 0 &= -V_{d} -\psi''_{q}\omega\\
+ 0 &= -V_{q} +\psi''_{d}\omega\\
+ 0 &= -I_d + I_r \sin(\delta) - I_i \cos(\delta) \\
+ 0 &= -I_q + I_r \cos(\delta) + I_i \sin(\delta) \\
+ 0 &= -I_r + G (V_d \sin(\delta) + V_q \cos(\delta) - V_r) - B (V_d \cos(\delta) + V_q \sin(\delta) - V_i) \\
+ 0 &= -I_i + B (V_d \sin(\delta) + V_q \cos(\delta) - V_r) + G (V_d \cos(\delta) + V_q \sin(\delta) - V_i) \\
+ 0 &= -\psi''_{d} +E'_{q}X_{d5} + \psi'_{d}X_{d4}\\
+ 0 &= -T_{e} +(\psi''_{d} - I_dX_d'')I_q-(\psi''_{q} - I_qX_d'')I_d
\end{aligned}
```