From 30b87d11abd7ed4fb53c45e3ae8115b0ca2adf92 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Sun, 31 May 2026 22:29:55 -0500 Subject: [PATCH 1/2] Add EXPIC1 exciter documentation stub --- .../PhasorDynamics/Exciter/EXPIC1/README.md | 72 ++++++++++++++++++ .../Model/PhasorDynamics/Exciter/README.md | 1 + .../Figures/PhasorDynamics/EXPIC1_diagram.png | Bin 0 -> 54074 bytes 3 files changed, 73 insertions(+) create mode 100644 GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md create mode 100644 docs/Figures/PhasorDynamics/EXPIC1_diagram.png diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md new file mode 100644 index 000000000..4935be3ce --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md @@ -0,0 +1,72 @@ +# **Exciter Model (EXPIC1)** + +> [!NOTE] +> This README is a documentation stub/template for the EXPIC1 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 EXPIC1 Exciter. + +
+ + + Figure 1: Exciter EXPIC1 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..0b6c03977 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)) +- EXPIC1 Excitation Model (See [EXPIC1](EXPIC1/README.md)) - Simplified Excitation System Model (See [SEXS-PTI](SEXS-PTI/README.md)) diff --git a/docs/Figures/PhasorDynamics/EXPIC1_diagram.png b/docs/Figures/PhasorDynamics/EXPIC1_diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..4bb1bdf445b5af565096631641f896327a7b74bf GIT binary patch literal 54074 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 aB?YM$bMyx1flfl93=Phnq@K8R`+ouXgobYb literal 0 HcmV?d00001 From c4fab36076b34e43f354761fe46e8ba6f7f05ad8 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Tue, 2 Jun 2026 16:53:19 -0500 Subject: [PATCH 2/2] docs: complete EXPIC1 README [skip ci] --- .../PhasorDynamics/Exciter/EXPIC1/README.md | 228 ++++++++++++++++-- 1 file changed, 214 insertions(+), 14 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md index 4935be3ce..1073c54ac 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md @@ -1,7 +1,17 @@ -# **Exciter Model (EXPIC1)** +# **Proportional/Integral Excitation System Model (EXPIC1)** -> [!NOTE] -> This README is a documentation stub/template for the EXPIC1 exciter. Parameters, variables, equations, initialization details, and outputs are intentionally left unfilled until the model is derived from its source documentation. +EXPIC1 is a proportional/integral excitation system with terminal-voltage +sensing, a PI regulator, cascaded regulator filters, stabilizing feedback, +potential/current-source scaling, rectifier loading, exciter limits, saturation, +and an exciter field-voltage state. + +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. +- If $K_P=0$ and $K_I=0$, the diagram sets $V_B=1$. +- If $T_E=0$, the source diagram states $E_{\mathrm{fd}}=E_0$; the exciter + field state becomes algebraic. ## Block Diagram @@ -10,41 +20,126 @@ Standard model of the EXPIC1 Exciter.
- Figure 1: Exciter EXPIC1 model. + Figure 1: Exciter EXPIC1 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, $E_T$ is algebraic +$K_A$ | [p.u.] | `Ka` | PI regulator gain | 1.0 | Block name: `Ka` +$T_{A1}$ | [sec] | `Ta1` | PI regulator numerator time constant | 0.0 | Block name: `Ta1` +$V_{R1}^{\max}$ | [p.u.] | `Vr1` | PI regulator upper output limit | 1.0 | Source label: `VR1` +$V_{R2}^{\min}$ | [p.u.] | `Vr2` | PI regulator lower output limit | -1.0 | Source label: `VR2` +$T_{A2}$ | [sec] | `Ta2` | First denominator time constant in regulator filter | 0.0 | Block name: `Ta2` +$T_{A3}$ | [sec] | `Ta3` | Numerator time constant in regulator filter | 0.0 | Block name: `Ta3` +$T_{A4}$ | [sec] | `Ta4` | Second denominator time constant in regulator filter | 0.0 | Block name: `Ta4` +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum regulator output before source multiplier | 1.0 | Block name: `Vrmax` +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum regulator output before source multiplier | -1.0 | Block name: `Vrmin` +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.0 | Block name: `Kf` +$T_{F1}$ | [sec] | `Tf1` | First feedback denominator time constant | 0.0 | Block name: `Tf1` +$T_{F2}$ | [sec] | `Tf2` | Second feedback denominator time constant | 0.0 | Block name: `Tf2` +$E_{\mathrm{fd}}^{\max}$ | [p.u.] | `Efdmax` | Maximum exciter input limit | 5.0 | Block name: `EFDMAX` +$E_{\mathrm{fd}}^{\min}$ | [p.u.] | `Efdmin` | Minimum exciter input limit | -5.0 | Block name: `EFDMIN` +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | Block name: `Ke` +$T_E$ | [sec] | `Te` | Exciter time constant | 0.5 | Block name: `Te`; if zero, $E_{\mathrm{fd}}=E_0$ +$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` +$K_P$ | [p.u.] | `Kp` | Potential-source voltage coefficient | 0.0 | Source label: `KP`; forms $V_E$ +$K_I$ | [p.u.] | `Ki` | Potential-source current coefficient | 0.0 | Source label: `KI`; forms $V_E$ +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | Block name: `Kc`; forms $I_N$ + +### Parameter Validation + +Invalid EXPIC1 parameter sets are rejected by the following checks. + +```math +\begin{aligned} + &T_R \ge 0,\quad T_{A1}\ge 0,\quad T_{A2}\ge 0,\quad T_{A3}\ge 0,\quad T_{A4}\ge 0 \\ + &T_{F1}\ge 0,\quad T_{F2}\ge 0,\quad T_E\ge 0 \\ + &V_{R2}^{\min}\le V_{R1}^{\max},\quad V_R^{\min}\le V_R^{\max},\quad E_{\mathrm{fd}}^{\min}\le E_{\mathrm{fd}}^{\max} +\end{aligned} +``` + +The saturation points are either disabled together or define a valid positive +two-point quadratic fit. ### 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} +``` + +The source calculation uses explicit real and imaginary terminal voltage/current +components: + +```math +\begin{aligned} + V_{\mathrm{src}}^{\mathrm{r}} &= K_P V_{\mathrm{r}} - K_I I_{\mathrm{i}} \\ + V_{\mathrm{src}}^{\mathrm{i}} &= K_P V_{\mathrm{i}} + K_I I_{\mathrm{r}} +\end{aligned} +``` + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description | Note --------|-------|-------------|----- +Symbol | Units | Description | Note +------------------------------------|--------|---------------------------------------------------------|------ +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output state | State 1 in Fig. 1; algebraic when $T_E=0$ +$E_T$ | [p.u.] | Sensed terminal voltage | State 2 in Fig. 1; source label: `Sensed Vt`; algebraic when $T_R=0$ +$V_A$ | [p.u.] | PI regulator output | State 3 in Fig. 1 +$x_{R1}$ | [p.u.] | First regulator filter state | State 4 in Fig. 1; source label: `VR1` +$V_R$ | [p.u.] | Regulator output before source multiplier | State 5 in Fig. 1; source label: `VR` +$V_{F1}$ | [p.u.] | First feedback filter state | State 6 in Fig. 1; source label: `VF1` +$V_F$ | [p.u.] | Stabilizing feedback output | State 7 in Fig. 1; source label: `VF` #### Algebraic -Symbol | Units | Description | Note --------|-------|-------------|----- +Symbol | Units | Description | Note +------------------------------------|--------|---------------------------------------------------------|------ +$e_V$ | [p.u.] | Voltage-error signal after feedback | Summing junction after $E_T$ +$V_{\mathrm{src}}^{\mathrm{r}}$ | [p.u.] | Real component of the source expression | From terminal voltage/current components +$V_{\mathrm{src}}^{\mathrm{i}}$ | [p.u.] | Imaginary component of the source expression | From terminal voltage/current components +$V_{\mathrm{src}}$ | [p.u.] | Potential/current source magnitude | Nonnegative source magnitude +$I_N$ | [p.u.] | Normalized exciter loading current | Source label: `IN`; satisfies $V_{\mathrm{src}}I_N=K_C I_{\mathrm{fd}}$ when source scaling is active +$F_{\mathrm{ex}}$ | [p.u.] | Rectifier loading factor | Source label: `FEX`; source curve $F_{\mathrm{ex}}=f(I_N)$ +$V_B$ | [p.u.] | Source multiplier after rectifier loading | Product of $V_{\mathrm{src}}$ and $F_{\mathrm{ex}}$, or 1 when $K_P=K_I=0$ +$E_0$ | [p.u.] | Limited exciter input | Limited by $E_{\mathrm{fd}}^{\min}$ and $E_{\mathrm{fd}}^{\max}$ +$S_E$ | [p.u.] | Saturation coefficient evaluated at $E_{\mathrm{fd}}$ | Uses derived saturation curve ### 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_{\mathrm{uel}}$ | [p.u.] | Under-excitation limiter input | Source label: `VUEL`; optional, defaults to zero +$V_S$ | [p.u.] | Stabilizer input signal | Source label: `VS`; optional, defaults to zero +$V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input | Source label: `VOEL`; optional, defaults to zero +$V_{\mathrm{r}}$ | [p.u.] | Terminal-voltage real component | Source label: `VT` +$V_{\mathrm{i}}$ | [p.u.] | Terminal-voltage imaginary component | Source label: `VT` +$I_{\mathrm{r}}$ | [p.u.] | Terminal-current real component | Source label: `IT` +$I_{\mathrm{i}}$ | [p.u.] | Terminal-current imaginary component | Source label: `IT` +$I_{\mathrm{fd}}$ | [p.u.] | Machine field current | Source label: `IFD` ## Model Equations @@ -52,21 +147,126 @@ Symbol | Units | Description | Note ```math \begin{aligned} + 0 &= -T_R\dot E_T - E_T + E_C \\ + 0 &= + -\dot V_A + + \text{antiwindup}\!\left( + V_A, + K_A e_V, + V_{R2}^{\min}, + V_{R1}^{\max} + \right) \\ + 0 &= -T_{A2}\dot x_{R1} - x_{R1} + V_A \\ + 0 &= -T_{A4}\dot V_R - V_R + x_{R1} + T_{A3}\dot x_{R1} \\ + 0 &= -T_{F1}\dot V_{F1} - V_{F1} + V_R \\ + 0 &= -T_{F2}\dot V_F - V_F + K_F\dot V_{F1} \\ + 0 &= -T_E\dot E_{\mathrm{fd}} + E_0 - (K_E + S_E)E_{\mathrm{fd}} \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_{\mathrm{uel}} + V_S + V_{\mathrm{oel}} - E_T - V_F \\ + 0 &= -V_{\mathrm{src}}^{\mathrm{r}} + K_P V_{\mathrm{r}} - K_I I_{\mathrm{i}} \\ + 0 &= -V_{\mathrm{src}}^{\mathrm{i}} + K_P V_{\mathrm{i}} + K_I I_{\mathrm{r}} \\ + 0 &= -V_{\mathrm{src}}^2 + + \left(V_{\mathrm{src}}^{\mathrm{r}}\right)^2 + + \left(V_{\mathrm{src}}^{\mathrm{i}}\right)^2 \\ + 0 &= + \begin{cases} + -I_N & K_P=0\ \text{and}\ K_I=0 \\ + -V_{\mathrm{src}}I_N + K_C I_{\mathrm{fd}} & \text{otherwise} + \end{cases} \\ + 0 &= -F_{\mathrm{ex}} + + \begin{cases} + 1 & K_P=0\ \text{and}\ K_I=0 \\ + f(I_N) & \text{otherwise} + \end{cases} \\ + 0 &= -V_B + + \begin{cases} + 1 & K_P=0\ \text{and}\ K_I=0 \\ + V_{\mathrm{src}}F_{\mathrm{ex}} & \text{otherwise} + \end{cases} \\ + 0 &= -E_0 + \text{clamp}(V_B V_R, E_{\mathrm{fd}}^{\min}, E_{\mathrm{fd}}^{\max}) \\ + 0 &= -S_E + S_B\,q(E_{\mathrm{fd}} - S_A) \end{aligned} ``` +CommonMath defines helper targets for [clamp](../../../../CommonMath.md#derived-functions) +and the primitive [quadratic ramp](../../../../CommonMath.md#primitives) $q$. +The rectifier loading function $f(I_N)$ is the source curve shown in Fig. 1. +The $V_{\mathrm{src}}$ residual uses the nonnegative branch of the squared +source-magnitude equation. + ## Initialization +For a standard unsaturated start, the machine initializes +$E_{\mathrm{fd},0}$ and $I_{\mathrm{fd},0}$ first. EXPIC1 reads those values, +sets all internal derivatives to zero, and evaluates: + ```math \begin{aligned} + E_{T,0} &= E_{C,0} \\ + V_{\mathrm{src},0}^{\mathrm{r}} &= K_P V_{\mathrm{r},0} - K_I I_{\mathrm{i},0} \\ + V_{\mathrm{src},0}^{\mathrm{i}} &= K_P V_{\mathrm{i},0} + K_I I_{\mathrm{r},0} \\ + V_{\mathrm{src},0} + &= \sqrt{ + \left(V_{\mathrm{src},0}^{\mathrm{r}}\right)^2 + + \left(V_{\mathrm{src},0}^{\mathrm{i}}\right)^2 + } \\ + 0 &= + \begin{cases} + -I_{N,0} & K_P=0\ \text{and}\ K_I=0 \\ + -V_{\mathrm{src},0}I_{N,0} + K_C I_{\mathrm{fd},0} & \text{otherwise} + \end{cases} \\ + F_{\mathrm{ex},0} &= + \begin{cases} + 1 & K_P=0\ \text{and}\ K_I=0 \\ + f(I_{N,0}) & \text{otherwise} + \end{cases} \\ + V_{B,0} &= + \begin{cases} + 1 & K_P=0\ \text{and}\ K_I=0 \\ + V_{\mathrm{src},0}F_{\mathrm{ex},0} & \text{otherwise} + \end{cases} \\ + S_{E,0} &= S_B\,q(E_{\mathrm{fd},0} - S_A) \\ + E_{0,0} &= (K_E + S_{E,0})E_{\mathrm{fd},0} \\ + V_{R,0} &= \dfrac{E_{0,0}}{V_{B,0}} \\ + x_{R1,0} &= V_{R,0} \\ + V_{A,0} &= x_{R1,0} \\ + V_{F1,0} &= V_{R,0} \\ + V_{F,0} &= 0 \\ + e_{V,0} &= \dfrac{V_{A,0}}{K_A} \\ + V_{\mathrm{ref},0} + &= e_{V,0} + E_{T,0} + V_{F,0} + - V_{\mathrm{uel},0} - V_{S,0} - V_{\mathrm{oel},0} \end{aligned} ``` +This closed-form start requires nonzero $K_A$ and $V_{B,0}$, inactive PI and +exciter limits, and residual consistency with the source curve. When +$K_P$ and $K_I$ are not both zero, it also requires $V_{\mathrm{src},0}\ne 0$. +If $T_E=0$, the final exciter residual is algebraic and requires +$E_{\mathrm{fd},0}=E_{0,0}$. Starts that bind the PI regulator, cascaded +regulator, or exciter limits are outside these closed-form equations. + ## Model Outputs + +Output | Units | Description | Note +----------------|--------|-------------------------------------|------ +`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ +`et` | [p.u.] | Sensed terminal voltage | $E_T$ +`va` | [p.u.] | PI regulator state | $V_A$ +`vr1` | [p.u.] | First regulator filter state | $x_{R1}$ +`vr` | [p.u.] | Regulator output | $V_R$ +`vf1` | [p.u.] | First feedback filter state | $V_{F1}$ +`vf` | [p.u.] | Stabilizing feedback output | $V_F$ +`vb` | [p.u.] | Source multiplier | $V_B$ +`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$