From df9459b0488f5b25d695b61d7a161a619c2862fa Mon Sep 17 00:00:00 2001 From: lukelowry Date: Sun, 31 May 2026 22:29:55 -0500 Subject: [PATCH 1/2] Add EXAC1 exciter documentation stub --- .../PhasorDynamics/Exciter/EXAC1/README.md | 72 ++++++++++++++++++ .../Model/PhasorDynamics/Exciter/README.md | 1 + docs/Figures/PhasorDynamics/EXAC1_diagram.png | Bin 0 -> 43642 bytes 3 files changed, 73 insertions(+) create mode 100644 GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md create mode 100644 docs/Figures/PhasorDynamics/EXAC1_diagram.png diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md new file mode 100644 index 000000000..756d90eba --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md @@ -0,0 +1,72 @@ +# **Exciter Model (EXAC1)** + +> [!NOTE] +> This README is a documentation stub/template for the EXAC1 exciter. Parameters, variables, equations, initialization details, and outputs are intentionally left unfilled until the model is derived from its source documentation. + +## Block Diagram + +Standard model of the EXAC1 Exciter. + +
+ + + Figure 1: Exciter EXAC1 model. +
+ +## Model Parameters + +Symbol | Units | Description | Typical Value | Note +-------|-------|-------------|---------------|----- + +### Model Derived Parameters + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +-------|-------|-------------|----- + +#### Algebraic + +Symbol | Units | Description | Note +-------|-------|-------------|----- + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +-------|-------|-------------|----- + +#### Algebraic + +Symbol | Units | Description | Note +-------|-------|-------------|----- + +## Model Equations + +### Differential Equations + +```math +\begin{aligned} +\end{aligned} +``` + +### Algebraic Equations + +```math +\begin{aligned} +\end{aligned} +``` + +## Initialization + +```math +\begin{aligned} +\end{aligned} +``` + +## Model Outputs diff --git a/GridKit/Model/PhasorDynamics/Exciter/README.md b/GridKit/Model/PhasorDynamics/Exciter/README.md index 81144066b..d80d67488 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/README.md @@ -14,4 +14,5 @@ device internal voltage. 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)) +- EXAC1 Excitation Model (See [EXAC1](EXAC1/README.md)) - Simplified Excitation System Model (See [SEXS-PTI](SEXS-PTI/README.md)) diff --git a/docs/Figures/PhasorDynamics/EXAC1_diagram.png b/docs/Figures/PhasorDynamics/EXAC1_diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..3a2a93704fcea7a9cbb12942f6343fe5f2dd9fe3 GIT binary patch literal 43642 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 z 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 literal 0 HcmV?d00001 From ba72c0abfe5118796f5e2f1c25837ba40045363a Mon Sep 17 00:00:00 2001 From: lukelowry Date: Tue, 2 Jun 2026 16:53:18 -0500 Subject: [PATCH 2/2] docs: complete EXAC1 README [skip ci] --- .../PhasorDynamics/Exciter/EXAC1/README.md | 185 ++++++++++++++++-- 1 file changed, 171 insertions(+), 14 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md index 756d90eba..bbf7a68b3 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md @@ -1,7 +1,16 @@ -# **Exciter Model (EXAC1)** +# **IEEE Type AC1 Excitation System Model (EXAC1)** -> [!NOTE] -> This README is a documentation stub/template for the EXAC1 exciter. Parameters, variables, equations, initialization details, and outputs are intentionally left unfilled until the model is derived from its source documentation. +EXAC1 is an IEEE Type AC excitation system with a terminal-voltage transducer, +lead-lag compensated voltage regulator, alternator field-voltage state, +stabilizing feedback, exciter saturation, rectifier loading, and optional speed +multiplier. + +Notes: +- Internal voltage and current signals are on model base unless otherwise stated. +- The rectifier loading block $F_{\mathrm{ex}}=f(I_N)$ is the source AC-exciter + loading curve from Fig. 1; it is not a CommonMath helper. +- The source diagram labels the optional multiplier input as `Speed`; GridKit + uses machine speed deviation, so the enabled multiplier is $1+\omega$. ## Block Diagram @@ -10,41 +19,119 @@ Standard model of the EXAC1 Exciter.
- Figure 1: Exciter EXAC1 model. + Figure 1: Exciter EXAC1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/)
## Model Parameters -Symbol | Units | Description | Typical Value | Note --------|-------|-------------|---------------|----- +Symbol | Units | JSON | Description | Typical Value | Note +------------------------------------|----------|-----------|---------------------------------------------------------|---------------|------ +$T_R$ | [sec] | `Tr` | Transducer time constant | 0.0 | Block name: `Tr`; if zero, $V_C$ is algebraic +$T_B$ | [sec] | `Tb` | Lag time constant for voltage-regulator input lead-lag | 0.0 | Block name: `Tb`; if $T_B=T_C=0$, the lead-lag block is bypassed +$T_C$ | [sec] | `Tc` | Lead time constant for voltage-regulator input lead-lag | 0.0 | Block name: `Tc` +$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | Block name: `Ka` +$T_A$ | [sec] | `Ta` | Voltage-regulator time constant | 0.1 | Block name: `Ta` +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | Block name: `Vrmax` +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | Block name: `Vrmin` +$T_E$ | [sec] | `Te` | Exciter alternator time constant | 0.5 | Block name: `Te` +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | Block name: `Kf` +$T_F$ | [sec] | `Tf` | Stabilizing feedback time constant | 0.7 | Block name: `Tf`; if zero, $V_F$ is algebraic +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | Block name: `Kc`; forms $I_N$ +$K_D$ | [p.u.] | `Kd` | Demagnetizing factor feedback gain | 0.0 | Block name: `Kd` +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | Block name: `Ke` +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | Block name: `E1` +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Block name: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | Block name: `E2` +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Block name: `Se2` +$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | Block name: `Spdmlt`; 1 enables the speed multiplier + +### Parameter Validation + +Invalid EXAC1 parameter sets are rejected by the following checks. + +```math +\begin{aligned} + &K_A > 0 \\ + &T_R \ge 0,\quad T_A > 0,\quad T_B \ge 0,\quad T_C \ge 0,\quad T_E > 0,\quad T_F \ge 0 \\ + &T_B > 0\quad\text{or}\quad(T_B = 0\ \text{and}\ T_C = 0) \\ + &V_R^{\min} \le V_R^{\max} \\ + &s_{\mathrm{spd}} \in \{0,1\} +\end{aligned} +``` + +The saturation points are either disabled together, + +```math +\begin{aligned} + S_E(E_1) = 0,\quad S_E(E_2) = 0 +\end{aligned} +``` + +or define a valid two-point quadratic saturation fit: + +```math +\begin{aligned} + &E_1 > 0,\quad E_2 > 0,\quad E_1 \ne E_2 \\ + &S_E(E_1) > 0,\quad S_E(E_2) > 0,\quad S_E(E_1) \ne S_E(E_2) +\end{aligned} +``` ### Model Derived Parameters +The saturation curve is fitted from the two supplied saturation points. If both +saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: + +```math +\begin{aligned} + C &= \sqrt{\dfrac{S_E(E_2)}{S_E(E_1)}} \\ + S_A &= \dfrac{C E_1 - E_2}{C - 1} \\ + S_B &= \dfrac{S_E(E_1)}{(E_1 - S_A)^2} +\end{aligned} +``` + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description | Note --------|-------|-------------|----- +Symbol | Units | Description | Note +------------------------------------|--------|---------------------------------------------------------|------ +$V_E$ | [p.u.] | Exciter alternator voltage state before output multipliers | State 1 in Fig. 1; source label: `VE` +$V_C$ | [p.u.] | Sensed compensated voltage | State 2 in Fig. 1; source label: `Sensed Vt`; algebraic when $T_R=0$ +$V_R$ | [p.u.] | Voltage-regulator output | State 3 in Fig. 1; source label: `VR` +$x_{\mathrm{ll}}$ | [p.u.] | Lead-lag block state | State 4 in Fig. 1; source label: `VLL` +$V_F$ | [p.u.] | Stabilizing feedback washout output | State 5 in Fig. 1; source label: `VF`; algebraic when $T_F=0$ #### Algebraic -Symbol | Units | Description | Note --------|-------|-------------|----- +Symbol | Units | Description | Note +------------------------------------|--------|---------------------------------------------------------|------ +$e_V$ | [p.u.] | Voltage-regulator input error before lead-lag block | Summing junction after sensed voltage +$V_{\mathrm{ll}}$ | [p.u.] | Lead-lag output | Input to voltage regulator +$S_E$ | [p.u.] | Saturation coefficient evaluated at $V_E$ | Uses derived saturation curve +$I_N$ | [p.u.] | Normalized exciter loading current | Source label: `IN`; satisfies $V_E I_N=K_C I_{\mathrm{fd}}$ +$F_{\mathrm{ex}}$ | [p.u.] | Rectifier loading factor | Source label: `FEX`; source curve $F_{\mathrm{ex}}=f(I_N)$ +$V_{\mathrm{fe}}$ | [p.u.] | Exciter feedback signal | Sum of saturation/resistance and $K_D I_{\mathrm{fd}}$ paths +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after rectifier loading and optional speed multiplier ### External Variables #### Differential -Symbol | Units | Description | Note --------|-------|-------------|----- +None. #### Algebraic -Symbol | Units | Description | Note --------|-------|-------------|----- +Symbol | Units | Description | Note +------------------------------------|--------|---------------------------------------------------------|------ +$E_C$ | [p.u.] | Compensated terminal voltage magnitude | Source label: `EC` +$V_{\mathrm{ref}}$ | [p.u.] | Voltage-control reference | Source label: `VREF` +$V_S$ | [p.u.] | Stabilizer input signal | Source label: `VS`; optional, defaults to zero +$V_{\mathrm{uel}}$ | [p.u.] | Under-excitation limiter input | Source label: `VUEL`; optional, defaults to zero +$V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input | Source label: `VOEL`; optional, defaults to zero +$I_{\mathrm{fd}}$ | [p.u.] | Machine field current | Source label: `IFD` +$\omega$ | [p.u.] | Machine speed deviation | Source label: `Speed`; optional when $s_{\mathrm{spd}}=0$ ## Model Equations @@ -52,21 +139,91 @@ Symbol | Units | Description | Note ```math \begin{aligned} + 0 &= -T_R\dot V_C - V_C + E_C \\ + 0 &= -T_B\dot x_{\mathrm{ll}} - x_{\mathrm{ll}} + e_V \\ + 0 &= -T_A\dot V_R + + \text{antiwindup}\!\left( + V_R, + -V_R + K_A V_{\mathrm{ll}}, + V_R^{\min}, + V_R^{\max} + \right) \\ + 0 &= -T_E\dot V_E + V_R - V_{\mathrm{fe}} \\ + 0 &= -T_F\dot V_F - V_F + K_F\dot V_E \end{aligned} ``` +CommonMath defines the [Anti-Windup](../../../../CommonMath.md#anti-windup-indicator) +target and smooth approximation. + ### Algebraic Equations ```math \begin{aligned} + 0 &= -e_V + V_{\mathrm{ref}} + V_S + V_{\mathrm{uel}} + V_{\mathrm{oel}} - V_C - V_F \\ + 0 &= -T_B(V_{\mathrm{ll}} - x_{\mathrm{ll}}) + T_C(e_V - x_{\mathrm{ll}}) \\ + 0 &= -S_E + S_B\,q(V_E - S_A) \\ + 0 &= -V_E I_N + K_C I_{\mathrm{fd}} \\ + 0 &= -F_{\mathrm{ex}} + f(I_N) \\ + 0 &= -V_{\mathrm{fe}} + (K_E + S_E)V_E + K_D I_{\mathrm{fd}} \\ + 0 &= -E_{\mathrm{fd}} + + \left(1+s_{\mathrm{spd}}\omega\right)F_{\mathrm{ex}}V_E \end{aligned} ``` +CommonMath defines the primitive [quadratic ramp](../../../../CommonMath.md#primitives) +$q$. The rectifier loading function $f(I_N)$ is the source curve shown in +Fig. 1. When $T_B=T_C=0$, the lead-lag block is bypassed so +$V_{\mathrm{ll}}=e_V$. + ## Initialization +The machine initializes $E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ first. For a +standard unsaturated start, EXAC1 reads those values along with attached +$\omega$, $E_C$, $V_S$, $V_{\mathrm{uel}}$, and $V_{\mathrm{oel}}$, and sets all +internal derivatives to zero. First solve the coupled rectifier-loading +equations: + ```math \begin{aligned} + 0 &= -V_{E,0}I_{N,0} + K_C I_{\mathrm{fd},0} \\ + 0 &= -F_{\mathrm{ex},0} + f(I_{N,0}) \\ + 0 &= -E_{\mathrm{fd},0} + + \left(1+s_{\mathrm{spd}}\omega_0\right)F_{\mathrm{ex},0}V_{E,0} \end{aligned} ``` +Then evaluate: + +```math +\begin{aligned} + S_{E,0} &= S_B\,q(V_{E,0} - S_A) \\ + V_{\mathrm{fe},0} &= (K_E + S_{E,0})V_{E,0} + K_D I_{\mathrm{fd},0} \\ + V_{R,0} &= V_{\mathrm{fe},0} \\ + V_{\mathrm{ll},0} &= \dfrac{V_{R,0}}{K_A} \\ + V_{C,0} &= E_{C,0} \\ + V_{F,0} &= 0 \\ + x_{\mathrm{ll},0} &= e_{V,0} = V_{\mathrm{ll},0} \\ + V_{\mathrm{ref},0} + &= e_{V,0} + V_{C,0} + V_{F,0} + - V_{S,0} - V_{\mathrm{uel},0} - V_{\mathrm{oel},0} +\end{aligned} +``` + +This standard start requires $1+s_{\mathrm{spd}}\omega_0\ne 0$, +$V_{E,0}\ne 0$, and $V_R^{\min}\le V_{R,0}\le V_R^{\max}$. Saturated regulator +starts are outside these closed-form equations. + ## Model Outputs + +Output | Units | Description | Note +----------------|--------|-------------------------------------|------ +`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ +`ve` | [p.u.] | Exciter alternator voltage state | $V_E$ +`vc` | [p.u.] | Sensed compensated voltage | $V_C$ +`vr` | [p.u.] | Voltage-regulator output | $V_R$ +`vll` | [p.u.] | Lead-lag output | $V_{\mathrm{ll}}$ +`vf` | [p.u.] | Stabilizing feedback state | $V_F$ +`in` | [p.u.] | Normalized exciter loading current | $I_N$ +`fex` | [p.u.] | Rectifier loading factor | $F_{\mathrm{ex}}$ +`se` | [p.u.] | Saturation coefficient | $S_E$