Update modeling documentation structure

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
 </div>
 
-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**
 

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}
+```

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}
 ```