Exciter Documentation

src/Model/PhasorDynamics/Exciter/EXDC1/README.md

@@ -0,0 +1,105 @@
+# **EXDC1**
+
+<div align="center">
+   <img align="center" src="../../../../../docs/Figures/EXDC1.JPG">
+
+  Figure 1: Exciter EXDC1 model. Figure courtesy of [PoweWorld](https://www.powerworld.com/WebHelp/).
+</div>
+
+## Nomenclature
+
+### Inputs
+- $V_{REF}$ - voltage reference set point
+- $E_{C}$ - output from the terminal voltage transducer
+- $V_{S}$ -  power system stabilizer output signal (if present)
+- $V_{UEL}$ and $V_{OEL}$ - limiters
+
+### Differential Variables
+- $V_{t}$ - terminal voltage (2 is sensed $V_{t}$)
+- $V_{B}$ - input to a voltage regulator (3)
+- $V_{R}$ - voltage regulator output also know as exciter field voltage (4)
+- $V_{F}$ - stabilizing feedback signal (5)
+### Parameters
+- $T_{R}$ - filter time constant, sec (0)
+- $K_{A}$ - voltage regulator gain (40)
+- $T_{A}$ - time constant, sec (0.1)
+- $T_{B}$ - lag time constant, sec (0)
+- $T_{C}$ - lead time constant, sec (0)
+- $V_{RMAX}$ - maximum control element output, pu (1)
+- $V_{RMIN}$ - minimum control element output, pu (-1)
+- $K_{E}$ - exciter field resistance line slope margine, pu (0.1)
+- $T_{E}$ - exciter time constant, sec (0.5)
+- $K_{F}$ - rate feedback gain, pu (0.05)
+- $T_{F1}$ - rate feedback time constant, sec (0.7)
+- $E1$ - field voltage value, 1 (2.8)
+- $SE1$ - saturation factor at E1, (3.7)
+- $E2$ - field voltage value, 2 (3.7)
+- $SE2$ - saturation factor at E2, (0.33)
+
+## Equations
+First block
+```math
+\dfrac{dV_{t}}{dt}=\dfrac{1}{T_{R}}(E_{C}-V_{t})
+```
+Second block
+```math
+\dfrac{dx_{1}}{dt}=\dfrac{1}{T_{B}}((V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})-V_{B})
+```
+```math
+V_{B}=x_{1}+\dfrac{T_{C}}{T_{B}}(V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})
+```
+Third block
+```math
+\dfrac{dV_{R}}{dt} = \begin{cases}
+   \dfrac{1}{T_{A}}(K_{A}V_{B}-V_{R}) &\text{if } V_{RMIN}<=V_{R}<= V_{RMAX}\\
+   0 &\text{if } V_{B}>0 \text{  and  } V_{R}>=V_{RMAX} &\text{ also then } V_{R}=V_{RMAX}\\
+   0 &\text{if } V_{B}<0 \text{  and  } V_{R}<=V_{RMIN} &\text{ also then } V_{R}=V_{RMIN}\\
+\end{cases}
+```
+Fourth block
+```math
+\dfrac{d\dfrac{E_{FD}}{\omega}}{dt}=\dfrac{1}{T_{E}}(V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega})
+```
+Feedback loop
+```math
+\dfrac{dx_{2}}{dt}=-\dfrac{V_{F}}{T_{F1}}
+```
+```math
+V_{F}=x_{2}+\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega}
+```
+Saturation is modeled using an alternative quadratic function, with the value of Se specified at two points :
+```math
+Sat(x) = \begin{cases}
+   \dfrac{B(x-A)^2}{x} &\text{if } x>A \\
+   0 &\text{if } x<=A
+\end{cases}
+```
+same as with the synchronous machines. There are two solutions, and one where $A<1$ should be chosen.
+
+## Initialization
+```math
+V_{t}=V_{t_{0}}
+```
+```math
+E_{C}=V_{t_{0}}
+```
+```math
+(V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})=V_{B}
+```
+```math
+V_{R}=V{R_{0}}
+```
+```math
+V_{B}=\dfrac{V{R_{0}}}{K_{A}}
+```
+```math
+\dfrac{E_{FD}}{\omega}=\dfrac{E_{FD_{0}}}{\omega}
+```
+```math
+V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega}=0
+```
+```math
+V_{F}=0
+```
+```math
+x_{2_{0}}=-\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega}

src/Model/PhasorDynamics/Exciter/IEEET1/README.md

@@ -0,0 +1,95 @@
+# **IEEE Type 1 Excitation System Model (IEEET1)**
+
+## Control Diagram
+
+Standard model of the IEEET1 Exciter.
+
+<div align="center">
+   <img align="center" src="../../../../../docs/Figures/PhasorDynamics_IEEET1_Diagram.png">
+
+
+  Figure 1: Exciter IEEET1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/)
+</div>
+
+## Nomenclature
+
+### Algebraic Variables
+- $V_{tr}$ - Terminal Voltage Error input to controller
+- $V_{F}$ - Feedback Voltage
+- $V_{E}$ - Excitation control voltage
+- $E_{fd}$ - Field winding voltage
+- $k_{sat}$ - Saturation variable
+
+These can be constants or external states
+- $E_{C}$ - Compensated machine terminal voltage magnitude
+- $V_{ref}$ - Referebce ternubak voltage
+- $V_{UEL}$ - Input from under excitation limiter
+- $V_{OEL}$ - Input from over excitation limiter
+- $V_{S}$ - Input from stabilizer controller
+- $\Delta \omega$ - Machine speed deviation from machine model
+
+### Differential Variables
+- $V_{ts}$ - Sensed terminal voltage
+- $V_{R}$ - Voltage regulator
+- $E_{fd}'$ - Field-current pre-speed multiplier
+- $V_{fx}$ - Exciter feedback internal state
+
+### Parameters
+- $T_R$ - Time constant for voltage sensing
+- $K_a, T_a$ - Coefficient and time constant for voltage regulation
+- $K_e, T_e$ - Coefficient and time constant for excitation system
+- $K_f, T_f$ - Coefficient and time constant for feedback
+- $V_{rmin}, V_{rmax}$ - Limits to voltage regulation
+- $E_1, S_{e1}, E_{2}, S_{e2}$ - Saturation Parameters
+- $I_{spdlm}$ - Speed Limit flag indicator
+
+## Equations
+
+
+### Algebraic Equations
+The algebraic equations of the exciter.
+```math
+\begin{aligned}
+   V_{tr} &= V_{ref} - V_{ts}+V_{UEL} + V_{OEL} + V_S - V_F\\
+    V_{f} &= \dfrac{E_{fd}' K_F}{T_F} - V_{fx}\\
+    E_{fd}&= \begin{cases}
+        E_{fd}'           &  \text{if } I_{spdlm}\\
+        (1+\Delta \omega)E_{fd}'  &  \text{else } \\
+   \end{cases}\\
+    k_{sat}&= \begin{cases}
+        S_B(E_{fd}' -S_A)^2        &  \text{if } E_{fd}' >S_A\\
+        0  &  \text{else } \\
+   \end{cases} \\
+    V_{E} &= k_{sat}\cdot E_{fd}' \\
+\end{aligned}
+```
+
+
+### Differential Equations
+The IEEET1 differential equations, as derived from the model diagram.
+```math
+\begin{aligned}
+   \dot{V}_{ts}   &= \dfrac{1}{T_R}(E_C-V_{ts}) \\
+   \dot{V}_{R}    &= 
+      \dfrac{1}{T_A}
+   \begin{cases}
+      -V_{R}+K_{a}V_{tr}
+         &  \text{if } V_R \in (V_{rmin}, V_{rmax})\\
+      0  
+         &  \text{else } \\
+   \end{cases}
+\end{aligned}
+```
+The domain of the state variable $V_{R}\in(V_{rmin}, V_{rmax})$ is enforced
+through the piece-wise definition above. This may need to be expressed as a
+smooth approximation (smooth indicator $\phi$) expressed generically as follows.
+```math
+\begin{aligned}
+   \dot{V}_{R}   
+            &= 
+            \phi(V_R)\cdot \dfrac{1}{T_A}
+            \left[
+               -V_{R}+K_{a}V_{tr}
+            \right] \\
+\end{aligned}
+```

src/Model/PhasorDynamics/Exciter/README.md

@@ -1,109 +1,16 @@
-# **Exciter**
+# **Exciter Models**
 
+> [!NOTE]  
+> No implementation yet.
 
-**Note: Exciter model not yet implemented**
 
-<div align="center">
-   <img align="center" src="../../../../docs/Figures/EXDC1.JPG">
-
-
-  Figure 1: Exciter EXDC1 model. Fifure courtesy of [PoweWorld](https://www.powerworld.com/WebHelp/).
-</div>
+## Introduction
 
-## Nomenclature
+An exciter generally models, regulates, and sustains
+device internal voltage.
 
-### Inputs
-- $`V_{REF}`$ - voltage reference set point
-- $`E_{C}`$ - output from the terminal voltage transducer
-- $`V_{S}`$ -  power system stabilizer output signal (if present)
-- $`V_{UEL}`$ and $`V_{OEL}`$ - limiters
 
-### States
-- $`V_{t}`$ - terminal voltage (2 is sensed $`V_{t}`$)
-- $`V_{B}`$ - input to a voltage regulator (3)
-- $`V_{R}`$ - voltage regulator output also know as exciter field voltage (4)
-- $`V_{F}`$ - stabilizing feedback signal (5)
-### Parameters
-- $`T_{R}`$ - filter time constant, sec (0)
-- $`K_{A}`$ - voltage regulator gain (40)
-- $`T_{A}`$ - time constant, sec (0.1)
-- $`T_{B}`$ - lag time constant, sec (0)
-- $`T_{C}`$ - lead time constant, sec (0)
-- $`V_{RMAX}`$ - maximum control element output, pu (1)
-- $`V_{RMIN}`$ - minimum control element output, pu (-1)
-- $`K_{E}`$ - exciter field resistance line slope margine, pu (0.1)
-- $`T_{E}`$ - exciter time constant, sec (0.5)
-- $`K_{F}`$ - rate feedback gain, pu (0.05)
-- $`T_{F1}`$ - rate feedback time constant, sec (0.7)
-- $`E1`$ - field voltage value, 1 (2.8)
-- $`SE1`$ - saturation factor at E1, (3.7)
-- $`E2`$ - field voltage value, 2 (3.7)
-- $`SE2`$ - saturation factor at E2, (0.33)
-
-## Equations
-First block
-```math
-\dfrac{dV_{t}}{dt}=\dfrac{1}{T_{R}}(E_{C}-V_{t})
-```
-Second block
-```math
-\dfrac{dx_{1}}{dt}=\dfrac{1}{T_{B}}((V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})-V_{B})
-```
-```math
-V_{B}=x_{1}+\dfrac{T_{C}}{T_{B}}(V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})
-```
-Third block
-```math
-\dfrac{dV_{R}}{dt} = \begin{cases}
-   \dfrac{1}{T_{A}}(K_{A}V_{B}-V_{R}) &\text{if } V_{RMIN}<=V_{R}<= V_{RMAX}\\
-   0 &\text{if } V_{B}>0 \text{  and  } V_{R}>=V_{RMAX} &\text{ also then } V_{R}=V_{RMAX}\\
-   0 &\text{if } V_{B}<0 \text{  and  } V_{R}<=V_{RMIN} &\text{ also then } V_{R}=V_{RMIN}\\
-\end{cases}
-```
-Fourth block
-```math
-\dfrac{d\dfrac{E_{FD}}{\omega}}{dt}=\dfrac{1}{T_{E}}(V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega})
-```
-Feedback loop
-```math
-\dfrac{dx_{2}}{dt}=-\dfrac{V_{F}}{T_{F1}}
-```
-```math
-V_{F}=x_{2}+\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega}
-```
-Saturation is modeled using an alternative quadratic function, with the value of Se specified at two points :
-```math
-Sat(x) = \begin{cases}
-   \dfrac{B(x-A)^2}{x} &\text{if } x>A \\
-   0 &\text{if } x<=A
-\end{cases}
-```
-same as with the synchronous machines. There are two solutions, and one where $`A<1`$ should be chosen.
-
-## Initialization
-```math
-V_{t}=V_{t_{0}}
-```
-```math
-E_{C}=V_{t_{0}}
-```
-```math
-(V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})=V_{B}
-```
-```math
-V_{R}=V{R_{0}}
-```
-```math
-V_{B}=\dfrac{V{R_{0}}}{K_{A}}
-```
-```math
-\dfrac{E_{FD}}{\omega}=\dfrac{E_{FD_{0}}}{\omega}
-```
-```math
-V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega}=0
-```
-```math
-V_{F}=0
-```
-```math
-x_{2_{0}}=-\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega}
+## Types
+There are a few standard Exciter models
+- IEEE Type 1 Excitation Model (See [IEEET1](IEEET1/README.md))
+- IEEE DC1 Excitation Model (See [EXDC1](EXDC1/README.md))