diff --git a/GridKit/Model/EMT/Bus/README.md b/GridKit/Model/EMT/Bus/README.md index ebd566ba8..ab03e9aa7 100644 --- a/GridKit/Model/EMT/Bus/README.md +++ b/GridKit/Model/EMT/Bus/README.md @@ -1,8 +1,10 @@ # Bus Model `Bus` represents an $N$-phase bus in instantaneous phase coordinates. It owns -the differential bus voltage and contributes the current-balance residual to -the assembled DAE. $\mathcal{E}$ denotes the set of connected devices. +the bus voltage and contributes the current-balance residual to +the assembled DAE. $`\mathcal{D}`$ denotes the set of connected devices. +Bus voltage and its residual are algebraic when no connected model contributes +a voltage derivative; see [assembly](../README.md#assembly). ## Block Diagram @@ -30,7 +32,7 @@ None. Symbol | Port | Type | Units | Description | Note ------ | ---- | ---- | ----- | ----------- | ---- -$\mathbf{i}_e$ | `i` | Input | [A] | Current from connected device $e$ | One port per $e \in \mathcal{E}$, $\mathbf{i}_e \in \mathbb{R}^N$ +$\mathbf{i}_d$ | `i` | Input | [A] | Current from connected device $d$ | One port per $d \in \mathcal{D}$, $\mathbf{i}_d \in \mathbb{R}^N$ $\mathbf{v}$ | `v` | Output | [V] | Bus voltage supplied to connected devices | $\mathbf{v} \in \mathbb{R}^N$ ## Submodels @@ -41,6 +43,10 @@ None. None. +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -72,7 +78,7 @@ None. #### Differential ```math -0 = \sum_{e \in \mathcal{E}} \mathbf{i}_e +0 = \sum_{d \in \mathcal{D}} \mathbf{i}_d ``` #### Algebraic @@ -83,13 +89,9 @@ None. None. -### Wiring - -None. - ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors diff --git a/GridKit/Model/EMT/Component/Line/LineDistributed/README.md b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md index 280df5601..7fef9e054 100644 --- a/GridKit/Model/EMT/Component/Line/LineDistributed/README.md +++ b/GridKit/Model/EMT/Component/Line/LineDistributed/README.md @@ -18,7 +18,7 @@ Define the phase- and conductor-index sets ```math \mathcal{N} = \{1,\ldots,N\}, \qquad -\mathcal{K} = \{1,\ldots,K\}. +\mathcal{K} = \{1,\ldots,K\} ``` Symbol | Units | JSON | Description | Note @@ -73,7 +73,7 @@ uniform line, so ```math \mathbf{Y}_1^{\mathrm{c}}(s)=\mathbf{Y}_2^{\mathrm{c}}(s), \qquad -\mathbf{H}_{12}(s)=\mathbf{H}_{21}(s). +\mathbf{H}_{12}(s)=\mathbf{H}_{21}(s) ``` The two terminal-admittance instances maintain independent states, and the two @@ -137,8 +137,6 @@ None. #### Algebraic -The residuals use the signals defined under Submodel Wiring. - ```math \begin{aligned} 0 &= -\mathbf{i}_1^\mathrm{ref} @@ -163,9 +161,7 @@ The residuals use the signals defined under Submodel Wiring. ## Initialization -The characteristic-admittance and propagation submodels initialize according -to their own specifications. There is no additional line-level initialization -procedure. +Initialize the characteristic-admittance and propagation submodels. ## Monitors @@ -175,45 +171,3 @@ Monitor | Units | Description | Note `i_c2` | [A] | Characteristic-admittance current at terminal 2 | $\mathbf{i}_2^\mathrm{c} \in \mathbb{R}^K$ `i_inc1` | [A] | Incident current at terminal 1 | $\mathbf{i}_1^\mathrm{inc} \in \mathbb{R}^K$ `i_inc2` | [A] | Incident current at terminal 2 | $\mathbf{i}_2^\mathrm{inc} \in \mathbb{R}^K$ - -## Development - -The initial three-phase formulation takes $N=K=3$ and -$\mathbf{P}_\phi=\mathbf{I}_3$. - -```math -\begin{aligned} -0 &= -\mathbf{i}_1^\mathrm{ref} - + 2\mathbf{i}_1^\mathrm{c} - - \mathbf{i}_1^\mathrm{inc} \\ -0 &= -\mathbf{i}_2^\mathrm{ref} - + 2\mathbf{i}_2^\mathrm{c} - - \mathbf{i}_2^\mathrm{inc} -\end{aligned} -``` - -the external equations reduce to - -```math -\begin{aligned} -\mathbf{i}_1 - &\leftarrow \mathbf{i}_1^\mathrm{inc}-\mathbf{i}_1^\mathrm{c} \\ -\mathbf{i}_2 - &\leftarrow \mathbf{i}_2^\mathrm{inc}-\mathbf{i}_2^\mathrm{c} -\end{aligned} -``` - -and the submodel wiring reduces to - -```math -\begin{aligned} -\mathbf{i}_1^\mathrm{c} - &\leftarrow \mathbf{y}_1^\mathrm{c}[\mathbf{v}_1] \\ -\mathbf{i}_2^\mathrm{c} - &\leftarrow \mathbf{y}_2^\mathrm{c}[\mathbf{v}_2] \\ -\mathbf{i}_1^\mathrm{inc} - &\leftarrow \mathbf{h}_{21}[\mathbf{i}_2^\mathrm{ref}] \\ -\mathbf{i}_2^\mathrm{inc} - &\leftarrow \mathbf{h}_{12}[\mathbf{i}_1^\mathrm{ref}] -\end{aligned} -``` diff --git a/GridKit/Model/EMT/Component/Line/LineLumped/README.md b/GridKit/Model/EMT/Component/Line/LineLumped/README.md index 6a7c50cff..ffb140c3c 100644 --- a/GridKit/Model/EMT/Component/Line/LineLumped/README.md +++ b/GridKit/Model/EMT/Component/Line/LineLumped/README.md @@ -20,7 +20,7 @@ Define the phase- and conductor-index sets ```math \mathcal{N} = \{1,\ldots,N\}, \qquad -\mathcal{K} = \{1,\ldots,K\}. +\mathcal{K} = \{1,\ldots,K\} ``` Symbol | Units | JSON | Description | Note @@ -79,6 +79,10 @@ independent states. \mathrm{rank}(\mathbf{E}^{\mathbf{z}}) = K ``` +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -124,10 +128,10 @@ None. ```math \begin{aligned} -0 &= \Delta x\,\mathbf{y}_2[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2] - + 2\mathbf{i}_2^\mathrm{sh} \\ 0 &= \Delta x\,\mathbf{y}_1[\mathbf{P}_\phi^\mathsf T\mathbf{v}_1] - + 2\mathbf{i}_1^\mathrm{sh} + + 2\mathbf{i}_1^\mathrm{sh} \\ +0 &= \Delta x\,\mathbf{y}_2[\mathbf{P}_\phi^\mathsf T\mathbf{v}_2] + + 2\mathbf{i}_2^\mathrm{sh} \end{aligned} ``` @@ -136,21 +140,21 @@ None. ```math \begin{aligned} \mathbf{i}_1 &\leftarrow - \mathbf{P}_\phi\left( + \mathbf{P}_\phi( \mathbf{i}_1^\mathrm{sh} - \mathbf{i}_{12} - \right) \\ + ) \\ \mathbf{i}_2 &\leftarrow - \mathbf{P}_\phi\left( + \mathbf{P}_\phi( \mathbf{i}_2^\mathrm{sh} + \mathbf{i}_{12} - \right) + ) \end{aligned} ``` ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors @@ -159,40 +163,3 @@ Monitor | Units | Description | Note `i12` | [A] | Series current from terminal 1 to terminal 2 | $\mathbf{i}_{12} \in \mathbb{R}^K$ `i_sh1` | [A] | Shunt current at terminal 1 | $\mathbf{i}_1^\mathrm{sh} \in \mathbb{R}^K$ `i_sh2` | [A] | Shunt current at terminal 2 | $\mathbf{i}_2^\mathrm{sh} \in \mathbb{R}^K$ - -## Development - -The initial three-phase formulation is a subset of the generalized formulation -above. - -### Derived Parameters - -```math -\begin{aligned} -\mathbf{R} &= \Delta x\,\mathbf{R}' \\ -\mathbf{L} &= \Delta x\,\mathbf{L}' \\ -\mathbf{G} &= \Delta x\,\mathbf{G}' \\ -\mathbf{C} &= \Delta x\,\mathbf{C}' -\end{aligned} -``` - -### Differential Equations - -```math -0 = \mathbf{R}\mathbf{i}_{12} - + \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}_{12}}{\mathrm{d}t} - + \mathbf{v}_2-\mathbf{v}_1 -``` - -### Algebraic Equations - -```math -\begin{aligned} -0 &= \mathbf{G}\mathbf{v}_2 - + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_2}{\mathrm{d}t} - + 2\mathbf{i}_2^\mathrm{sh} \\ -0 &= \mathbf{G}\mathbf{v}_1 - + \mathbf{C}\dfrac{\mathrm{d}\mathbf{v}_1}{\mathrm{d}t} - + 2\mathbf{i}_1^\mathrm{sh} -\end{aligned} -``` diff --git a/GridKit/Model/EMT/Component/Load/LoadZ/README.md b/GridKit/Model/EMT/Component/Load/LoadZ/README.md index d5dc20e19..0b2c3fdde 100644 --- a/GridKit/Model/EMT/Component/Load/LoadZ/README.md +++ b/GridKit/Model/EMT/Component/Load/LoadZ/README.md @@ -46,9 +46,13 @@ algebraic when $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$. ```math \mathbf{E}^{\mathbf{z}}=\mathbf{0} \qquad \text{or} \qquad -\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N. +\mathrm{rank}(\mathbf{E}^{\mathbf{z}})=N ``` +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -95,29 +99,18 @@ For $\mathbf{E}^{\mathbf{z}}=\mathbf{0}$, the same residual is algebraic. ### External Equations +The load supplies input $d$ of the [bus current balance](../../../Bus/README.md#model-equations): + ```math -\mathbf{f} \leftarrow \mathbf{i} +\mathbf{i}_d \leftarrow \mathbf{i} ``` ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors Monitor | Units | Description | Note ------- | ----- | ----------- | ---- `i` | [A] | Load current injection | $\mathbf{i} \in \mathbb{R}^N$ - -## Development - -The initial three-phase formulation uses resistance and inductance matrices. - -### Differential Equations - -```math -0 = -\mathbf{R}\mathbf{i} -+ \mathbf{L}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t} -+ \mathbf{v} -``` diff --git a/GridKit/Model/EMT/Component/Source/VoltageSource/README.md b/GridKit/Model/EMT/Component/Source/VoltageSource/README.md index 9dfea8056..e52b42513 100644 --- a/GridKit/Model/EMT/Component/Source/VoltageSource/README.md +++ b/GridKit/Model/EMT/Component/Source/VoltageSource/README.md @@ -34,7 +34,7 @@ N &\in \mathbb{Z}_{>0} \\ Define the phase-index set ```math -\mathcal{N} = \{1,\ldots,N\}. +\mathcal{N} = \{1,\ldots,N\} ``` ## Model Ports @@ -54,6 +54,10 @@ $\mathbf{y}$ | Terminal admittance | [VectorFit](../../../Operators/Rational/Vec None. +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -103,7 +107,7 @@ None. ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors @@ -111,18 +115,3 @@ Monitor | Units | Description | Note ------- | ----- | ----------- | ---- `e` | [V] | Source voltage | $\mathbf{e} \in \mathbb{R}^N$ `i` | [A] | Source current injection | $\mathbf{i} \in \mathbb{R}^N$ - -## Development - -The initial three-phase formulation realizes the terminal admittance as a -series resistance and inductance, with $\mathbf{i}$ as a differential variable. - -### Differential Equations - -```math -0 = -\mathbf{R}_\mathrm{s}\mathbf{i} -+ \mathbf{L}_\mathrm{s}\dfrac{\mathrm{d}\mathbf{i}}{\mathrm{d}t} -+ \mathbf{v} -- \mathbf{e} -``` diff --git a/GridKit/Model/EMT/Component/Switch/README.md b/GridKit/Model/EMT/Component/Switch/README.md index b70d7d9bd..58c9ec049 100644 --- a/GridKit/Model/EMT/Component/Switch/README.md +++ b/GridKit/Model/EMT/Component/Switch/README.md @@ -46,6 +46,10 @@ None. None. +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -85,8 +89,8 @@ None. ```math \begin{cases} -\mathbf{i}_{12} = \mathbf{0}, & \text{open}, \\ -\mathbf{v}_2-\mathbf{v}_1 = \mathbf{0}, & \text{closed}. +\mathbf{i}_{12} = \mathbf{0}, & \text{open}\\ +\mathbf{v}_2-\mathbf{v}_1 = \mathbf{0}, & \text{closed} \end{cases} ``` @@ -95,7 +99,7 @@ None. ```math \begin{aligned} \mathbf{i}_1 &\leftarrow -\mathbf{i}_{12} \\ -\mathbf{i}_2 &\leftarrow \mathbf{i}_{12}. +\mathbf{i}_2 &\leftarrow \mathbf{i}_{12} \end{aligned} ``` diff --git a/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md b/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md index ae1af87cf..c166f906e 100644 --- a/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md +++ b/GridKit/Model/EMT/Operators/Rational/StateSpace/README.md @@ -5,13 +5,9 @@ real or complex poles and factorized residue terms. For pole count $Q$, define the pole-index set ```math -\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\}. +\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\} ``` -Thus $\mathcal{Q}$ is empty when $Q=0$. - -Then - ```math \mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} + \mathbf{C}\dfrac{\mathbf{I}}{s\mathbf{I}-\mathbf{P}}\mathbf{B} @@ -49,21 +45,17 @@ $\mathbf{B}$ | $[\mathrm{s}^{-1}]$ | `B` | Input matrix | $\mathbf{B} \in \mathb ### Parameter Validation -The input and output dimensions are positive integers, and the pole count is a -nonnegative integer. Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain +Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain the real-pole indices and $\mathcal{Q}_\mathrm{c} \subseteq \mathcal{Q}$ the first indices of the nonreal conjugate pairs. Define their partner-index set as ```math \mathcal{Q}_\mathrm{c}^{+} - = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\}. + = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\} ``` -The three sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and -$\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint and together contain every -pole index. Real poles have real factors, and each nonreal pole and its factors -are followed by their conjugates. +The sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and $\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint. ```math \begin{aligned} @@ -95,10 +87,10 @@ p_{q+1} &= p_q^{\ast}, \mathbf{P} &= \mathrm{diag}(p_1,\ldots,p_Q) \\ \mathbf{a} &= \mathrm{Re}(\mathbf{p}) \\ \boldsymbol{\omega} &= \mathrm{Im}(\mathbf{p}) \\ -\mathbf{C}_{\mathrm{r}} &= \mathrm{Re}(\mathbf{C}) \\ -\mathbf{C}_{\mathrm{i}} &= \mathrm{Im}(\mathbf{C}) \\ -\mathbf{B}_{\mathrm{r}} &= \mathrm{Re}(\mathbf{B}) \\ -\mathbf{B}_{\mathrm{i}} &= \mathrm{Im}(\mathbf{B}) +\mathbf{C}_r &= \mathrm{Re}(\mathbf{C}) \\ +\mathbf{C}_i &= \mathrm{Im}(\mathbf{C}) \\ +\mathbf{B}_r &= \mathrm{Re}(\mathbf{B}) \\ +\mathbf{B}_i &= \mathrm{Im}(\mathbf{B}) \end{aligned} ``` @@ -117,6 +109,10 @@ None. None. +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -161,10 +157,10 @@ $\mathbf{u}$ | $[u]$ | Input vector | Algebraic-input configuration, $\mathbf{u} \quad q \in \mathcal{Q}_\mathrm{r} \\ 0 &= -\dfrac{\mathrm{d}w_q}{\mathrm{d}t} + a_qw_q-\omega_qv_q - + (\mathbf{B}_{\mathrm{r}})_{q,:}\mathbf{u} \\ + + (\mathbf{B}_r)_{q,:}\mathbf{u} \\ 0 &= -\dfrac{\mathrm{d}v_q}{\mathrm{d}t} + \omega_qw_q+a_qv_q - + (\mathbf{B}_{\mathrm{i}})_{q,:}\mathbf{u}, + + (\mathbf{B}_i)_{q,:}\mathbf{u}, \quad q \in \mathcal{Q}_\mathrm{c} \end{aligned} ``` @@ -182,16 +178,13 @@ None. + \sum_{q \in \mathcal{Q}_\mathrm{r}} \mathbf{C}_{:,q}w_q + 2\sum_{q \in \mathcal{Q}_\mathrm{c}} - ((\mathbf{C}_{\mathrm{r}})_{:,q}w_q - -(\mathbf{C}_{\mathrm{i}})_{:,q}v_q) + ((\mathbf{C}_r)_{:,q}w_q + -(\mathbf{C}_i)_{:,q}v_q) ``` -For algebraic input, $\mathbf{E}=\mathbf{0}$ and the input-derivative term -vanishes. - ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors diff --git a/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md b/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md index 656ba806d..09c5a9944 100644 --- a/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md +++ b/GridKit/Model/EMT/Operators/Rational/VectorFit/README.md @@ -5,16 +5,12 @@ or complex poles and general residue matrices. For pole count $Q$, define the pole-index set ```math -\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\}. +\mathcal{Q} = \{q \in \mathbb{Z}_{>0} \mid q \le Q\} ``` -Thus $\mathcal{Q}$ is empty when $Q=0$. - -Then - ```math \mathbf{H}(s) \approx \mathbf{D} + s\mathbf{E} - + \sum_{q \in \mathcal{Q}} \dfrac{\mathbf{R}_q}{s - p_q}. + + \sum_{q \in \mathcal{Q}} \dfrac{\mathbf{R}_q}{s - p_q} ``` `VectorFit` is a general rational operator; consuming models impose any @@ -45,21 +41,17 @@ $\mathbf{R}$ | $[y]/(\mathrm{s}[u])$ | `residues` | Residues | $\mathbf{R} \in \ ### Parameter Validation -The input and output dimensions are positive integers, and the pole count is a -nonnegative integer. Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain +Let $\mathcal{Q}_\mathrm{r} \subseteq \mathcal{Q}$ contain the real-pole indices and $\mathcal{Q}_\mathrm{c} \subseteq \mathcal{Q}$ the first indices of the nonreal conjugate pairs. Define their partner-index set as ```math \mathcal{Q}_\mathrm{c}^{+} - = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\}. + = \{q+1 \mid q \in \mathcal{Q}_\mathrm{c}\} ``` -The three sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and -$\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint and together contain every -pole index. Real poles have real residues, and each nonreal pole and residue is -followed by its conjugate. +The sets $\mathcal{Q}_\mathrm{r}$, $\mathcal{Q}_\mathrm{c}$, and $\mathcal{Q}_\mathrm{c}^{+}$ are pairwise disjoint. ```math \begin{aligned} @@ -107,6 +99,10 @@ None. None. +### Submodel Wiring + +None. + ## Model Variables ### Internal Variables @@ -177,12 +173,9 @@ None. (\mathbf{A}_q\mathbf{w}_q-\mathbf{B}_q\mathbf{v}_q) ``` -For algebraic input, $\mathbf{E}=\mathbf{0}$ and the input-derivative term -vanishes. - ## Initialization -None beyond the EMT initialization contract. +None. ## Monitors diff --git a/GridKit/Model/EMT/Operators/Shift/Delay/README.md b/GridKit/Model/EMT/Operators/Shift/Delay/README.md index 1a8b3221f..6c980a52f 100644 --- a/GridKit/Model/EMT/Operators/Shift/Delay/README.md +++ b/GridKit/Model/EMT/Operators/Shift/Delay/README.md @@ -4,13 +4,9 @@ ```math \mathbf{D}_{\boldsymbol{\tau}}(s) - = \mathrm{diag}\left(\exp(-s\tau_1),\ldots,\exp(-s\tau_M)\right). + = \mathrm{diag}(\exp(-s\tau_1),\ldots,\exp(-s\tau_M)) ``` -At runtime, accepted-step input samples are reconstructed with cubic Hermite -interpolation. `Delay` adds no DAE variables or residual rows. A scalar delay -is the $M=1$ case. - ## Block Diagram ![Delay operator block diagram](../../../../../../docs/Figures/EMT/Delay/diagram.png) @@ -58,6 +54,10 @@ None. None. +### Submodel Wiring + +None. + ## Model Variables History samples are implementation data, not DAE variables or residual rows. @@ -104,8 +104,6 @@ Each channel satisfies $y_m(t)=u_m(t-\tau_m)$. \mathbf{y} \leftarrow \mathbf{u}(t-\boldsymbol{\tau}) ``` - - ## History Realization ### History Record @@ -161,7 +159,7 @@ A prehistory for $\mathbf{u}(t)$ and $\mathrm{d}\mathbf{u}/\mathrm{d}t$ must be specified over ```math -t \in [t_0-\tau_{\max},t_0]. +t \in [t_0-\tau_{\max},t_0] ``` Its endpoint value and derivative must match the initialized input at $t_0$. @@ -169,12 +167,12 @@ The delay does not synthesize prehistory. At $t_0$, ```math \begin{aligned} -\mathbf{y}(t_0) +\mathbf{y} &\leftarrow \mathbf{u}(t_0-\boldsymbol{\tau}) \\ -\left.\dfrac{\mathrm{d}\mathbf{y}}{\mathrm{d}t}\right|_{t_0} +\dfrac{\mathrm{d}\mathbf{y}}{\mathrm{d}t} &\leftarrow \left.\dfrac{\mathrm{d}\mathbf{u}}{\mathrm{d}t} - \right|_{t_0-\boldsymbol{\tau}}. + \right|_{t_0-\boldsymbol{\tau}} \end{aligned} ``` diff --git a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md index 2fad25be4..a2a6a7f6e 100644 --- a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md +++ b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -4,6 +4,21 @@ For input units $[u]$, `Propagation` is the $K$-channel current-form propagation operator used by `LineDistributed`. It applies a fitted input factor, one scalar delay per mode, and a fitted output factor while preserving the input units. +```math +\begin{aligned} +\mathbf{H}(s) + &= \sum_{m=1}^M \mathbf{H}^\mathrm{mps}_m(s) \exp(-s\tau_m) +\end{aligned} +``` + +With $`\mathbf{G}_\mathrm{in}`$ and $`\mathbf{G}_\mathrm{out}`$ the transfer matrices +of the input and output factors, + +```math +\mathbf{H}^\mathrm{mps}_m(s) + = \mathbf{G}_\mathrm{out}(s)_{:,m}\,\mathbf{G}_\mathrm{in}(s)_{m,:} +``` + ## Block Diagram ![Propagation operator block diagram](../../../../../../docs/Figures/EMT/Propagation/diagram.png) @@ -51,30 +66,6 @@ $\mathbf{g}_\mathrm{in}$ | Input factor | [VectorFit](../../Rational/VectorFit/R $\mathbf{d}$ | Modal delay bank | [Delay](../Delay/README.md) | History | `delays` | $\mathbb{R}^M$ | $\mathbb{R}^M$ $\mathbf{g}_\mathrm{out}$ | Output factor | [VectorFit](../../Rational/VectorFit/README.md) | $KQ_{\mathbf{g}_\mathrm{out}}$ | `output` | $\mathbb{R}^M$ | $\mathbb{R}^K$ -The offline fitting targets and propagation factorization are - -```math -\begin{aligned} -\mathbf{G}^\mathrm{in}(s) - &\approx \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\ -\mathbf{G}^\mathrm{out}(s) &\approx \mathbf{T}_i(s) \\ -\mathbf{H}^\mathrm{mps}(s) - &= \mathrm{diag}(h_1^\mathrm{mps}(s),\ldots,h_M^\mathrm{mps}(s)) \\ -\mathbf{D}_{\boldsymbol{\tau}}(s) - &= \mathrm{diag}(\exp(-s\tau_1),\ldots,\exp(-s\tau_M)) \\ -\mathbf{H}(s) - &= \mathbf{T}_i(s)\mathbf{D}_{\boldsymbol{\tau}}(s) - \mathbf{H}^\mathrm{mps}(s)\mathbf{T}_i^{-1}(s) \\ - &\approx \mathbf{G}^\mathrm{out}(s)\mathbf{D}_{\boldsymbol{\tau}}(s) - \mathbf{G}^\mathrm{in}(s) -\end{aligned} -``` - -$\mathbf{H}^\mathrm{mps}$ is the diagonal modal minimum-phase-shift propagation -function with the modal delays removed. The current modal transformation -$\mathbf{T}_i$ maps modal currents to phase coordinates, and -$\mathbf{T}_i^{-1}$ maps phase currents to modal coordinates. - ### Submodel Validation Both rational factors must have stable poles and no term linear in $s$. The @@ -138,7 +129,8 @@ None. ## Initialization -TBD +Initialize the rational factors using the [EMT initialization contract](../../../README.md#initialization). +Provide the input-factor output history required by [Delay](../Delay/README.md#initialization). ## Monitors diff --git a/GridKit/Model/PhasorDynamics/Branch/README.md b/GridKit/Model/PhasorDynamics/Branch/README.md index 97256c5aa..a5106957f 100644 --- a/GridKit/Model/PhasorDynamics/Branch/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/README.md @@ -1,38 +1,39 @@ -# **Branch Model** +# Branch The Branch model represents a two-terminal phasor-domain $\pi$ branch with an optional off-nominal tap magnitude and phase shift on bus 1. Terminal current contributions are oriented entering the adjacent buses. -Notes: +## Notes + - Setting $\tau = 1$ and $\theta = 0$ gives the ordinary symmetric transmission-line $\pi$ model. - The total line shunt $G + jB$ is split equally between the two terminals, - while the magnetizing shunt $G_\text{mag} + jB_\text{mag}$ is connected at + while the magnetizing shunt $`G_\mathrm{mag} + jB_\mathrm{mag}`$ is connected at bus 1; both shunts are added outside the $\mathbf{M}$ transformation. - The branch has no solver-owned variables; it contributes current residuals directly to the connected buses. ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note ----------------------|--------|---------|-----------------------------------------|---------------|------ -$R$ | [p.u.] | `R` | Branch series resistance | | -$X$ | [p.u.] | `X` | Branch series reactance | | -$G$ | [p.u.] | `G` | Total line shunt conductance | 0.0 | -$B$ | [p.u.] | `B` | Total line shunt susceptance | 0.0 | -$G_\text{mag}$ | [p.u.] | `Gmag` | Magnetizing shunt conductance at bus 1 | 0.0 | -$B_\text{mag}$ | [p.u.] | `Bmag` | Magnetizing shunt susceptance at bus 1 | 0.0 | -$\tau$ | [p.u.] | `tap` | Off-nominal tap magnitude on bus-1 side | 1.0 | -$\theta$ | [rad] | `phase` | Phase-shift angle | 0.0 | +Symbol | Units | JSON | Description | Typical Value | Note +-----------------|--------|---------|-----------------------------------------|---------------|----- +$R$ | [p.u.] | `R` | Branch series resistance | | +$X$ | [p.u.] | `X` | Branch series reactance | | +$G$ | [p.u.] | `G` | Total line shunt conductance | 0.0 | +$B$ | [p.u.] | `B` | Total line shunt susceptance | 0.0 | +$G_\mathrm{mag}$ | [p.u.] | `Gmag` | Magnetizing shunt conductance at bus 1 | 0.0 | +$B_\mathrm{mag}$ | [p.u.] | `Bmag` | Magnetizing shunt susceptance at bus 1 | 0.0 | +$\tau$ | [p.u.] | `tap` | Off-nominal tap magnitude on bus-1 side | 1.0 | +$\theta$ | [rad] | `phase` | Phase-shift angle | 0.0 | ### Parameter Validation -Invalid Branch parameter sets are rejected by the following checks: +A valid Branch parameter set must satisfy the following conditions: ```math \begin{aligned} - &R, X, G, B, G_\text{mag}, B_\text{mag}, \tau, \theta + &R, X, G, B, G_\mathrm{mag}, B_\mathrm{mag}, \tau, \theta \in \mathbb{R}\ \text{and finite} \\ &R^2 + X^2 > 0 \\ &\tau > 0 @@ -46,7 +47,7 @@ The series, magnetizing shunt, and line shunt admittances are: ```math \begin{aligned} Y_{\mathrm{br}} &= \dfrac{1}{R + jX} \\ - Y_{\mathrm{mag}} &= G_\text{mag} + jB_\text{mag} \\ + Y_{\mathrm{mag}} &= G_\mathrm{mag} + jB_\mathrm{mag} \\ Y_{\mathrm{sh}} &= G + jB \end{aligned} ``` @@ -63,14 +64,14 @@ The series, magnetizing shunt, and line shunt admittance matrices are: & -Y_{\mathrm{br}} \end{bmatrix} \\ - \mathbf{Y}_\text{mag} + \mathbf{Y}_\mathrm{mag} &= \begin{bmatrix} -Y_{\mathrm{mag}} & 0 \\ 0 & 0 \end{bmatrix} \\ - \mathbf{Y}_\text{sh} + \mathbf{Y}_\mathrm{sh} &= \dfrac{1}{2} \begin{bmatrix} @@ -88,7 +89,7 @@ The off-nominal transformer transformation uses bus 1 as the tap side: &= \begin{bmatrix} \tau^{-1} & 0 \\ - 0 & e^{j\theta} + 0 & \exp(j\theta) \end{bmatrix} \end{aligned} ``` @@ -103,14 +104,21 @@ The magnetizing and line shunts are added outside the transformation: \mathbf{Y}_0 \mathbf{M} + - \mathbf{Y}_\text{mag} + \mathbf{Y}_\mathrm{mag} + - \mathbf{Y}_\text{sh} + \mathbf{Y}_\mathrm{sh} \end{aligned} ``` For the equations below, write each entry as $Y_{mn}=G_{mn}+jB_{mn}$. +## Model Ports + +Name | Port | Init | Description +-------|------|-------|----------------------------------------- +`bus1` | Bus | Known | Required bus-1 terminal; the tapped side +`bus2` | Bus | Known | Required bus-2 terminal + ## Model Variables ### Internal Variables @@ -131,20 +139,26 @@ 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 +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 +### Internal Equations + +#### Differential + +None. + +#### Algebraic None. -### Algebraic Equations +### External Equations The branch current relation is $0 = -\mathbf{I} + \mathbf{Y}\mathbf{V}$. @@ -168,24 +182,24 @@ positive sign because branch current is oriented entering the bus. The Branch model has no internal state to initialize. During construction or parameter updates, the component computes $\mathbf{Y}$ from the current -parameter values. Initial terminal current and power monitor values are -evaluated from the connected bus voltages. Parameter verification rejects the -invalid cases listed above. - -## Model Outputs - -Output | Units | Description | Note --------|--------|----------------------------------------------|------ -`ir1` | [p.u.] | Terminal current, real component, bus 1 | Oriented entering bus 1 -`ii1` | [p.u.] | Terminal current, imaginary component, bus 1 | Oriented entering bus 1 -`im1` | [p.u.] | Terminal current magnitude, bus 1 | -`p1` | [p.u.] | Active power at bus 1 terminal | Positive entering bus 1 -`q1` | [p.u.] | Reactive power at bus 1 terminal | Positive entering bus 1 -`ir2` | [p.u.] | Terminal current, real component, bus 2 | Oriented entering bus 2 -`ii2` | [p.u.] | Terminal current, imaginary component, bus 2 | Oriented entering bus 2 -`im2` | [p.u.] | Terminal current magnitude, bus 2 | -`p2` | [p.u.] | Active power at bus 2 terminal | Positive entering bus 2 -`q2` | [p.u.] | Reactive power at bus 2 terminal | Positive entering bus 2 +parameter values. Terminal current and power monitor values are evaluated +from the connected bus voltages when read. Parameter verification enforces the +conditions in [Parameter Validation](#parameter-validation). + +## Monitors + +Monitor | Units | Description | Note +--------|--------|----------------------------------------------|------------------------ +`ir1` | [p.u.] | Terminal current, real component, bus 1 | Oriented entering bus 1 +`ii1` | [p.u.] | Terminal current, imaginary component, bus 1 | Oriented entering bus 1 +`im1` | [p.u.] | Terminal current magnitude, bus 1 | +`p1` | [p.u.] | Active power at bus 1 terminal | Positive entering bus 1 +`q1` | [p.u.] | Reactive power at bus 1 terminal | Positive entering bus 1 +`ir2` | [p.u.] | Terminal current, real component, bus 2 | Oriented entering bus 2 +`ii2` | [p.u.] | Terminal current, imaginary component, bus 2 | Oriented entering bus 2 +`im2` | [p.u.] | Terminal current magnitude, bus 2 | +`p2` | [p.u.] | Active power at bus 2 terminal | Positive entering bus 2 +`q2` | [p.u.] | Reactive power at bus 2 terminal | Positive entering bus 2 Current magnitudes are: diff --git a/GridKit/Model/PhasorDynamics/Bus/README.md b/GridKit/Model/PhasorDynamics/Bus/README.md index f86c89934..f012aa5c4 100644 --- a/GridKit/Model/PhasorDynamics/Bus/README.md +++ b/GridKit/Model/PhasorDynamics/Bus/README.md @@ -1,20 +1,16 @@ -# Bus Model +# Bus -A bus is a point of interconnection of electrical devices. The bus component -model also plays a key role in coupling system components. Each bus $k$ owns -two variables: real voltage and imaginary voltage, denoted as $V_{rk}$ and -$V_{ik}$, respectively. The bus also owns current-balance residual equations for -real and imaginary currents entering the bus, denoted as $I_{rk}$ and $I_{ik}$, -respectively. While the bus model owns current residuals, it _does not compute_ -them. Instead, each component connected to the bus adds its contribution to the -residual. The bus initializes the residual to zero each time the numerical -integrator requests residual evaluation. +A bus owns the terminal voltage components $V_r$ and $V_i$ and the +current-balance residuals. Each connected device adds its current injection +after the bus resets the residuals to zero. -## Sign Convention +## Notes Current entering the bus has positive sign, and current exiting the bus has negative sign. +## Block Diagram + ![](../../../../docs/Figures/bus_variables.jpg) Figure 1: Bus-variable diagram. This should be updated to represent current @@ -22,9 +18,90 @@ balance instead of power balance. ## Model Parameters -Buses are uniquely identified by their numeric bus ID. Each bus has an -associated nominal voltage. +Symbol | Units | JSON | Description | Typical Value | Note +------------------|-------|------|---------------------|---------------|------- +$V_\mathrm{base}$ | [kV] | `kv` | Nominal bus voltage | | Unused + +### Parameter Validation + +None. + +### Model Derived Parameters + +None. + +## Model Ports + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------|--------|----------------------------------|----- +$V_r$ | [p.u.] | Bus voltage, real component | +$V_i$ | [p.u.] | Bus voltage, imaginary component | + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Internal Equations + +#### Differential + +None. + +#### Algebraic + +Let $\mathcal{D}$ denote the set of components connected to the bus. + +```math +\begin{aligned} +0 &= \sum_{d \in \mathcal{D}} I_{r,d} \\ +0 &= \sum_{d \in \mathcal{D}} I_{i,d} +\end{aligned} +``` + +### External Equations + +None. + +## Initialization + +### Internal Initialization + +Bus initializes its algebraic voltage variables as + +```math +\begin{aligned} +V_r &\leftarrow \text{bus voltage, real component} \\ +V_i &\leftarrow \text{bus voltage, imaginary component} +\end{aligned} +``` + +The derivative vector entries initialize to zero. + +## Monitors -Symbol | Units | JSON | Description ---------------------|-------|------|------------ -$V_\mathrm{base}$ | [kV] | `kv` | Nominal bus voltage +Monitor | Units | Description | Note +--------|--------|---------------------------------|----- +`Vr` | [p.u.] | Bus voltage, real component | +`Vi` | [p.u.] | Bus voltage, imaginary component | +`Vm` | [p.u.] | Bus voltage magnitude | $\sqrt{V_r^2+V_i^2}$ +`Va` | [rad] | Bus voltage angle | $\operatorname{atan2}(V_i,V_r)$ diff --git a/GridKit/Model/PhasorDynamics/BusFault/README.md b/GridKit/Model/PhasorDynamics/BusFault/README.md index 3576df850..7c701a73c 100644 --- a/GridKit/Model/PhasorDynamics/BusFault/README.md +++ b/GridKit/Model/PhasorDynamics/BusFault/README.md @@ -1,29 +1,40 @@ -# Bus Fault +# BusFault 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. +Symbol | Units | JSON | Description | Typical Value | Note +-------|-----------|----------|----------------------|---------------|----------------------------------------------------------------------------------- +$R$ | [p.u.] | `R` | Fault resistance | | +$X$ | [p.u.] | `X` | Fault reactance | | +$U$ | [boolean] | `state0` | Initial fault status | | JSON boolean; `true` puts the fault on. Changed at run time through `setStatus()`. + +### Parameter Validation + +None. ### Model Derived Parameters -``` math +```math \begin{aligned} G &=\dfrac{R}{R^2+ X^2} \\ B &= -\dfrac{X}{R^2 + X^2}\\ \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +-----------------|-------|-------|------------ +`bus` | Bus | Known | Required bus where the fault is applied +`control_signal` | Input | N/A | Accepted by the parser but not read by the model; fault status is set through `state0` and `setStatus()` ## Model Variables ### Internal Variables #### Differential + None. #### Algebraic @@ -33,28 +44,65 @@ 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 +### Internal Equations + +#### Differential + None. -### Algebraic Equations -``` math +#### Algebraic + +```math \begin{aligned} -0 &= -I_{r} + U (-G V_{r} + B V_{i}) \\ -0 &= -I_{i} + U (-B V_{r} - G V_{i}) +0 &= -I_r + U (-G V_r + B V_i) \\ +0 &= -I_i + U (-B V_r - G V_i) \end{aligned} ``` + +### External Equations + +The fault currents are added to the connected bus residuals: + +```math +\begin{aligned} +I_r^{\mathrm{bus}} &\leftarrow I_r^{\mathrm{bus}} + I_r \\ +I_i^{\mathrm{bus}} &\leftarrow I_i^{\mathrm{bus}} + I_i +\end{aligned} +``` + +## Initialization + +The initial fault status and bus voltage determine the terminal currents: + +```math +\begin{aligned} +U &\leftarrow \text{initial fault status} \\ +I_r &\leftarrow U(-GV_r+BV_i) \\ +I_i &\leftarrow U(-BV_r-GV_i) +\end{aligned} +``` + +The derivative vector entries initialize to zero. + +## Monitors + +Monitor | Units | Description | Note +--------|----------|-------------------------------------------|----- +`state` | [binary] | Fault status | `1` when on; `0` when off +`ir` | [p.u.] | Fault-current real component | Added to the connected-bus residual +`ii` | [p.u.] | Fault-current imaginary component | Added to the connected-bus residual diff --git a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md index d618c6323..36accb060 100644 --- a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md +++ b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md @@ -1,20 +1,84 @@ -# Bus-to-Signal Adapter +# BusToSignalAdapter -This component enables signals to send and receive bus variables. It has five -ports: +This component enables signals to send and receive bus variables. -## Bus Port -- `bus` for the bus whose variables are managed by the adapter +## Model Parameters -## Input Ports -- `ir` ($I_r$) -- `ii` ($I_i$) +None. -External current injections are read from input signal nodes added to currents -on the bus. +### Parameter Validation -## Output Ports -- `vr` ($V_r$) -- `vi` ($V_i$) +None. -Voltages read from the bus are made available to signal nodes. +### Model Derived Parameters + +None. + +## Model Ports + +Name | Port | Init | Description +------|--------|-------|----------------------------------------------- +`bus` | Bus | Known | Bus whose variables are managed by the adapter +`ir` | Input | Known | Real current contribution to the bus +`ii` | Input | Known | Imaginary current contribution to the bus +`vr` | Output | Known | Bus voltage, real component +`vi` | Output | Known | Bus voltage, imaginary component + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------|--------|-------------------------------------------|--------------------------------------- +$V_r$ | [p.u.] | Bus-voltage real component | Bus-owned value published through `vr` +$V_i$ | [p.u.] | Bus-voltage imaginary component | Bus-owned value published through `vi` +$I_r$ | [p.u.] | Real current contribution to the bus | Read from the optional `ir` input +$I_i$ | [p.u.] | Imaginary current contribution to the bus | Read from the optional `ii` input + +## Model Equations + +### Internal Equations + +#### Differential + +None. + +#### Algebraic + +None. + +### External Equations + +Each attached current input is added to the corresponding connected-bus +residual: + +```math +\begin{aligned} +I_r^{\mathrm{bus}} &\leftarrow I_r^{\mathrm{bus}} + I_r \\ +I_i^{\mathrm{bus}} &\leftarrow I_i^{\mathrm{bus}} + I_i +\end{aligned} +``` + +## Initialization + +None. + +## Monitors + +None. diff --git a/GridKit/Model/PhasorDynamics/Controller/README.md b/GridKit/Model/PhasorDynamics/Controller/README.md index aac18d485..1d27b0572 100644 --- a/GridKit/Model/PhasorDynamics/Controller/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/README.md @@ -1,11 +1,9 @@ -# **Controller Models** +# Controller Models -## Introduction - -Controller models produce command signals for dynamic device models without -directly contributing to the network equations. +Controllers produce command signals for dynamic devices. ## Types -- Renewable Energy Electrical Control Model REECB (See [REECB](REECB/README.md)) -- Renewable Energy Plant Control Model REPCA (See [REPCA](REPCA/README.md)) +- [REECA](REECA/README.md): Renewable energy electrical control +- [REECB](REECB/README.md): Renewable energy electrical control +- [REPCA](REPCA/README.md): Renewable energy plant control diff --git a/GridKit/Model/PhasorDynamics/Controller/REECA/README.md b/GridKit/Model/PhasorDynamics/Controller/REECA/README.md new file mode 100644 index 000000000..9147d3a4c --- /dev/null +++ b/GridKit/Model/PhasorDynamics/Controller/REECA/README.md @@ -0,0 +1,407 @@ +# REECA + +REECA is a WECC renewable energy electrical control model for inverter-coupled resources. In GridKit it is represented as a signal-control model that computes active- and reactive-current commands. + +> [!WARNING] +> Post-dip reactive-current injection and active-current limit holds require +> timer/history states that are not modeled. $T_{\mathrm{hld}}$ and +> $T_{\mathrm{hld2}}$ must be zero: $I_{\mathrm{qinj}}^{\mathrm{frz}}$ is unused, +> and $I_{\mathrm{p}}^{\max}$ is recalculated from VDL2 and current-circle logic +> at each residual evaluation instead of held after voltage recovery. + +## Notes + +- Internal electrical quantities and current commands are on model base unless otherwise stated. +- Optional signal inputs default to their documented constant values when omitted. + +## Block Diagram + +![](../../../../../docs/Figures/PhasorDynamics_REECA_Diagram.png) + +Figure 1: REECA block diagram. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) + +## Model Parameters + +Symbol | Units | JSON | Description | Typical Value | Note +-----------------------------------|----------|------|----------------------------------------------------------------------|---------------|--------------------------------------------------------------------------- +$S^{\mathrm{base}}$ | [MVA] | TBD | REECA model power base | TBD | Source label: `MVABase` +$s_{\mathrm{pf}}$ | [binary] | TBD | Power-factor control flag | TBD | Source label: `PfFlag`; 1 = power-factor control, 0 = Q control +$s_V$ | [binary] | TBD | Voltage-control mode flag | TBD | Source label: `VFlag`; 1 = Q control, 0 = voltage control +$s_Q$ | [binary] | TBD | Reactive-power control flag | TBD | Source label: `QFlag`; 1 = voltage/Q control, 0 = constant pf or Q control +$s_P$ | [binary] | TBD | Active-power reference speed-multiplier flag | TBD | Source label: `Pflag`; 1 = multiply by generator speed +$s_\mathrm{PQ}$ | [binary] | TBD | P/Q priority flag for converter current limit | TBD | Source label: `Pqflag`; 0 = Q priority, 1 = P priority +$T_{\mathrm{rv}}$ | [s] | TBD | Voltage-measurement filter time constant | TBD | Source label: `Trv`; if zero, $V_{\mathrm{meas}}$ is algebraic +$T_{\mathrm{p}}$ | [s] | TBD | Electrical-power measurement filter time constant | TBD | Source label: `Tp`; if zero, $P_{\mathrm{meas}}$ is algebraic +$V_{\mathrm{ref0}}$ | [p.u.] | TBD | Outer-loop voltage reference | TBD | Source label: `Vref0`; initialized to terminal voltage if omitted +$V_{\mathrm{dip}}$ | [p.u.] | TBD | Low-voltage threshold for reactive-current injection logic | TBD | Source label: `Vdip` +$V_{\mathrm{up}}$ | [p.u.] | TBD | High-voltage threshold for reactive-current injection logic | TBD | Source label: `Vup` +$D_{\mathrm{bd1}}$ | [p.u.] | TBD | Overvoltage deadband for voltage-error response | TBD | Source label: `dbd1` +$D_{\mathrm{bd2}}$ | [p.u.] | TBD | Undervoltage deadband for voltage-error response | TBD | Source label: `dbd2` +$K_{\mathrm{qv}}$ | [p.u.] | TBD | Reactive-current injection gain during voltage dip/overvoltage logic | TBD | Source label: `kqv` +$I_{\mathrm{qinj}}^{\min}$ | [p.u.] | TBD | Minimum reactive-current injection limit | TBD | Source label: `Iql1` +$I_{\mathrm{qinj}}^{\max}$ | [p.u.] | TBD | Maximum reactive-current injection limit | TBD | Source label: `Iqh1` +$I_{\mathrm{qinj}}^{\mathrm{frz}}$ | [p.u.] | TBD | Held reactive-current injection value after voltage dip | TBD | Source label: `Iqfrz`; unused when $T_{\mathrm{hld}} = 0$ +$T_{\mathrm{hld}}$ | [s] | TBD | Reactive-current injection hold time after voltage dip clears | TBD | Source label: `Thld`; required to be zero in this version +$Q^{\max}$ | [p.u.] | TBD | Maximum reactive-power control limit | TBD | Source label: `Qmax` +$Q^{\min}$ | [p.u.] | TBD | Minimum reactive-power control limit | TBD | Source label: `Qmin` +$K_{\mathrm{qp}}$ | [p.u.] | TBD | Reactive-power control proportional gain | TBD | Source label: `Kqp` +$K_{\mathrm{qi}}$ | [p.u./s] | TBD | Reactive-power control integral gain | TBD | Source label: `Kqi` +$V^{\max}$ | [p.u.] | TBD | Maximum voltage-control limit | TBD | Source label: `Vmax` +$V^{\min}$ | [p.u.] | TBD | Minimum voltage-control limit | TBD | Source label: `Vmin` +$V_{\mathrm{ref1}}$ | [p.u.] | TBD | Inner-loop voltage-control reference/bias | 0 | Source label: `Vref1` +$K_{\mathrm{vp}}$ | [p.u.] | TBD | Voltage-control proportional gain | TBD | Source label: `Kvp` +$K_{\mathrm{vi}}$ | [p.u./s] | TBD | Voltage-control integral gain | TBD | Source label: `Kvi` +$T_{\mathrm{iq}}$ | [s] | TBD | Reactive-current command lag time constant | TBD | Source label: `Tiq` +$T_{\mathrm{pord}}$ | [s] | TBD | Active-power order filter time constant | TBD | Source label: `Tpord` +$R_P^{\max}$ | [p.u./s] | TBD | Positive active-power order ramp-rate limit | TBD | Source label: `dPmax` +$R_P^{\min}$ | [p.u./s] | TBD | Negative active-power order ramp-rate limit | TBD | Source label: `dPmin` +$P^{\max}$ | [p.u.] | TBD | Maximum active-power order limit | TBD | Source label: `Pmax` +$P^{\min}$ | [p.u.] | TBD | Minimum active-power order limit | TBD | Source label: `Pmin` +$I^{\max}$ | [p.u.] | TBD | Maximum total converter current | TBD | Source label: `Imax` +$V_{\mathrm{q},1}$ | [p.u.] | TBD | VDL1 voltage point 1 | TBD | Source label: `vq1` +$I_{\mathrm{q},1}^{\max}$ | [p.u.] | TBD | VDL1 reactive-current limit point 1 | TBD | Source label: `lq1` +$V_{\mathrm{q},2}$ | [p.u.] | TBD | VDL1 voltage point 2 | TBD | Source label: `vq2` +$I_{\mathrm{q},2}^{\max}$ | [p.u.] | TBD | VDL1 reactive-current limit point 2 | TBD | Source label: `lq2` +$V_{\mathrm{q},3}$ | [p.u.] | TBD | VDL1 voltage point 3 | TBD | Source label: `vq3` +$I_{\mathrm{q},3}^{\max}$ | [p.u.] | TBD | VDL1 reactive-current limit point 3 | TBD | Source label: `lq3` +$V_{\mathrm{q},4}$ | [p.u.] | TBD | VDL1 voltage point 4 | TBD | Source label: `vq4` +$I_{\mathrm{q},4}^{\max}$ | [p.u.] | TBD | VDL1 reactive-current limit point 4 | TBD | Source label: `lq4` +$V_{\mathrm{p},1}$ | [p.u.] | TBD | VDL2 voltage point 1 | TBD | Source label: `vp1` +$I_{\mathrm{p},1}^{\max}$ | [p.u.] | TBD | VDL2 active-current limit point 1 | TBD | Source label: `lp1` +$V_{\mathrm{p},2}$ | [p.u.] | TBD | VDL2 voltage point 2 | TBD | Source label: `vp2` +$I_{\mathrm{p},2}^{\max}$ | [p.u.] | TBD | VDL2 active-current limit point 2 | TBD | Source label: `lp2` +$V_{\mathrm{p},3}$ | [p.u.] | TBD | VDL2 voltage point 3 | TBD | Source label: `vp3` +$I_{\mathrm{p},3}^{\max}$ | [p.u.] | TBD | VDL2 active-current limit point 3 | TBD | Source label: `lp3` +$V_{\mathrm{p},4}$ | [p.u.] | TBD | VDL2 voltage point 4 | TBD | Source label: `vp4` +$I_{\mathrm{p},4}^{\max}$ | [p.u.] | TBD | VDL2 active-current limit point 4 | TBD | Source label: `lp4` +$T_{\mathrm{hld2}}$ | [s] | TBD | Active-current limit hold time after voltage dip clears | TBD | Source label: `Thld2`; required to be zero in this version + +JSON parameter names are not yet specified. + +### Parameter Validation + +A valid REECA parameter set must satisfy the following conditions: + +```math +\begin{aligned} + &S^{\mathrm{base}} > 0 \\ + &s_{\mathrm{pf}}, s_V, s_Q, s_P, s_\mathrm{PQ} \in \{0,1\} \\ + &T_{\mathrm{rv}}, T_{\mathrm{p}} \ge 0 \\ + &0 \le V_{\mathrm{dip}} < V_{\mathrm{up}} \\ + &D_{\mathrm{bd1}} \le 0 \le D_{\mathrm{bd2}} \\ + &I_{\mathrm{qinj}}^{\min} \le I_{\mathrm{qinj}}^{\max} \\ + &T_{\mathrm{hld}} = T_{\mathrm{hld2}} = 0 \\ + &Q^{\min} \le Q^{\max} \\ + &V^{\min} \le V^{\max} \\ + &T_{\mathrm{iq}}, T_{\mathrm{pord}} > 0 \\ + &R_P^{\min} < 0 < R_P^{\max} \\ + &P^{\min} \le P^{\max} \\ + &I^{\max} \ge 0 \\ + &0 \le V_{\mathrm{q},1} < V_{\mathrm{q},2} < V_{\mathrm{q},3} < V_{\mathrm{q},4} \\ + &I_{\mathrm{q},k}^{\max} \ge 0\ \text{for } k=1,\ldots,4 \\ + &0 \le V_{\mathrm{p},1} < V_{\mathrm{p},2} < V_{\mathrm{p},3} < V_{\mathrm{p},4} \\ + &I_{\mathrm{p},k}^{\max} \ge 0\ \text{for } k=1,\ldots,4 +\end{aligned} +``` + +### Model Derived Parameters + +The off-mode flag complements are: + +```math +\begin{aligned} + s_{\mathrm{pf}}^{\mathrm{off}} &= 1 - s_{\mathrm{pf}} \\ + s_V^{\mathrm{off}} &= 1 - s_V \\ + s_Q^{\mathrm{off}} &= 1 - s_Q \\ + s_\mathrm{PQ}^{\mathrm{off}} &= 1 - s_\mathrm{PQ} +\end{aligned} +``` + +The VDL functions use GridKit's smooth [Linear Segment](../../../../CommonMath.md#linear-segment) helper and provide flat extrapolation outside the first and fourth voltage points: + +```math +\begin{aligned} + g_q(x) &= + I_{\mathrm{q},1}^{\max} + + \sum_{k=1}^{3} + \text{linseg}\!( + x;\, + V_{\mathrm{q},k},\, + V_{\mathrm{q},k+1},\, + I_{\mathrm{q},k+1}^{\max} - I_{\mathrm{q},k}^{\max} + ) \\ + g_p(x) &= + I_{\mathrm{p},1}^{\max} + + \sum_{k=1}^{3} + \text{linseg}\!( + x;\, + V_{\mathrm{p},k},\, + V_{\mathrm{p},k+1},\, + I_{\mathrm{p},k+1}^{\max} - I_{\mathrm{p},k}^{\max} + ) +\end{aligned} +``` + +## Model Ports + +Name | Port | Init | Description +----------|--------|------|------------ +`bus` | Bus | TBD | Terminal-bus voltage +`speed` | Input | TBD | Generator speed deviation +`pe` | Input | TBD | Electrical active-power feedback +`qgen` | Input | TBD | Reactive-power feedback +`qext` | Input | TBD | External reactive-power command +`pfaref` | Input | TBD | Power-factor angle reference +`pref` | Input | TBD | Active-power reference +`iqcmd` | Output | TBD | Reactive-current command +`ipcmd` | Output | TBD | Active-current command + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +--------------------|--------|------------------------------------|------------------------------------------------------------------------------- +$V_{\mathrm{meas}}$ | [p.u.] | Filtered terminal voltage | State 1 in Fig. 1; Source label: `Vmeas`; algebraic when $T_{\mathrm{rv}} = 0$ +$P_{\mathrm{meas}}$ | [p.u.] | Filtered electrical power | State 2 in Fig. 1; Source label: `Pmeas`; algebraic when $T_{\mathrm{p}} = 0$ +$x_{\mathrm{PIQ}}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1; Source label: `PIQ` +$x_{\mathrm{PIV}}$ | [p.u.] | Voltage PI controller state | State 4 in Fig. 1; Source label: `PIV` +$Q_V$ | [p.u.] | Reactive-current command lag state | State 5 in Fig. 1; Source label: `Q_V` +$P_{\mathrm{ord}}$ | [p.u.] | Filtered active-power order | State 6 in Fig. 1; Source label: `Pord` + +#### Algebraic + +Symbol | Units | Description | Note +--------------------------------|--------|-------------------------------------|------ +$V_T$ | [p.u.] | Terminal voltage magnitude | +$V_{\mathrm{meas}}^{\mathrm{safe}}$ | [p.u.] | Safe filtered terminal voltage for divider blocks | Lower bounded by 0.01 +$s_{\mathrm{dip}}$ | [binary] | Voltage-dip/overvoltage freeze indicator | 1 when outside voltage thresholds +$V_{\mathrm{err}}$ | [p.u.] | Deadbanded voltage error | Defined by CommonMath `deadband2` +$I_{\mathrm{qv}}$ | [p.u.] | Reactive-current injection candidate | Converter base +$Q_{\mathrm{ref}}$ | [p.u.] | Selected reactive-power reference | From power-factor or external reactive-power command +$e_Q$ | [p.u.] | Reactive-power control error | Limited $Q_{\mathrm{ref}}$ minus $Q_{\mathrm{gen}}$ +$V_{\mathrm{PIQ}}$ | [p.u.] | Reactive-power control PI output | Limited by $V^{\min}$ and $V^{\max}$ +$e_{\mathrm{PIV}}$ | [p.u.] | Voltage-control PI error | Selected voltage-control signal minus $V_{\mathrm{meas}}$ +$f_{\mathrm{pord}}$ | [p.u./s] | Active-power order derivative before ramp-rate limiting | Feeds $r_{\mathrm{pord}}$ +$r_{\mathrm{pord}}$ | [p.u./s] | Ramp-rate-limited active-power order derivative | Feeds $P_{\mathrm{ord}}$ anti-windup +$I_{\mathrm{q}}^{\mathrm{circ}}$ | [p.u.] | Reactive-current limit from converter current circle | Converter base; nonnegative algebraic branch +$I_{\mathrm{p}}^{\mathrm{circ}}$ | [p.u.] | Active-current limit from converter current circle | Converter base; nonnegative algebraic branch +$I_{\mathrm{q}}^{\max}$ | [p.u.] | Final reactive-current upper limit | Converter base; updated by VDL1 and current-limit logic +$I_{\mathrm{p}}^{\max}$ | [p.u.] | Final active-current upper limit | Converter base; updated by VDL2 and current-limit logic +$I_{\mathrm{qbase}}$ | [p.u.] | Base reactive-current command | Converter base; before $s_Q$ selection and reactive-current injection +$I_{\mathrm{q}}^{\mathrm{raw}}$ | [p.u.] | Raw reactive-current command before final limit | Converter base +$I_{\mathrm{q}}^{\mathrm{cmd}}$ | [p.u.] | Reactive-current command output | Converter base +$I_{\mathrm{p}}^{\mathrm{cmd}}$ | [p.u.] | Active-current command output | Converter base + +### External Variables + +#### Differential + +Symbol | Units | Description | Note +-----------|--------|-------------------------|------ +$\omega$ | [p.u.] | Generator speed deviation | Optional, defaults to zero; source diagram $\omega_\mathrm{g} = 1 + \omega$ + +#### 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 +$P_\mathrm{e}$ | [p.u.] | Electrical active power | Source label: `Pe` +$Q_{\mathrm{gen}}$ | [p.u.] | Reactive-power feedback | Source label: `Qgen` +$Q_{\mathrm{ext}}$ | [p.u.] | External reactive-power command | Optional, defaults to initialized constant +$\phi_{\mathrm{pf}}^{\mathrm{ref}}$ | [rad] | Power-factor angle reference | Source label: `pfaref`; used through tangent block +$P_{\mathrm{ref}}$ | [p.u.] | External active-power reference | Optional, defaults to initialized constant + +## Model Equations + +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband2`](../../../../CommonMath.md#type-ii-deadband), [`max`](../../../../CommonMath.md#maximum), [`min`](../../../../CommonMath.md#minimum), [`outside`](../../../../CommonMath.md#outside). + +For readability, define: + +```math +\begin{aligned} + f_{\mathrm{PIQ}} &= K_{\mathrm{qi}} e_Q \\ + f_{\mathrm{PIV}} &= K_{\mathrm{vi}} e_{\mathrm{PIV}} +\end{aligned} +``` + +### Internal Equations + +#### Differential + +```math +\begin{aligned} + 0 &= -T_{\mathrm{rv}}\dot V_{\mathrm{meas}} - V_{\mathrm{meas}} + V_T \\ + 0 &= -T_{\mathrm{p}}\dot P_{\mathrm{meas}} - P_{\mathrm{meas}} + P_\mathrm{e} \\ + 0 &= + -\dot x_{\mathrm{PIQ}} + + (1 - s_{\mathrm{dip}}) + \text{antiwindup}\!( + V_{\mathrm{PIQ}}, + f_{\mathrm{PIQ}}; + V^{\min}, + V^{\max} + ) \\ + 0 &= + -\dot x_{\mathrm{PIV}} + + (1 - s_{\mathrm{dip}}) + \text{antiwindup}\!( + I_{\mathrm{qbase}}, + f_{\mathrm{PIV}}; + -I_{\mathrm{q}}^{\max}, + I_{\mathrm{q}}^{\max} + ) \\ + 0 &= + -T_{\mathrm{iq}}\dot Q_V + - (1 - s_{\mathrm{dip}})Q_V + + (1 - s_{\mathrm{dip}})Q_{\mathrm{ref}}/V_{\mathrm{meas}}^{\mathrm{safe}} \\ + 0 &= + -\dot P_{\mathrm{ord}} + + (1 - s_{\mathrm{dip}}) + \text{antiwindup}\!( + P_{\mathrm{ord}}, + r_{\mathrm{pord}}; + P^{\min}, + P^{\max} + ) +\end{aligned} +``` + +#### Algebraic + +```math +\begin{aligned} + 0 &= -V_T^2 + V_\mathrm r^2 + V_\mathrm i^2 \\ + 0 &= -V_\mathrm{meas}^\mathrm{safe} + \max(V_\mathrm{meas}, 0.01) \\ + 0 &= -s_\mathrm{dip} + \text{outside}(V_T; V_\mathrm{dip}, V_\mathrm{up}) \\ + 0 &= -V_\mathrm{err} + \text{deadband2}(V_\mathrm{ref0} - V_\mathrm{meas}; D_\mathrm{bd1}, D_\mathrm{bd2}) \\ + 0 &= -I_\mathrm{qv} + \text{clamp}(K_\mathrm{qv} V_\mathrm{err}; I_\mathrm{qinj}^{\min}, I_\mathrm{qinj}^{\max}) \\ + 0 &= -Q_\mathrm{ref} + + s_\mathrm{pf} P_\mathrm{meas}\tan(\phi_\mathrm{pf}^\mathrm{ref}) + + s_\mathrm{pf}^\mathrm{off} Q_\mathrm{ext} \\ + 0 &= -e_Q + \text{clamp}(Q_\mathrm{ref}; Q^{\min}, Q^{\max}) - Q_\mathrm{gen} \\ + 0 &= -V_\mathrm{PIQ} + \text{clamp}(K_\mathrm{qp} e_Q + x_\mathrm{PIQ}; V^{\min}, V^{\max}) \\ + 0 &= -e_\mathrm{PIV} + s_V V_\mathrm{PIQ} + s_V^\mathrm{off}(Q_\mathrm{ref} + V_\mathrm{ref1}) - V_\mathrm{meas} \\ + 0 &= -T_\mathrm{pord} f_\mathrm{pord} + (1 + s_P\omega)P_\mathrm{ref} - P_\mathrm{ord} \\ + 0 &= -r_\mathrm{pord} + \text{clamp}(f_\mathrm{pord}; R_P^{\min}, R_P^{\max}) +\end{aligned} +``` + +```math +\begin{aligned} + 0 &= -{I_\mathrm{q}^\mathrm{circ}}^2 + (I^{\max})^2 - s_\mathrm{PQ}(I_\mathrm{p}^\mathrm{cmd})^2 \\ + 0 &= -{I_\mathrm{p}^\mathrm{circ}}^2 + (I^{\max})^2 - s_\mathrm{PQ}^\mathrm{off}(I_\mathrm{q}^\mathrm{cmd})^2 \\ + 0 &= -I_\mathrm{q}^{\max} + \text{min}(g_q(V_\mathrm{meas}), I_\mathrm{q}^\mathrm{circ}) \\ + 0 &= -I_\mathrm{p}^{\max} + \text{min}(g_p(V_\mathrm{meas}), I_\mathrm{p}^\mathrm{circ}) \\ + 0 &= -I_\mathrm{qbase} + \text{clamp}(K_\mathrm{vp} e_\mathrm{PIV} + x_\mathrm{PIV}; -I_\mathrm{q}^{\max}, I_\mathrm{q}^{\max}) \\ + 0 &= -I_\mathrm{q}^\mathrm{raw} + s_Q I_\mathrm{qbase} + s_Q^\mathrm{off} Q_V + s_\mathrm{dip} I_\mathrm{qv} \\ + 0 &= -I_\mathrm{q}^\mathrm{cmd} + \text{clamp}(I_\mathrm{q}^\mathrm{raw}; -I_\mathrm{q}^{\max}, I_\mathrm{q}^{\max}) \\ + 0 &= -I_\mathrm{p}^\mathrm{cmd} + \text{clamp}(P_\mathrm{ord}/V_\mathrm{meas}^\mathrm{safe}; 0, I_\mathrm{p}^{\max}) +\end{aligned} +``` + +The $V_T$, $I_{\mathrm{q}}^{\mathrm{circ}}$, and $I_{\mathrm{p}}^{\mathrm{circ}}$ variables use nonnegative branches of squared algebraic residuals. + +### External Equations + +None. + +## Initialization + +All internal derivatives initialize to zero. Omitted optional signals use the following constants: + +```math +\begin{aligned} + V_T &\leftarrow \sqrt{V_r^2 + V_i^2} \\ + \omega &\leftarrow 0,\quad \text{if omitted} \\ + Q_{\mathrm{ext}} &\leftarrow Q_{\mathrm{gen}},\quad \text{if omitted} \\ + P_{\mathrm{ref}} &\leftarrow \dfrac{P_{\mathrm{e}}}{1+s_P\omega},\quad \text{if omitted} +\end{aligned} +``` + +Connected optional signals use their supplied initial values; if only some are omitted, compute the omitted constants with the connected initial values. Inconsistent supplied commands require a residual solve or initialization rejection. + +If $V_{\mathrm{ref0}}$ is omitted, set $V_{\mathrm{ref0}}\leftarrow V_T$. + +```math +\begin{aligned} + V_{\mathrm{meas}} &\leftarrow V_T \\ + P_{\mathrm{meas}} &\leftarrow P_{\mathrm{e}} +\end{aligned} +``` + +Then evaluate the upstream algebraic chain: + +```math +\begin{aligned} + V_{\mathrm{meas}}^{\mathrm{safe}} &\leftarrow \text{max}(V_{\mathrm{meas}}, 0.01) \\ + s_{\mathrm{dip}} &\leftarrow \text{outside}(V_T; V_{\mathrm{dip}}, V_{\mathrm{up}}) \\ + V_{\mathrm{err}} &\leftarrow \text{deadband2}(V_{\mathrm{ref0}} - V_{\mathrm{meas}}; D_{\mathrm{bd1}}, D_{\mathrm{bd2}}) \\ + I_{\mathrm{qv}} &\leftarrow \text{clamp}(K_{\mathrm{qv}} V_{\mathrm{err}}; I_{\mathrm{qinj}}^{\min}, I_{\mathrm{qinj}}^{\max}) \\ + Q_{\mathrm{ref}} &\leftarrow s_{\mathrm{pf}} P_{\mathrm{meas}}\tan(\phi_{\mathrm{pf}}^{\mathrm{ref}}) + s_{\mathrm{pf}}^{\mathrm{off}} Q_{\mathrm{ext}} \\ + e_Q &\leftarrow \text{clamp}(Q_{\mathrm{ref}}; Q^{\min}, Q^{\max}) - Q_{\mathrm{gen}} \\ + Q_V &\leftarrow \dfrac{Q_{\mathrm{ref}}}{V_{\mathrm{meas}}^{\mathrm{safe}}} \\ + P_{\mathrm{ord}} &\leftarrow (1+s_P\omega)P_{\mathrm{ref}} +\end{aligned} +``` + +The PI states must satisfy: + +```math +\begin{aligned} + 0 &= -V_{\mathrm{PIQ}} + \text{clamp}(K_{\mathrm{qp}} e_Q + x_{\mathrm{PIQ}}; V^{\min}, V^{\max}) \\ + 0 &= -e_{\mathrm{PIV}} + s_V V_{\mathrm{PIQ}} + s_V^{\mathrm{off}}(Q_{\mathrm{ref}} + V_{\mathrm{ref1}}) - V_{\mathrm{meas}} +\end{aligned} +``` + +An unsaturated start requires $e_Q=0$ and $e_{\mathrm{PIV}}=0$. +When $s_V=1$, set $V_{\mathrm{PIQ}}\leftarrow V_{\mathrm{meas}}$; when +$s_V=0$, the supplied $Q_{\mathrm{ref}}+V_{\mathrm{ref1}}$ must equal +$V_{\mathrm{meas}}$. Then +$x_{\mathrm{PIQ}}\leftarrow V_{\mathrm{PIQ}}-K_{\mathrm{qp}}e_Q$. +Saturated starts require a solve against the anti-windup residuals. + +Finish by evaluating $g_q(V_{\mathrm{meas}})$, $g_p(V_{\mathrm{meas}})$, and the current-limit and current-command algebraic residuals in priority order. At the command steps, use the power-flow current targets before final limiting: + +```math +\begin{aligned} + I_{\mathrm{qbase}}^{\star} &\leftarrow \dfrac{Q_{\mathrm{gen}}}{V_{\mathrm{meas}}^{\mathrm{safe}}} \\ + I_{\mathrm{p}}^{\star} &\leftarrow \dfrac{P_{\mathrm{ord}}}{V_{\mathrm{meas}}^{\mathrm{safe}}} +\end{aligned} +``` + +Evaluate current limits and commands in this order: + +- $s_\mathrm{PQ}=0$: $I_{\mathrm{q}}^{\mathrm{circ}}$, $I_{\mathrm{q}}^{\max}$, $I_{\mathrm{qbase}}$, $I_{\mathrm{q}}^{\mathrm{raw}}$, $I_{\mathrm{q}}^{\mathrm{cmd}}$, $I_{\mathrm{p}}^{\mathrm{circ}}$, $I_{\mathrm{p}}^{\max}$, $I_{\mathrm{p}}^{\mathrm{cmd}}$. +- $s_\mathrm{PQ}=1$: $I_{\mathrm{p}}^{\mathrm{circ}}$, $I_{\mathrm{p}}^{\max}$, $I_{\mathrm{p}}^{\mathrm{cmd}}$, $I_{\mathrm{q}}^{\mathrm{circ}}$, $I_{\mathrm{q}}^{\max}$, $I_{\mathrm{qbase}}$, $I_{\mathrm{q}}^{\mathrm{raw}}$, $I_{\mathrm{q}}^{\mathrm{cmd}}$. + +After $I_{\mathrm{q}}^{\max}$ and $I_{\mathrm{qbase}}$ are known, initialize the voltage PI state: + +```math +x_{\mathrm{PIV}} \leftarrow I_{\mathrm{qbase}} - K_{\mathrm{vp}} e_{\mathrm{PIV}} +``` + +The current-circle variables use the nonnegative branch of the squared algebraic residuals; initialization must reject negative radicands. A standard steady-state initialization assumes $s_{\mathrm{dip}}=0$. If initialized during voltage-dip or overvoltage logic, $Q_V$, $P_{\mathrm{ord}}$, and the PI histories are not uniquely determined without the unsupported hold-timer histories, so the implementation should solve a saturation-consistent state or reject the start. + +## Monitors + +Monitor | Units | Description | Note +----------------|--------|-------------------------------------|------ +`iqcmd` | [p.u.] | Reactive-current command output | Converter base +`ipcmd` | [p.u.] | Active-current command output | Converter base +`vmeas` | [p.u.] | Filtered terminal voltage | +`pmeas` | [p.u.] | Filtered electrical power | +`piq` | [p.u.] | Reactive-power PI controller state | +`piv` | [p.u.] | Voltage PI controller state | +`qv` | [p.u.] | Reactive-current command lag state | +`pord` | [p.u.] | Filtered active-power order | +`qref` | [p.u.] | Selected reactive-power reference | +`sdip` | [binary] | Voltage-dip/overvoltage freeze indicator | +`iqmax` | [p.u.] | Final reactive-current upper limit | Converter base +`ipmax` | [p.u.] | Final active-current upper limit | Converter base +`iqv` | [p.u.] | Reactive-current injection candidate | Converter base +`vqctrl` | [p.u.] | Reactive-power control PI output | +`iqbase` | [p.u.] | Base reactive-current command | Converter base diff --git a/GridKit/Model/PhasorDynamics/Controller/REECB/README.md b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md index 44d93bbe7..9b437ac2c 100644 --- a/GridKit/Model/PhasorDynamics/Controller/REECB/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md @@ -1,14 +1,9 @@ -# **Renewable Energy Electrical Control Model (REECB)** +# REECB REECB is a WECC renewable electrical-control model with power-factor, reactive-power, voltage, and active-power command paths for an inverter-coupled resource.[^wecc-reecb-specification] -## Notes - -- In direct-voltage mode ($s_Q=1$, $s_V=0$) `qext` carries a terminal-voltage - reference instead of a system-base reactive power. - > [!WARNING] > GridKit does not inherit `mva` from the associated REGCA model. Set `mva` > to the REGCA component base.[^reecb-mva-base] @@ -17,6 +12,11 @@ inverter-coupled resource.[^wecc-reecb-specification] > GridKit does not yet apply the associated generator's Governor Response Limits > modes `Down Only` and `Fixed` to REECB. +## Notes + +- In direct-voltage mode ($s_Q=1$, $s_V=0$) `qext` carries a terminal-voltage + reference instead of a system-base reactive power. + ## Block Diagram ![REECB electrical-control block diagram](../../../../../docs/Figures/PhasorDynamics/REECB/diagram.png) @@ -26,45 +26,45 @@ Figure 1: REECB electrical-control model. Figure courtesy of the ## Model Parameters -Symbol | Units | JSON | Description | Default | Note -------------------------------------|-----------|----------|---------------------------------------------------------|---------------|----- -$S^\mathrm{base}$ | [MVA] | `mva` | REECB component power base | Required | Must be positive -$s_\mathrm{pf}$ | [boolean] | `PfFlag` | Power-factor control selector | `false` | `true` = power-factor control, `false` = reactive-power control -$s_V$ | [boolean] | `VFlag` | Voltage-reference selector under $s_Q=1$ | `false` | `true` = cascaded Q-PI voltage command, `false` = direct external voltage reference -$s_Q$ | [boolean] | `QFlag` | Reactive-path selector | `false` | `true` = Volt/VAr PI control, `false` = reactive-current lag -$s_\mathrm{pq}$ | [boolean] | `Pqflag` | Converter current-priority selector | `false` | `true` = P priority, `false` = Q priority -$T_\mathrm{rv}$ | [sec] | `Trv` | Voltage-measurement filter time constant | 0.02 | State 1 in Fig. 1 -$T_\mathrm{p}$ | [sec] | `Tp` | Electrical-power measurement filter time constant | 0.0 | State 2 in Fig. 1 -$V^\mathrm{ref}$ | [p.u.] | `Vref0` | Reactive-current-injection voltage reference | $V_T$ | Initialized from terminal voltage when omitted -$V_\mathrm{dip}$ | [p.u.] | `Vdip` | Low-voltage threshold for the voltage-band gate | 0.85 | -$V_\mathrm{up}$ | [p.u.] | `Vup` | High-voltage threshold for the voltage-band gate | 1.15 | -$D_1^\mathrm{db}$ | [p.u.] | `dbd1` | Lower deadband threshold for voltage-error response | 0.0 | -$D_2^\mathrm{db}$ | [p.u.] | `dbd2` | Upper deadband threshold for voltage-error response | 0.0 | -$K_\mathrm{qv}$ | [p.u.] | `kqv` | Reactive-current injection gain | 5.0 | -$I_{q,\mathrm{inj}}^{\min}$ | [p.u.] | `Iql1` | Minimum reactive-current injection | -1.1 | -$I_{q,\mathrm{inj}}^{\max}$ | [p.u.] | `Iqh1` | Maximum reactive-current injection | 1.1 | -$Q^{\max}$ | [p.u.] | `Qmax` | Maximum reactive-power control output | 0.436 | -$Q^{\min}$ | [p.u.] | `Qmin` | Minimum reactive-power control output | -0.436 | -$K_\mathrm{qp}$ | [p.u.] | `Kqp` | Reactive-power controller proportional gain | 0.0 | -$K_\mathrm{qi}$ | [p.u./s] | `Kqi` | Reactive-power controller integral gain | 0.1 | -$V^{\max}$ | [p.u.] | `Vmax` | Maximum voltage-control output | 1.1 | -$V^{\min}$ | [p.u.] | `Vmin` | Minimum voltage-control output | 0.9 | -$K_\mathrm{vp}$ | [p.u.] | `Kvp` | Voltage controller proportional gain | 18.0 | -$K_\mathrm{vi}$ | [p.u./s] | `Kvi` | Voltage controller integral gain | 5.0 | -$T_\mathrm{iq}$ | [sec] | `Tiq` | Reactive-current command lag time constant | 0.02 | State 5 in Fig. 1 -$T_\mathrm{pord}$ | [sec] | `Tpord` | Active-power order filter time constant | 0.02 | State 6 in Fig. 1 -$R_P^{\max}$ | [p.u./s] | `dPmax` | Positive active-power order ramp-rate limit | 99.0 | -$R_P^{\min}$ | [p.u./s] | `dPmin` | Negative active-power order ramp-rate limit | -99.0 | -$P^{\max}$ | [p.u.] | `Pmax` | Maximum active-power order | 1.0 | -$P^{\min}$ | [p.u.] | `Pmin` | Minimum active-power order | 0.0 | -$I^{\max}$ | [p.u.] | `Imax` | Maximum converter current | 1.3 | +Symbol | Units | JSON | Description | Typical Value | Note +----------------------------|-----------|----------|-----------------------------------------------------|---------------|------------------------------------------------------------------------------------ +$S^\mathrm{base}$ | [MVA] | `mva` | REECB component power base | Required | Must be positive +$s_\mathrm{pf}$ | [boolean] | `PfFlag` | Power-factor control selector | `false` | `true` = power-factor control, `false` = reactive-power control +$s_V$ | [boolean] | `VFlag` | Voltage-reference selector under $s_Q=1$ | `false` | `true` = cascaded Q-PI voltage command, `false` = direct external voltage reference +$s_Q$ | [boolean] | `QFlag` | Reactive-path selector | `false` | `true` = Volt/VAr PI control, `false` = reactive-current lag +$s_\mathrm{pq}$ | [boolean] | `Pqflag` | Converter current-priority selector | `false` | `true` = P priority, `false` = Q priority +$T_\mathrm{rv}$ | [s] | `Trv` | Voltage-measurement filter time constant | 0.02 | State 1 in Fig. 1 +$T_\mathrm{p}$ | [s] | `Tp` | Electrical-power measurement filter time constant | 0.0 | State 2 in Fig. 1 +$V^\mathrm{ref}$ | [p.u.] | `Vref0` | Reactive-current-injection voltage reference | $V_T$ | Initialized from terminal voltage when omitted +$V_\mathrm{dip}$ | [p.u.] | `Vdip` | Low-voltage threshold for the voltage-band gate | 0.85 | +$V_\mathrm{up}$ | [p.u.] | `Vup` | High-voltage threshold for the voltage-band gate | 1.15 | +$D_1^\mathrm{db}$ | [p.u.] | `dbd1` | Lower deadband threshold for voltage-error response | 0.0 | +$D_2^\mathrm{db}$ | [p.u.] | `dbd2` | Upper deadband threshold for voltage-error response | 0.0 | +$K_\mathrm{qv}$ | [p.u.] | `kqv` | Reactive-current injection gain | 5.0 | +$I_{q,\mathrm{inj}}^{\min}$ | [p.u.] | `Iql1` | Minimum reactive-current injection | -1.1 | +$I_{q,\mathrm{inj}}^{\max}$ | [p.u.] | `Iqh1` | Maximum reactive-current injection | 1.1 | +$Q^{\max}$ | [p.u.] | `Qmax` | Maximum reactive-power control output | 0.436 | +$Q^{\min}$ | [p.u.] | `Qmin` | Minimum reactive-power control output | -0.436 | +$K_\mathrm{qp}$ | [p.u.] | `Kqp` | Reactive-power controller proportional gain | 0.0 | +$K_\mathrm{qi}$ | [p.u./s] | `Kqi` | Reactive-power controller integral gain | 0.1 | +$V^{\max}$ | [p.u.] | `Vmax` | Maximum voltage-control output | 1.1 | +$V^{\min}$ | [p.u.] | `Vmin` | Minimum voltage-control output | 0.9 | +$K_\mathrm{vp}$ | [p.u.] | `Kvp` | Voltage controller proportional gain | 18.0 | +$K_\mathrm{vi}$ | [p.u./s] | `Kvi` | Voltage controller integral gain | 5.0 | +$T_\mathrm{iq}$ | [s] | `Tiq` | Reactive-current command lag time constant | 0.02 | State 5 in Fig. 1 +$T_\mathrm{pord}$ | [s] | `Tpord` | Active-power order filter time constant | 0.02 | State 6 in Fig. 1 +$R_P^{\max}$ | [p.u./s] | `dPmax` | Positive active-power order ramp-rate limit | 99.0 | +$R_P^{\min}$ | [p.u./s] | `dPmin` | Negative active-power order ramp-rate limit | -99.0 | +$P^{\max}$ | [p.u.] | `Pmax` | Maximum active-power order | 1.0 | +$P^{\min}$ | [p.u.] | `Pmin` | Minimum active-power order | 0.0 | +$I^{\max}$ | [p.u.] | `Imax` | Maximum converter current | 1.3 | Real-valued parameters accept real or integer JSON values; selectors require Boolean JSON values. ### Parameter Validation -Invalid REECB parameter sets are rejected by the following checks: +A valid REECB parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -78,7 +78,7 @@ Invalid REECB parameter sets are rejected by the following checks: V^{\min} &\le V^{\max} \\ R_P^{\min} &< 0 < R_P^{\max} \\ P^{\min} &\le P^{\max} \\ - I^{\max} &> 0. + I^{\max} &> 0 \end{aligned} ``` @@ -91,14 +91,14 @@ raised to that floor in place, so every equation below uses the raised value: ```math \begin{aligned} - T_x &\leftarrow \text{max}(T_x,\epsilon_T), && x\in\{\mathrm{rv},\mathrm{p},\mathrm{iq},\mathrm{pord}\} \\ + T_x &\leftarrow \max(T_x,\epsilon_T), && x\in\{\mathrm{rv},\mathrm{p},\mathrm{iq},\mathrm{pord}\} \\ s_\mathrm{pf}^\mathrm{off} &= 1 - s_\mathrm{pf} \\ s_Q^\mathrm{off} &= 1 - s_Q \\ s_Q^\mathrm{PI} &= s_Q s_V \\ s_V^\mathrm{ref} &= s_Q(1-s_V) \\ s_Q^\mathrm{ref} &= 1 - s_V^\mathrm{ref} \\ s_\mathrm{pq}^\mathrm{off} &= 1 - s_\mathrm{pq} \\ - k_\mathrm{base} &= \dfrac{S^\mathrm{sys}}{S^\mathrm{base}}. + k_\mathrm{base} &= \dfrac{S^\mathrm{sys}}{S^\mathrm{base}} \end{aligned} ``` @@ -118,9 +118,8 @@ Name | Port | Init | Description `ipcmd` | Output | Known | Active-current command `bus` is required; signal ports are optional and must be linked when attached. -`Known` ports are seeded before `initialize()` and preserved by it. `Unknown` -inputs are resolved during initialization and written to attached signal -storage, or retained as constant inputs when the port is unattached. +`Known` values are seeded before initialization and preserved. `Unknown` inputs +are initialized in attached signal storage or held constant when unattached. ## Model Variables @@ -128,14 +127,14 @@ storage, or retained as constant inputs when the port is unattached. #### Differential -Symbol | Units | Description | Note -------------------------|--------|-------------------------------------|----- -$V^\mathrm{meas}$ | [p.u.] | Filtered terminal voltage | State 1 in Fig. 1 -$P^\mathrm{meas}$ | [p.u.] | Filtered electrical power | State 2 in Fig. 1; component base -$x_Q^\mathrm{PI}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1 -$x_V^\mathrm{PI}$ | [p.u.] | Voltage-control PI controller state | State 4 in Fig. 1; component-base current -$Q_V$ | [p.u.] | Reactive-current command lag state | State 5 in Fig. 1; component base -$P^\mathrm{ord}$ | [p.u.] | Filtered active-power order | State 6 in Fig. 1; component base +Symbol | Units | Description | Note +------------------|--------|-------------------------------------|--------------------------------------------------------------- +$V^\mathrm{meas}$ | [p.u.] | Filtered terminal voltage | State 1 in Fig. 1; Source label: `Vmeas` +$P^\mathrm{meas}$ | [p.u.] | Filtered electrical power | State 2 in Fig. 1; Source label: `Pmeas`; component base +$x_Q^\mathrm{PI}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1; Source label: `PIQ` +$x_V^\mathrm{PI}$ | [p.u.] | Voltage-control PI controller state | State 4 in Fig. 1; Source label: `PIV`; component-base current +$Q_V$ | [p.u.] | Reactive-current command lag state | State 5 in Fig. 1; Source label: `Q_V`; component base +$P^\mathrm{ord}$ | [p.u.] | Filtered active-power order | State 6 in Fig. 1; Source label: `Pord`; component base #### Algebraic @@ -166,18 +165,20 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note ------------------------|--------|---------|------------------------------------------|----- -$V_\mathrm{r}$ | [p.u.] | Known | Terminal voltage, real component | Bus input -$V_\mathrm{i}$ | [p.u.] | Known | Terminal voltage, imaginary component | Bus input -$P_e$ | [p.u.] | Known | Electrical active-power feedback | Optional signal port `pe`; system base -$Q^\mathrm{gen}$ | [p.u.] | Known | Reactive-power feedback | Optional signal port `qgen`; system base -$Q^\mathrm{ext}$ | [p.u.] | Unknown | External Volt/VAr reference | Optional signal port `qext`; terminal voltage in direct-voltage mode -$\phi^\mathrm{ref}$ | [rad] | Unknown | Power-factor angle reference | Optional signal port `pfaref` -$P^\mathrm{ref}$ | [p.u.] | Unknown | External active-power reference | Optional signal port `pref`; system base +Symbol | Units | Description | Note +--------------------|--------|---------------------------------------|--------------------------------------------------------------------- +$V_r$ | [p.u.] | Terminal voltage, real component | Bus input +$V_i$ | [p.u.] | Terminal voltage, imaginary component | Bus input +$P_\mathrm{e}$ | [p.u.] | Electrical active-power feedback | Optional signal port `pe`; system base +$Q^\mathrm{gen}$ | [p.u.] | Reactive-power feedback | Optional signal port `qgen`; system base +$Q^\mathrm{ext}$ | [p.u.] | External Volt/VAr reference | Optional signal port `qext`; terminal voltage in direct-voltage mode +$\phi^\mathrm{ref}$ | [rad] | Power-factor angle reference | Optional signal port `pfaref` +$P^\mathrm{ref}$ | [p.u.] | External active-power reference | Optional signal port `pref`; system base ## Model Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband2`](../../../../CommonMath.md#type-ii-deadband), [`inside`](../../../../CommonMath.md#inside), [`max`](../../../../CommonMath.md#maximum). + ### Internal Equations #### Differential @@ -185,11 +186,11 @@ $P^\mathrm{ref}$ | [p.u.] | Unknown | External active-power reference ```math \begin{aligned} 0 &= -\dot{V}^\mathrm{meas} + \dfrac{1}{T_\mathrm{rv}}(V_T-V^\mathrm{meas}) \\ - 0 &= -\dot{P}^\mathrm{meas} + \dfrac{1}{T_\mathrm{p}}(k_\mathrm{base}P_e-P^\mathrm{meas}) \\ + 0 &= -\dot{P}^\mathrm{meas} + \dfrac{1}{T_\mathrm{p}}(k_\mathrm{base}P_\mathrm{e}-P^\mathrm{meas}) \\ 0 &= -\dot{x}_Q^\mathrm{PI} + s_Q^\mathrm{PI}s_\mathrm{dip}\,\text{antiwindup}(K_\mathrm{qp}e_Q+x_Q^\mathrm{PI},K_\mathrm{qi}e_Q;\,V^{\min},V^{\max}) \\ 0 &= -\dot{x}_V^\mathrm{PI} + s_Qs_\mathrm{dip}\,\text{antiwindup}(K_\mathrm{vp}e_V^\mathrm{PI}+x_V^\mathrm{PI},K_\mathrm{vi}e_V^\mathrm{PI};\,-I_q^{\max},I_q^{\max}) \\ 0 &= -\dot{Q}_V + \dfrac{1}{T_\mathrm{iq}}s_Q^\mathrm{off}s_\mathrm{dip}\left(\dfrac{Q^\mathrm{ref}}{V_\mathrm{safe}^\mathrm{meas}}-Q_V\right) \\ - 0 &= -\dot{P}^\mathrm{ord} + s_\mathrm{dip}\,\text{antiwindup}(P^\mathrm{ord},r_P^\mathrm{ord};\,P^{\min},P^{\max}). + 0 &= -\dot{P}^\mathrm{ord} + s_\mathrm{dip}\,\text{antiwindup}(P^\mathrm{ord},r_P^\mathrm{ord};\,P^{\min},P^{\max}) \end{aligned} ``` @@ -197,11 +198,11 @@ $P^\mathrm{ref}$ | [p.u.] | Unknown | External active-power reference ```math \begin{aligned} - 0 &= -V_T^2+V_\mathrm{r}^2+V_\mathrm{i}^2 \\ + 0 &= -V_T^2+V_r^2+V_i^2 \\ 0 &= -V_\mathrm{safe}^\mathrm{meas}+\text{max}(V^\mathrm{meas},0.01) \\ 0 &= -s_\mathrm{dip}+\text{inside}(V_T;\,V_\mathrm{dip},V_\mathrm{up}) \\ - 0 &= -I_q^\mathrm{inj}+\text{clamp}\!\left(K_\mathrm{qv}\text{deadband2}(V^\mathrm{ref}-V^\mathrm{meas};\,D_1^\mathrm{db},D_2^\mathrm{db});\,I_{q,\mathrm{inj}}^{\min},I_{q,\mathrm{inj}}^{\max}\right) \\ - 0 &= -Q^\mathrm{ref}+s_Q^\mathrm{ref}\left(s_\mathrm{pf}P^\mathrm{meas}\tan(\phi^\mathrm{ref})+s_\mathrm{pf}^\mathrm{off}k_\mathrm{base}Q^\mathrm{ext}\right) \\ + 0 &= -I_q^\mathrm{inj}+\text{clamp}\!(K_\mathrm{qv}\text{deadband2}(V^\mathrm{ref}-V^\mathrm{meas};\,D_1^\mathrm{db},D_2^\mathrm{db});\,I_{q,\mathrm{inj}}^{\min},I_{q,\mathrm{inj}}^{\max}) \\ + 0 &= -Q^\mathrm{ref}+s_Q^\mathrm{ref}(s_\mathrm{pf}P^\mathrm{meas}\tan(\phi^\mathrm{ref})+s_\mathrm{pf}^\mathrm{off}k_\mathrm{base}Q^\mathrm{ext}) \\ 0 &= -e_Q+\text{clamp}(Q^\mathrm{ref};\,Q^{\min},Q^{\max})-k_\mathrm{base}Q^\mathrm{gen} \\ 0 &= -V_Q^\mathrm{PI}+\text{clamp}(K_\mathrm{qp}e_Q+x_Q^\mathrm{PI};\,V^{\min},V^{\max}) \\ 0 &= -e_V^\mathrm{PI}+s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}Q^\mathrm{ext}-s_QV^\mathrm{meas} \\ @@ -212,19 +213,17 @@ $P^\mathrm{ref}$ | [p.u.] | Unknown | External active-power reference 0 &= -I_q^\mathrm{base}+\text{clamp}(K_\mathrm{vp}e_V^\mathrm{PI}+x_V^\mathrm{PI};\,-I_q^{\max},I_q^{\max}) \\ 0 &= -I_q^\mathrm{raw}+s_QI_q^\mathrm{base}+s_Q^\mathrm{off}Q_V+I_q^\mathrm{inj} \\ 0 &= -k_\mathrm{base}I_q^\mathrm{cmd}+\text{clamp}(I_q^\mathrm{raw};\,-I_q^{\max},I_q^{\max}) \\ - 0 &= -k_\mathrm{base}I_p^\mathrm{cmd}+\text{clamp}\left(\dfrac{P^\mathrm{ord}}{V_\mathrm{safe}^\mathrm{meas}};\,0,I_p^{\max}\right). + 0 &= -k_\mathrm{base}I_p^\mathrm{cmd}+\text{clamp}\left(\dfrac{P^\mathrm{ord}}{V_\mathrm{safe}^\mathrm{meas}};\,0,I_p^{\max}\right) \end{aligned} ``` Here $I^\mathrm{high}=s_\mathrm{pq}k_\mathrm{base}I_p^\mathrm{cmd} +s_\mathrm{pq}^\mathrm{off}k_\mathrm{base}I_q^\mathrm{cmd}$ and -$\epsilon_0=100\epsilon_\mathrm{machine}$. -[Appendix C](#appendix-c-sqrtramp) defines `sqrtramp`. +$\epsilon_\mathrm{init}=100\epsilon_\mathrm{machine}$. +[Appendix B](#appendix-b-sqrtramp) defines `sqrtramp`. -CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) and -[smooth limiter](../../../../CommonMath.md#derived-functions) functions used in -these equations. [Appendix B](#appendix-b-aslew) defines `aslew`. +[Appendix A](#appendix-a-aslew) defines `aslew`. ### External Equations @@ -238,54 +237,59 @@ REECB reconstructs a steady operating point. Arbitrary-state restart is unsuppor ```math \begin{aligned} - V_\mathrm{r},V_\mathrm{i} &\leftarrow \text{terminal-bus voltage} \\ + V_r,V_i &\leftarrow \text{terminal-bus voltage} \\ I_q^\mathrm{cmd},I_p^\mathrm{cmd} &\leftarrow \text{owned current-command variables} \\ - P_e &\leftarrow \text{attached active-power feedback},\quad \text{if attached} \\ - Q^\mathrm{gen} &\leftarrow \text{attached reactive-power feedback},\quad \text{if attached}. + P_\mathrm{e} &\leftarrow \text{attached active-power feedback},\quad \text{if attached} \\ + Q^\mathrm{gen} &\leftarrow \text{attached reactive-power feedback},\quad \text{if attached} \end{aligned} ``` ### Internal Initialization Initialization resolves the steady-state quantities in dependency order; all -internal derivatives start at zero. Let $I_p=k_\mathrm{base}I_p^\mathrm{cmd}$ -and $I_q=k_\mathrm{base}I_q^\mathrm{cmd}$ be the component-base commands. -[Appendix A](#appendix-a-iclamp) defines the initialization-only `iclamp`. +internal derivatives start at zero. Initialize the component-base commands: +$I_p\leftarrow k_\mathrm{base}I_p^\mathrm{cmd}$ and +$I_q\leftarrow k_\mathrm{base}I_q^\mathrm{cmd}$. +CommonMath defines the [initialization inverse](../../../../CommonMath.md#initialization-inverses) +`iclamp`. At a bound, REECB uses an outward offset +$\delta=-\ln(\text{expm1}(\mu\epsilon_\mathrm{init}/2))/\mu$ to keep the clamp error +within $\epsilon_\mathrm{init}$; collapsed bounds return the bound. ```math \begin{aligned} - V_T &\leftarrow \sqrt{V_\mathrm{r}^2+V_\mathrm{i}^2} \\ + V_T &\leftarrow \sqrt{V_r^2+V_i^2} \\ V^\mathrm{ref} &\leftarrow V_T,\quad \text{if omitted} \\ V^\mathrm{meas} &\leftarrow V_T \\ V_\mathrm{safe}^\mathrm{meas} &\leftarrow \text{max}(V^\mathrm{meas},0.01) \\ s_\mathrm{dip} &\leftarrow \text{inside}(V_T;\,V_\mathrm{dip},V_\mathrm{up}) \\ - P_e &\leftarrow V_\mathrm{safe}^\mathrm{meas}I_p^\mathrm{cmd},\quad \text{if unattached} \\ + P_\mathrm{e} &\leftarrow V_\mathrm{safe}^\mathrm{meas}I_p^\mathrm{cmd},\quad \text{if unattached} \\ Q^\mathrm{gen} &\leftarrow V_\mathrm{safe}^\mathrm{meas}I_q^\mathrm{cmd},\quad \text{if unattached} \\ - P^\mathrm{meas} &\leftarrow k_\mathrm{base}P_e \\ + P^\mathrm{meas} &\leftarrow k_\mathrm{base}P_\mathrm{e} \\ e_V^\mathrm{db} &\leftarrow \text{deadband2}(V^\mathrm{ref}-V^\mathrm{meas};\,D_1^\mathrm{db},D_2^\mathrm{db}) \\ - I_q^\mathrm{inj} &\leftarrow \text{clamp}(K_\mathrm{qv}e_V^\mathrm{db};\,I_{q,\mathrm{inj}}^{\min},I_{q,\mathrm{inj}}^{\max}). + I_q^\mathrm{inj} &\leftarrow \text{clamp}(K_\mathrm{qv}e_V^\mathrm{db};\,I_{q,\mathrm{inj}}^{\min},I_{q,\mathrm{inj}}^{\max}) \end{aligned} ``` Let $I_q^\mathrm{need}$ be the smooth-clamp input magnitude required to reproduce $I_q$, including the Volt/VAr recovery margin. Initialization raises -$I^\max$, if needed, to a finite limit satisfying +$I^{\max}$, if needed, to a finite limit satisfying ```math \begin{aligned} - h &= s_\mathrm{pq}I_p+s_\mathrm{pq}^\mathrm{off}|I_q| \\ - \ell &= s_\mathrm{pq}I_q^\mathrm{need}+s_\mathrm{pq}^\mathrm{off}I_p \\ - I &\ge \text{max}(I^\max,h,\ell,I_q^\mathrm{need}) \\ - \text{sqrtramp}\big((I-h)(I+h)\big) &\ge \ell. + h &\leftarrow s_\mathrm{pq}I_p+s_\mathrm{pq}^\mathrm{off}|I_q| \\ + \ell &\leftarrow s_\mathrm{pq}I_q^\mathrm{need}+s_\mathrm{pq}^\mathrm{off}I_p \\ + I &\ge \max(I^{\max},h,\ell,I_q^\mathrm{need}) \\ + \text{sqrtramp}\big((I-h)(I+h)\big) &\ge \ell \end{aligned} ``` The solution initializes -$I^\max\leftarrow I$ and +$I^{\max}\leftarrow I$ and $I_L^\mathrm{cap}\leftarrow\text{sqrtramp}\big((I-h)(I+h)\big)$. The operating point is rejected if no finite solution exists or the reactive-current injection is incompatible. Q, V, and P limits are expanded as -needed; each adjustment logs a warning. +needed; each adjustment logs a warning. This matches PowerWorld's default +`Modify Limits and Run` treatment of initial limit violations. ```math \begin{aligned} @@ -297,7 +301,7 @@ needed; each adjustment logs a warning. V_\mathrm{safe}^\mathrm{meas}I_q^\mathrm{ctrl} & s_Q=0 \\ \text{iclamp}(k_\mathrm{base}Q^\mathrm{gen};\,Q^{\min},Q^{\max}) & s_Qs_V=1 \\ 0 & \text{otherwise} - \end{cases}. + \end{cases} \end{aligned} ``` @@ -317,8 +321,8 @@ give e_V^\mathrm{PI} &\leftarrow s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}Q^\mathrm{ext}-s_QV^\mathrm{meas} \\ x_V^\mathrm{PI} &\leftarrow \begin{cases} - -K_\mathrm{vp}e_V^\mathrm{PI} & s_Q=1\ \land\ I_q^{\max}\le\epsilon_0 \\ - \text{iclamp}(I_q^\mathrm{ctrl};\,-I_q^{\max},I_q^{\max})-K_\mathrm{vp}e_V^\mathrm{PI} & s_Q=1\ \land\ I_q^{\max}>\epsilon_0 \\ + -K_\mathrm{vp}e_V^\mathrm{PI} & s_Q=1\ \land\ I_q^{\max}\le\epsilon_\mathrm{init} \\ + \text{iclamp}(I_q^\mathrm{ctrl};\,-I_q^{\max},I_q^{\max})-K_\mathrm{vp}e_V^\mathrm{PI} & s_Q=1\ \land\ I_q^{\max}>\epsilon_\mathrm{init} \\ 0 & s_Q=0 \end{cases} \\ Q_V &\leftarrow @@ -326,9 +330,9 @@ give 0 & s_Q=1 \\ Q^\mathrm{ref}/V_\mathrm{safe}^\mathrm{meas} & s_Q=0 \end{cases} \\ - I_q^\mathrm{base} &\leftarrow \text{clamp}(K_\mathrm{vp}e_V^\mathrm{PI}+x_V^\mathrm{PI};\,-I_q^\max,I_q^\max) \\ + I_q^\mathrm{base} &\leftarrow \text{clamp}(K_\mathrm{vp}e_V^\mathrm{PI}+x_V^\mathrm{PI};\,-I_q^{\max},I_q^{\max}) \\ I_q^\mathrm{raw} &\leftarrow s_QI_q^\mathrm{base}+s_Q^\mathrm{off}Q_V+I_q^\mathrm{inj} \\ - r_P^\mathrm{ord} &\leftarrow 0. + r_P^\mathrm{ord} &\leftarrow 0 \end{aligned} ``` @@ -357,45 +361,16 @@ limit, latch, or signal is changed. REECB writes the resolved references to attached signal inputs; unattached ports retain them as constant inputs. -## Monitorable Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note --------|--------|---------------------------------|----- `iqcmd` | [p.u.] | Reactive-current command output | $I_q^\mathrm{cmd}$ (system base) `ipcmd` | [p.u.] | Active-current command output | $I_p^\mathrm{cmd}$ (system base) `vmeas` | [p.u.] | Filtered terminal voltage | $V^\mathrm{meas}$ `pmeas` | [p.u.] | Filtered electrical power | $P^\mathrm{meas}$ (component base) -## Testing - -- `validation()` checks configuration and defaults. -- `initializationAndSignals()` checks initialization, signals, monitors, and power bases. -- `initializationDomain()` checks rejected inputs and limit expansion. -- `initializationExactness()` checks endpoint and current-circle initialization. -- `residualEquations()` checks residual equations at a hand-computable state. -- `selectorConfigurations()` checks selectors and optional ports. -- `voltVarReferenceBase()` checks `qext` units. -- `reactiveControl()` checks the reactive-control paths. -- `activeCurrentControl()` checks active-current control, current priority, and the current circle. -- `jacobian()` compares the Enzyme and dependency-tracking Jacobians. -- `regcaReecbRepca()` checks the public-signal REGCA-REECB-REPCA control loop. -- `reecb()` checks construction through the production system-data path. - -## Appendix A: `iclamp` - -For $\ell [!WARNING] +> GridKit does not yet apply the associated generator's Governor Response Limits +> modes `Down Only` and `Fixed` to REPCA. -- Fig. 1 hard nonlinearities use the linked CommonMath smooth approximations; - transition-point values may differ. +## Notes > [!NOTE] > `freq` is optional because the regulated bus does not yet expose a frequency @@ -14,10 +15,6 @@ resources. > frequency at 1.0 p.u. and logs a warning. `freq` and `freqref` use absolute > per-unit frequency. -> [!WARNING] -> GridKit does not yet apply the associated generator's Governor Response Limits -> modes `Down Only` and `Fixed` to REPCA. - ## Block Diagram ![REPCA plant-control block diagram](../../../../../docs/Figures/PhasorDynamics/REPCA/diagram.png) @@ -29,47 +26,48 @@ Figure 1: REPCA plant-control model. Figure courtesy of All parameters are optional; omitted keys use the defaults below. -Symbol | Units | JSON | Description | Default | Note -------------------------------------|-----------|-------------|---------------------------------------------------------|---------------|------ -$S^\mathrm{base}$ | [MVA] | `mva` | REPCA component power base | 100.0 | Set to the associated converter base -$s_\mathrm{comp}$ | [boolean] | `VcompFlag` | Voltage-compensation selector | `true` | `true` = line-drop compensation, `false` = reactive droop -$s_\mathrm{ref}$ | [boolean] | `RefFlag` | Reactive-loop reference selector | `true` | `true` = voltage control, `false` = reactive-power control -$s_\mathrm{freq}$ | [boolean] | `Freqflag` | Active-power output selector | `false` | `true` = command enabled, `false` = zero output -$T_\mathrm{fltr}$ | [sec] | `Tfltr` | Voltage and reactive-power filter time constant | 0.05 | -$V^\mathrm{frz}$ | [p.u.] | `Vfrz` | Reactive-power PI freeze-voltage threshold | 0.7 | -$R_c$ | [p.u.] | `Rc` | Line-drop compensation resistance | 0.0 | Component base -$X_c$ | [p.u.] | `Xc` | Line-drop compensation reactance | 0.0 | Component base -$K_c$ | [p.u.] | `Kc` | Reactive-current compensation gain | 1.0 | -$D_\mathrm{bd1}$ | [p.u.] | `dbdlow` | Lower reactive-loop deadband threshold | 0.0 | -$D_\mathrm{bd2}$ | [p.u.] | `dbdupper` | Upper reactive-loop deadband threshold | 0.0 | -$e^{\max}$ | [p.u.] | `emax` | Maximum reactive-loop error limit | 1.0 | -$e^{\min}$ | [p.u.] | `emin` | Minimum reactive-loop error limit | -1.0 | -$K_\mathrm{p}$ | [p.u.] | `Kp` | Reactive-power controller proportional gain | 10.0 | -$K_\mathrm{i}$ | [p.u./s] | `Ki` | Reactive-power controller integral gain | 10.0 | -$Q^{\max}$ | [p.u.] | `Qmax` | Maximum reactive-power command | 1.0 | Component base -$Q^{\min}$ | [p.u.] | `Qmin` | Minimum reactive-power command | -1.0 | Component base -$T_\mathrm{ft}$ | [sec] | `Tft` | Reactive-command lead time constant | 0.0 | -$T_\mathrm{fv}$ | [sec] | `Tfv` | Reactive-command lag time constant | 3.0 | -$T_\mathrm{p}$ | [sec] | `Tp` | Active-power measurement filter time constant | 0.0 | -$D_\mathrm{bd1}^{f}$ | [p.u.] | `fdbd1` | Lower frequency-error deadband threshold | 0.0 | -$D_\mathrm{bd2}^{f}$ | [p.u.] | `fdbd2` | Upper frequency-error deadband threshold | 0.0 | -$D_\mathrm{dn}$ | [p.u./p.u.] | `Ddn` | Down-regulation (overfrequency) gain | 20.0 | -$D_\mathrm{up}$ | [p.u./p.u.] | `Dup` | Up-regulation (underfrequency) gain | 0.0 | -$e_P^{\max}$ | [p.u.] | `femax` | Maximum active-power error limit | 1.0 | -$e_P^{\min}$ | [p.u.] | `femin` | Minimum active-power error limit | -1.0 | -$K_\mathrm{pg}$ | [p.u.] | `Kpg` | Active-power controller proportional gain | 10.0 | -$K_\mathrm{ig}$ | [p.u./s] | `Kig` | Active-power controller integral gain | 10.0 | -$P^{\max}$ | [p.u.] | `Pmax` | Maximum active-power command | 2.0 | Component base -$P^{\min}$ | [p.u.] | `Pmin` | Minimum active-power command | 0.0 | Component base -$T_\mathrm{lag}$ | [sec] | `Tlag` | Active-power command lag time constant | 3.0 | +Symbol | Units | JSON | Description | Typical Value | Note +---------------------|-------------|-------------|-------------------------------------------------|---------------|----------------------------------------------------------- +$S^\mathrm{base}$ | [MVA] | `mva` | REPCA component power base | 100.0 | Set to the associated converter base +$s_\mathrm{comp}$ | [boolean] | `VcompFlag` | Voltage-compensation selector | `true` | `true` = line-drop compensation, `false` = reactive droop +$s_\mathrm{ref}$ | [boolean] | `RefFlag` | Reactive-loop reference selector | `true` | `true` = voltage control, `false` = reactive-power control +$s_\mathrm{freq}$ | [boolean] | `Freqflag` | Active-power output selector | `false` | `true` = command enabled, `false` = zero output +$T_\mathrm{fltr}$ | [s] | `Tfltr` | Voltage and reactive-power filter time constant | 0.05 | +$V^\mathrm{frz}$ | [p.u.] | `Vfrz` | Reactive-power PI freeze-voltage threshold | 0.7 | +$R_c$ | [p.u.] | `Rc` | Line-drop compensation resistance | 0.0 | Component base +$X_c$ | [p.u.] | `Xc` | Line-drop compensation reactance | 0.0 | Component base +$K_c$ | [p.u.] | `Kc` | Reactive-current compensation gain | 1.0 | +$D_\mathrm{bd1}$ | [p.u.] | `dbdlow` | Lower reactive-loop deadband threshold | 0.0 | +$D_\mathrm{bd2}$ | [p.u.] | `dbdupper` | Upper reactive-loop deadband threshold | 0.0 | +$e^{\max}$ | [p.u.] | `emax` | Upper limit on the signed reactive-loop error | 1.0 | +$e^{\min}$ | [p.u.] | `emin` | Lower limit on the signed reactive-loop error | -1.0 | +$K_\mathrm{p}$ | [p.u.] | `Kp` | Reactive-power controller proportional gain | 10.0 | +$K_\mathrm{i}$ | [p.u./s] | `Ki` | Reactive-power controller integral gain | 10.0 | +$Q^{\max}$ | [p.u.] | `Qmax` | Maximum reactive-power command | 1.0 | Component base +$Q^{\min}$ | [p.u.] | `Qmin` | Minimum reactive-power command | -1.0 | Component base +$T_\mathrm{ft}$ | [s] | `Tft` | Reactive-command lead time constant | 0.0 | +$T_\mathrm{fv}$ | [s] | `Tfv` | Reactive-command lag time constant | 3.0 | +$T_\mathrm{p}$ | [s] | `Tp` | Active-power measurement filter time constant | 0.0 | +$D_\mathrm{bd1}^{f}$ | [p.u.] | `fdbd1` | Lower frequency-error deadband threshold | 0.0 | +$D_\mathrm{bd2}^{f}$ | [p.u.] | `fdbd2` | Upper frequency-error deadband threshold | 0.0 | +$D_\mathrm{dn}$ | [p.u./p.u.] | `Ddn` | Down-regulation (overfrequency) gain | 20.0 | +$D_\mathrm{up}$ | [p.u./p.u.] | `Dup` | Up-regulation (underfrequency) gain | 0.0 | +$e_P^{\max}$ | [p.u.] | `femax` | Upper limit on the signed active-power error | 1.0 | +$e_P^{\min}$ | [p.u.] | `femin` | Lower limit on the signed active-power error | -1.0 | +$K_\mathrm{pg}$ | [p.u.] | `Kpg` | Active-power controller proportional gain | 10.0 | +$K_\mathrm{ig}$ | [p.u./s] | `Kig` | Active-power controller integral gain | 10.0 | +$P^{\max}$ | [p.u.] | `Pmax` | Maximum active-power command | 2.0 | Component base +$P^{\min}$ | [p.u.] | `Pmin` | Minimum active-power command | 0.0 | Component base +$T_\mathrm{lag}$ | [s] | `Tlag` | Active-power command lag time constant | 3.0 | ### Parameter Validation -All real parameters must be finite. Invalid parameter sets are rejected by: +A valid REPCA parameter set must satisfy the following conditions: ```math \begin{aligned} S^\mathrm{base} &> 0 \\ + T_\mathrm{fltr}, T_\mathrm{ft}, T_\mathrm{fv}, T_\mathrm{p}, T_\mathrm{lag} &\ge 0 \\ D_\mathrm{bd1} &\le 0 \le D_\mathrm{bd2} \\ e^{\min} &\le 0 \le e^{\max} \\ Q^{\min} &\le Q^{\max} \\ @@ -80,6 +78,8 @@ All real parameters must be finite. Invalid parameter sets are rejected by: \end{aligned} ``` +All real parameters must be finite. + The power bases and both conversion ratios must also be finite and positive; `verify()` also enforces Model Ports. @@ -94,8 +94,8 @@ floor with a warning: s_\mathrm{comp}^\mathrm{off} &= 1 - s_\mathrm{comp} \\ s_\mathrm{ref}^\mathrm{off} &= 1 - s_\mathrm{ref} \\ k_\mathrm{base} &= \dfrac{S^\mathrm{sys}}{S^\mathrm{base}} \\ - I_\mathrm{r}^\mathrm{comp} &= k_\mathrm{base}I_\mathrm{r}, \quad - I_\mathrm{i}^\mathrm{comp} = k_\mathrm{base}I_\mathrm{i} + I_r^\mathrm{comp} &= k_\mathrm{base}I_r, \quad + I_i^\mathrm{comp} = k_\mathrm{base}I_i \end{aligned} ``` @@ -132,15 +132,15 @@ $s_\mathrm{freq}=1$; otherwise `pext` becomes zero. #### Differential -Symbol | Units | Description | Note -------------------------|--------|-------------------------------------|------ -$V^\mathrm{meas}$ | [p.u.] | Filtered regulated voltage | State 1 in Fig. 1 -$Q^\mathrm{meas}$ | [p.u.] | Filtered reactive-power signal | State 2 in Fig. 1; component base -$x_Q^\mathrm{PI}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1; component base -$x_Q^\mathrm{lag}$ | [p.u.] | Reactive-command lead-lag state | State 4 in Fig. 1; component base -$P^\mathrm{meas}$ | [p.u.] | Filtered active-power signal | State 5 in Fig. 1; component base -$x_P^\mathrm{PI}$ | [p.u.] | Active-power PI controller state | State 6 in Fig. 1; component base -$P^\mathrm{ref}$ | [p.u.] | Active-power command lag state | State 7 in Fig. 1; component base +Symbol | Units | Description | Note +-------------------|--------|------------------------------------|--------------------------------------------------------------- +$V^\mathrm{meas}$ | [p.u.] | Filtered regulated voltage | State 1 in Fig. 1; Source label: `Vmeas` +$Q^\mathrm{meas}$ | [p.u.] | Filtered reactive-power signal | State 2 in Fig. 1; Source label: `Qmeas`; component base +$x_Q^\mathrm{PI}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1; Source label: `Reactive PI`; component base +$x_Q^\mathrm{lag}$ | [p.u.] | Reactive-command lead–lag state | State 4 in Fig. 1; Source label: `Qext`; component base +$P^\mathrm{meas}$ | [p.u.] | Filtered active-power signal | State 5 in Fig. 1; Source label: `Pmeas`; component base +$x_P^\mathrm{PI}$ | [p.u.] | Active-power PI controller state | State 6 in Fig. 1; Source label: `Power PI`; component base +$P^\mathrm{ref}$ | [p.u.] | Active-power command lag state | State 7 in Fig. 1; Source label: `Pref`; component base #### Algebraic @@ -170,22 +170,24 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note --------------------------------|--------|---------|-----------------------------------|------ -$V_\mathrm{r}$ | [p.u.] | Known | Regulated-bus voltage, real component | Bus input -$V_\mathrm{i}$ | [p.u.] | Known | Regulated-bus voltage, imaginary component | Bus input -$I_\mathrm{r}$ | [p.u.] | Known | Branch-current real component | Signal port `ir`; system base -$I_\mathrm{i}$ | [p.u.] | Known | Branch-current imaginary component | Signal port `ii`; system base -$P$ | [p.u.] | Known | Branch active power | Signal port `p`; system base -$Q$ | [p.u.] | Known | Branch reactive power | Signal port `q`; system base -$f$ | [p.u.] | Known | Frequency input | Signal port `freq` -$V^\mathrm{ref}$ | [p.u.] | Unknown | Voltage-control reference | Optional signal port `vref` -$P_\mathrm{plant}^\mathrm{ref}$ | [p.u.] | Unknown | Plant active-power reference | Optional signal port `pref`; system base -$Q^\mathrm{ref}$ | [p.u.] | Unknown | Reactive-power reference | Optional signal port `qref`; system base -$f^\mathrm{ref}$ | [p.u.] | Unknown | Frequency reference | Optional signal port `freqref` +Symbol | Units | Description | Note +--------------------------------|--------|--------------------------------------------|----------------------------------------- +$V_r$ | [p.u.] | Regulated-bus voltage, real component | Bus input +$V_i$ | [p.u.] | Regulated-bus voltage, imaginary component | Bus input +$I_r$ | [p.u.] | Branch-current real component | Signal port `ir`; system base +$I_i$ | [p.u.] | Branch-current imaginary component | Signal port `ii`; system base +$P$ | [p.u.] | Branch active power | Signal port `p`; system base +$Q$ | [p.u.] | Branch reactive power | Signal port `q`; system base +$f$ | [p.u.] | Frequency input | Signal port `freq` +$V^\mathrm{ref}$ | [p.u.] | Voltage-control reference | Optional signal port `vref` +$P_\mathrm{plant}^\mathrm{ref}$ | [p.u.] | Plant active-power reference | Optional signal port `pref`; system base +$Q^\mathrm{ref}$ | [p.u.] | Reactive-power reference | Optional signal port `qref`; system base +$f^\mathrm{ref}$ | [p.u.] | Frequency reference | Optional signal port `freqref` ## Model Equations +Smooth functions: [`above`](../../../../CommonMath.md#above), [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband2`](../../../../CommonMath.md#type-ii-deadband). + ### Internal Equations #### Differential @@ -198,19 +200,16 @@ $f^\mathrm{ref}$ | [p.u.] | Unknown | Frequency reference 0 &= -\dot{x}_Q^\mathrm{lag} + \dfrac{1}{T_\mathrm{fv}} (Q^\mathrm{PI} - x_Q^\mathrm{lag}) \\ 0 &= -\dot{P}^\mathrm{meas} + \dfrac{1}{T_\mathrm{p}} (k_\mathrm{base}P - P^\mathrm{meas}) \\ 0 &= -\dot{x}_P^\mathrm{PI} + \text{antiwindup}(P^\mathrm{PI}, K_\mathrm{ig}e_P^\mathrm{lim};\,P^{\min}, P^{\max}) \\ - 0 &= -\dot{P}^\mathrm{ref} + \dfrac{1}{T_\mathrm{lag}} (P^\mathrm{PI} - P^\mathrm{ref}). + 0 &= -\dot{P}^\mathrm{ref} + \dfrac{1}{T_\mathrm{lag}} (P^\mathrm{PI} - P^\mathrm{ref}) \end{aligned} ``` -CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - #### Algebraic ```math \begin{aligned} - 0 &= -V^2 + V_\mathrm{r}^2 + V_\mathrm{i}^2 \\ - 0 &= -(V^\mathrm{ldc})^2 + (V_\mathrm{r} - R_c I_\mathrm{r}^\mathrm{comp} + X_c I_\mathrm{i}^\mathrm{comp})^2 + (V_\mathrm{i} - R_c I_\mathrm{i}^\mathrm{comp} - X_c I_\mathrm{r}^\mathrm{comp})^2 \\ + 0 &= -V^2 + V_r^2 + V_i^2 \\ + 0 &= -(V^\mathrm{ldc})^2 + (V_r - R_c I_r^\mathrm{comp} + X_c I_i^\mathrm{comp})^2 + (V_i - R_c I_i^\mathrm{comp} - X_c I_r^\mathrm{comp})^2 \\ 0 &= -V^\mathrm{droop} + V + K_c k_\mathrm{base}Q \\ 0 &= -V^\mathrm{ctrl} + s_\mathrm{comp}V^\mathrm{ldc} + s_\mathrm{comp}^\mathrm{off}V^\mathrm{droop} \\ 0 &= -s_\mathrm{frz} + \text{above}(V;\,V^\mathrm{frz}) \\ @@ -223,12 +222,11 @@ target and smooth approximation. 0 &= -e_P + k_\mathrm{base}P_\mathrm{plant}^\mathrm{ref} - P^\mathrm{meas} + \text{droop}(e_f;D_\mathrm{dn},D_\mathrm{up}) \\ 0 &= -e_P^\mathrm{lim} + \text{clamp}(e_P;\,e_P^{\min},e_P^{\max}) \\ 0 &= -P^\mathrm{PI} + \text{clamp}(K_\mathrm{pg}e_P^\mathrm{lim}+x_P^\mathrm{PI};\,P^{\min},P^{\max}) \\ - 0 &= -k_\mathrm{base}P^\mathrm{ext} + s_\mathrm{freq}P^\mathrm{ref}. + 0 &= -k_\mathrm{base}P^\mathrm{ext} + s_\mathrm{freq}P^\mathrm{ref} \end{aligned} ``` -CommonMath defines the [derived limiter functions](../../../../CommonMath.md#derived-functions) -used above; Appendix A defines `droop`. +[Appendix A](#appendix-a-droop) defines `droop`. ### External Equations @@ -242,8 +240,8 @@ REPCA reconstructs a steady operating point; arbitrary-state restart is unsuppor ```math \begin{aligned} - V_\mathrm{r}, V_\mathrm{i} &\leftarrow \text{regulated-bus voltage} \\ - I_\mathrm{r}, I_\mathrm{i} &\leftarrow \text{branch current} \\ + V_r, V_i &\leftarrow \text{regulated-bus voltage} \\ + I_r, I_i &\leftarrow \text{branch current} \\ P, Q &\leftarrow \text{branch power} \\ f &\leftarrow \text{frequency input} \\ Q^\mathrm{ext} &\leftarrow \text{known reactive-power command on system base} \\ @@ -253,31 +251,33 @@ REPCA reconstructs a steady operating point; arbitrary-state restart is unsuppor ### Internal Initialization -Initialization-only $\text{clamp}^{-1}$ and $\text{deadband2}^{-1}$ recover -finite inputs that reproduce the requested smooth-block outputs. +Initialization uses the smooth [initialization inverses](../../../../CommonMath.md#initialization-inverses) +`iclamp` and `ideadband2`. Within $10^{-12}$ of a clamp bound, REPCA uses that +bound moved outward by $0.1$; intervals of width at most $10^{-12}$ return +$\ell$. Deadband outputs within $10^{-12}$ of zero use the midpoint; other +values are inverted by bisection. ```math \begin{aligned} - V &\leftarrow \sqrt{V_\mathrm{r}^2 + V_\mathrm{i}^2} \\ - V^\mathrm{ldc} &\leftarrow \sqrt{(V_\mathrm{r}-R_c I_\mathrm{r}^\mathrm{comp}+X_c I_\mathrm{i}^\mathrm{comp})^2 + (V_\mathrm{i}-R_c I_\mathrm{i}^\mathrm{comp}-X_c I_\mathrm{r}^\mathrm{comp})^2} \\ + V &\leftarrow \sqrt{V_r^2 + V_i^2} \\ + V^\mathrm{ldc} &\leftarrow \sqrt{(V_r-R_c I_r^\mathrm{comp}+X_c I_i^\mathrm{comp})^2 + (V_i-R_c I_i^\mathrm{comp}-X_c I_r^\mathrm{comp})^2} \\ V^\mathrm{droop} &\leftarrow V + K_c k_\mathrm{base}Q \\ V^\mathrm{ctrl} &\leftarrow s_\mathrm{comp}V^\mathrm{ldc} + s_\mathrm{comp}^\mathrm{off}V^\mathrm{droop} \\ V^\mathrm{meas} &\leftarrow V^\mathrm{ctrl} \\ Q^\mathrm{meas} &\leftarrow k_\mathrm{base}Q \\ P^\mathrm{meas} &\leftarrow k_\mathrm{base}P \\ s_\mathrm{frz} &\leftarrow \text{above}(V;\,V^\mathrm{frz}) \\ - e_\mathrm{RQ}^\mathrm{db} &\leftarrow \text{clamp}^{-1}(0;\,e^{\min},e^{\max}) \\ - e_\mathrm{RQ} &\leftarrow \text{deadband2}^{-1}(e_\mathrm{RQ}^\mathrm{db};\,D_\mathrm{bd1},D_\mathrm{bd2}) \\ + e_\mathrm{RQ}^\mathrm{db} &\leftarrow \text{iclamp}(0;\,e^{\min},e^{\max}) \\ + e_\mathrm{RQ} &\leftarrow \text{ideadband2}(e_\mathrm{RQ}^\mathrm{db};\,D_\mathrm{bd1},D_\mathrm{bd2}) \\ e_\mathrm{RQ}^\mathrm{lim} &\leftarrow 0 \\ Q^\mathrm{PI} &\leftarrow k_\mathrm{base}Q^\mathrm{ext} \\ Q^{\min} &\leftarrow \min(Q^{\min},Q^\mathrm{PI}),\quad Q^{\max}\leftarrow \max(Q^{\max},Q^\mathrm{PI}) \\ x_Q^\mathrm{lag} &\leftarrow Q^\mathrm{PI} \\ - u_Q^\mathrm{PI} &\leftarrow \text{clamp}^{-1}(Q^\mathrm{PI};\,Q^{\min},Q^{\max}) \\ + u_Q^\mathrm{PI} &\leftarrow \text{iclamp}(Q^\mathrm{PI};\,Q^{\min},Q^{\max}) \\ x_Q^\mathrm{PI} &\leftarrow u_Q^\mathrm{PI} - K_\mathrm{p}e_\mathrm{RQ}^\mathrm{lim} \\ - \Delta f_0 &\leftarrow \text{deadband2}^{-1}(0;\,D_\mathrm{bd1}^{f},D_\mathrm{bd2}^{f}) \\ e_f &\leftarrow 0 \\ - P^\mathrm{freq} &\leftarrow \text{droop}(e_f;D_\mathrm{dn},D_\mathrm{up}) = 0 \\ - e_P &\leftarrow \text{clamp}^{-1}(0;\,e_P^{\min},e_P^{\max}) \\ + P^\mathrm{freq} &\leftarrow \text{droop}(e_f;D_\mathrm{dn},D_\mathrm{up}) \\ + e_P &\leftarrow \text{iclamp}(0;\,e_P^{\min},e_P^{\max}) \\ e_P^\mathrm{lim} &\leftarrow 0 \\ P^\mathrm{ref} &\leftarrow \begin{cases} k_\mathrm{base}P^\mathrm{ext} & s_\mathrm{freq}=1 \\ @@ -285,15 +285,16 @@ finite inputs that reproduce the requested smooth-block outputs. \end{cases} \\ P^\mathrm{PI} &\leftarrow P^\mathrm{ref} \\ P^{\min} &\leftarrow \min(P^{\min},P^\mathrm{PI}),\quad P^{\max}\leftarrow \max(P^{\max},P^\mathrm{PI}) \\ - u_P^\mathrm{PI} &\leftarrow \text{clamp}^{-1}(P^\mathrm{PI};\,P^{\min},P^{\max}) \\ + u_P^\mathrm{PI} &\leftarrow \text{iclamp}(P^\mathrm{PI};\,P^{\min},P^{\max}) \\ x_P^\mathrm{PI} &\leftarrow u_P^\mathrm{PI} - K_\mathrm{pg}e_P^\mathrm{lim} \\ P^\mathrm{ext} &\leftarrow \dfrac{s_\mathrm{freq}}{k_\mathrm{base}}P^\mathrm{ref} \\ - \dot{V}^\mathrm{meas},\dot{Q}^\mathrm{meas}, \dot{x}_Q^\mathrm{PI},\dot{x}_Q^\mathrm{lag}, \dot{P}^\mathrm{meas},\dot{x}_P^\mathrm{PI},\dot{P}^\mathrm{ref} &\leftarrow 0. + \dot{V}^\mathrm{meas},\dot{Q}^\mathrm{meas}, \dot{x}_Q^\mathrm{PI},\dot{x}_Q^\mathrm{lag}, \dot{P}^\mathrm{meas},\dot{x}_P^\mathrm{PI},\dot{P}^\mathrm{ref} &\leftarrow 0 \end{aligned} ``` If an initial PI output falls outside its configured limits, REPCA expands the -limits to include it and logs a warning. +limits to include it and logs a warning. This matches PowerWorld's default +`Modify Limits and Run` treatment of initial limit violations. Initialization rejects an operating point if: @@ -310,13 +311,13 @@ Initialization is atomic; candidates are validated before state or signal writes V^\mathrm{ref} &\leftarrow V^\mathrm{meas} + s_\mathrm{ref}e_\mathrm{RQ} \\ Q^\mathrm{ref} &\leftarrow Q + \dfrac{s_\mathrm{ref}^\mathrm{off}e_\mathrm{RQ}}{k_\mathrm{base}} \\ P_\mathrm{plant}^\mathrm{ref} &\leftarrow P + \dfrac{e_P-P^\mathrm{freq}}{k_\mathrm{base}} \\ - f^\mathrm{ref} &\leftarrow f + \Delta f_0. + f^\mathrm{ref} &\leftarrow f + \text{ideadband2}(0;\,D_\mathrm{bd1}^{f},D_\mathrm{bd2}^{f}) \end{aligned} ``` -## Monitorable Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `qext` | [p.u.] | Reactive-power command output | $Q^\mathrm{ext}$; system base `pext` | [p.u.] | Active-power command output | $P^\mathrm{ext}$; system base @@ -324,23 +325,6 @@ Output | Units | Description | Note `qmeas` | [p.u.] | Filtered reactive-power signal | $Q^\mathrm{meas}$; component base `pmeas` | [p.u.] | Filtered active-power signal | $P^\mathrm{meas}$; component base -## Testing - -- `validation()` checks defaults, parameter domains, signal contracts, and time floors. -- `initializationAndSignals()` checks reconstruction, bases, signals, monitors, - tags, and selectors. -- `initializationDomain()` checks adjusted and collapsed limits, nonfinite - values, and atomicity. -- `residualEquations()` checks every residual against a fixed answer key. -- `reactiveControl()` checks compensation and reference modes, voltage freeze, - deadbands, smooth limits, anti-windup, and lead-lag behavior. -- `activePowerControl()` checks frequency selection, deadband, droop, smooth - limits, anti-windup, and the output lag. -- `derivatives()` checks differential-row derivative signs. -- `dependencyTracking()` checks fixed numerical and structural Jacobian oracles. -- `jacobian()` checks fixed numerical and structural oracles, plus Enzyme - agreement to $10^{-9}$ when enabled. - ## Appendix A: `droop` ```math @@ -349,7 +333,7 @@ Output | Units | Description | Note ``` where $\sigma$ is GridKit's smooth -[`sigmoid`](../../../../CommonMath.md#primitives). The response preserves +[`sigmoid`](../../../../CommonMath.md#logistic-function). The response preserves $\text{droop}(0;D_\mathrm{dn},D_\mathrm{up})=0$. [^frequency-measurement]: Background for phase-derived, filtered frequency diff --git a/GridKit/Model/PhasorDynamics/Converter/README.md b/GridKit/Model/PhasorDynamics/Converter/README.md index aa937a8b2..f9dcef326 100644 --- a/GridKit/Model/PhasorDynamics/Converter/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/README.md @@ -1,15 +1,8 @@ -# **Converter Models** +# Converter Models -## Introduction - -Converter models represent inverter-coupled resources in the phasor dynamics -model and provide the network interface between renewable-energy controller -models and the bus equations. +Converters provide the network interface for inverter-coupled resources. ## Types -The GridKit converter documentation includes: - -- Renewable Energy Generator/Converter Model REGCA (See [REGCA](REGCA/README.md)) -- Renewable Energy Generator/Converter Model REGCB (See [REGCB](REGCB/README.md)) -- Renewable Energy Electrical Control Model REECA (See [REECA](REECA/README.md)) +- [REGCA](REGCA/README.md): Renewable energy generator/converter +- [REGCB](REGCB/README.md): Renewable energy generator/converter diff --git a/GridKit/Model/PhasorDynamics/Converter/REECA/README.md b/GridKit/Model/PhasorDynamics/Converter/REECA/README.md deleted file mode 100644 index d2a7c743f..000000000 --- a/GridKit/Model/PhasorDynamics/Converter/REECA/README.md +++ /dev/null @@ -1,424 +0,0 @@ -# **Renewable Energy Electrical Control Model (REECA)** - -REECA is a WECC renewable energy electrical control model for inverter-coupled resources. In GridKit it is represented as a signal-control model that computes active- and reactive-current commands. - -Notes: -- Internal electrical quantities and current commands are on model base unless otherwise stated. -- Optional signal inputs default to their documented constant values when omitted. -- Timer-based post-dip reactive-current injection hold and active-current limit hold are not modeled in this version; $T_{\mathrm{hld}}$ and $T_{\mathrm{hld2}}$ must be zero. - -## Block Diagram - -Standard REECA block diagram. - -![](../../../../../docs/Figures/PhasorDynamics_REECA_Diagram.png) - -Figure 1: REECA block diagram. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) - -## Model Parameters - -Symbol | Units | Description | Typical Value | Note -------------------------------------|----------|---------------------------------------------------------|---------------|------ -$S^{\mathrm{base}}$ | [MVA] | REECA model power base | TBD | Block name: `MVABase` -$s_{\mathrm{pf}}$ | [binary] | Power-factor control flag | TBD | Block name: `PfFlag`; 1 = power-factor control, 0 = Q control -$s_V$ | [binary] | Voltage-control mode flag | TBD | Block name: `VFlag`; 1 = Q control, 0 = voltage control -$s_Q$ | [binary] | Reactive-power control flag | TBD | Block name: `QFlag`; 1 = voltage/Q control, 0 = constant pf or Q control -$s_P$ | [binary] | Active-power reference speed-multiplier flag | TBD | Block name: `Pflag`; 1 = multiply by generator speed -$s_{PQ}$ | [binary] | P/Q priority flag for converter current limit | TBD | Block name: `Pqflag`; 0 = Q priority, 1 = P priority -$T_{\mathrm{rv}}$ | [sec] | Voltage-measurement filter time constant | TBD | Block name: `Trv`; if zero, $V_{\mathrm{meas}}$ is algebraic -$T_{\mathrm{p}}$ | [sec] | Electrical-power measurement filter time constant | TBD | Block name: `Tp`; if zero, $P_{\mathrm{meas}}$ is algebraic -$V_{\mathrm{ref0}}$ | [p.u.] | Outer-loop voltage reference | TBD | Block name: `Vref0`; initialized to terminal voltage if omitted -$V_{\mathrm{dip}}$ | [p.u.] | Low-voltage threshold for reactive-current injection logic | TBD | Block name: `Vdip` -$V_{\mathrm{up}}$ | [p.u.] | High-voltage threshold for reactive-current injection logic | TBD | Block name: `Vup` -$D_{\mathrm{bd1}}$ | [p.u.] | Overvoltage deadband for voltage-error response | TBD | Block name: `dbd1` -$D_{\mathrm{bd2}}$ | [p.u.] | Undervoltage deadband for voltage-error response | TBD | Block name: `dbd2` -$K_{\mathrm{qv}}$ | [p.u.] | Reactive-current injection gain during voltage dip/overvoltage logic | TBD | Block name: `kqv` -$I_{\mathrm{qinj}}^{\min}$ | [p.u.] | Minimum reactive-current injection limit | TBD | Block name: `Iql1` -$I_{\mathrm{qinj}}^{\max}$ | [p.u.] | Maximum reactive-current injection limit | TBD | Block name: `Iqh1` -$I_{\mathrm{qinj}}^{\mathrm{frz}}$ | [p.u.] | Held reactive-current injection value after voltage dip | TBD | Block name: `Iqfrz`; unused when $T_{\mathrm{hld}} = 0$ -$T_{\mathrm{hld}}$ | [sec] | Reactive-current injection hold time after voltage dip clears | TBD | Block name: `Thld`; required to be zero in this version -$Q^{\max}$ | [p.u.] | Maximum reactive-power control limit | TBD | Block name: `Qmax` -$Q^{\min}$ | [p.u.] | Minimum reactive-power control limit | TBD | Block name: `Qmin` -$K_{\mathrm{qp}}$ | [p.u.] | Reactive-power control proportional gain | TBD | Block name: `Kqp` -$K_{\mathrm{qi}}$ | [p.u./s] | Reactive-power control integral gain | TBD | Block name: `Kqi` -$V^{\max}$ | [p.u.] | Maximum voltage-control limit | TBD | Block name: `Vmax` -$V^{\min}$ | [p.u.] | Minimum voltage-control limit | TBD | Block name: `Vmin` -$V_{\mathrm{ref1}}$ | [p.u.] | Inner-loop voltage-control reference/bias | 0 | Block name: `Vref1` -$K_{\mathrm{vp}}$ | [p.u.] | Voltage-control proportional gain | TBD | Block name: `Kvp` -$K_{\mathrm{vi}}$ | [p.u./s] | Voltage-control integral gain | TBD | Block name: `Kvi` -$T_{\mathrm{iq}}$ | [sec] | Reactive-current command lag time constant | TBD | Block name: `Tiq` -$T_{\mathrm{pord}}$ | [sec] | Active-power order filter time constant | TBD | Block name: `Tpord` -$R_P^{\max}$ | [p.u./s] | Positive active-power order ramp-rate limit | TBD | Block name: `dPmax` -$R_P^{\min}$ | [p.u./s] | Negative active-power order ramp-rate limit | TBD | Block name: `dPmin` -$P^{\max}$ | [p.u.] | Maximum active-power order limit | TBD | Block name: `Pmax` -$P^{\min}$ | [p.u.] | Minimum active-power order limit | TBD | Block name: `Pmin` -$I^{\max}$ | [p.u.] | Maximum total converter current | TBD | Block name: `Imax` -$V_{\mathrm{q},1}$ | [p.u.] | VDL1 voltage point 1 | TBD | Block name: `vq1` -$I_{\mathrm{q},1}^{\max}$ | [p.u.] | VDL1 reactive-current limit point 1 | TBD | Block name: `lq1` -$V_{\mathrm{q},2}$ | [p.u.] | VDL1 voltage point 2 | TBD | Block name: `vq2` -$I_{\mathrm{q},2}^{\max}$ | [p.u.] | VDL1 reactive-current limit point 2 | TBD | Block name: `lq2` -$V_{\mathrm{q},3}$ | [p.u.] | VDL1 voltage point 3 | TBD | Block name: `vq3` -$I_{\mathrm{q},3}^{\max}$ | [p.u.] | VDL1 reactive-current limit point 3 | TBD | Block name: `lq3` -$V_{\mathrm{q},4}$ | [p.u.] | VDL1 voltage point 4 | TBD | Block name: `vq4` -$I_{\mathrm{q},4}^{\max}$ | [p.u.] | VDL1 reactive-current limit point 4 | TBD | Block name: `lq4` -$V_{\mathrm{p},1}$ | [p.u.] | VDL2 voltage point 1 | TBD | Block name: `vp1` -$I_{\mathrm{p},1}^{\max}$ | [p.u.] | VDL2 active-current limit point 1 | TBD | Block name: `lp1` -$V_{\mathrm{p},2}$ | [p.u.] | VDL2 voltage point 2 | TBD | Block name: `vp2` -$I_{\mathrm{p},2}^{\max}$ | [p.u.] | VDL2 active-current limit point 2 | TBD | Block name: `lp2` -$V_{\mathrm{p},3}$ | [p.u.] | VDL2 voltage point 3 | TBD | Block name: `vp3` -$I_{\mathrm{p},3}^{\max}$ | [p.u.] | VDL2 active-current limit point 3 | TBD | Block name: `lp3` -$V_{\mathrm{p},4}$ | [p.u.] | VDL2 voltage point 4 | TBD | Block name: `vp4` -$I_{\mathrm{p},4}^{\max}$ | [p.u.] | VDL2 active-current limit point 4 | TBD | Block name: `lp4` -$T_{\mathrm{hld2}}$ | [sec] | Active-current limit hold time after voltage dip clears | TBD | Block name: `Thld2`; required to be zero in this version - -### Parameter Validation - -Implementations should reject invalid REECA parameter sets. If source data preprocessing adjusts active-power ramp-rate or order limits, apply these checks to the effective values used by the equations. - -The required checks are: - -```math -\begin{aligned} - &S^{\mathrm{base}} > 0 \\ - &s_{\mathrm{pf}}, s_V, s_Q, s_P, s_{PQ} \in \{0,1\} \\ - &T_{\mathrm{rv}}, T_{\mathrm{p}} \ge 0 \\ - &0 \le V_{\mathrm{dip}} < V_{\mathrm{up}} \\ - &D_{\mathrm{bd1}} \le 0 \le D_{\mathrm{bd2}} \\ - &I_{\mathrm{qinj}}^{\min} \le I_{\mathrm{qinj}}^{\max} \\ - &T_{\mathrm{hld}} = T_{\mathrm{hld2}} = 0 \\ - &Q^{\min} \le Q^{\max} \\ - &V^{\min} \le V^{\max} \\ - &T_{\mathrm{iq}}, T_{\mathrm{pord}} > 0 \\ - &R_P^{\min} < 0 < R_P^{\max} \\ - &P^{\min} \le P^{\max} \\ - &I^{\max} \ge 0 \\ - &0 \le V_{\mathrm{q},1} < V_{\mathrm{q},2} < V_{\mathrm{q},3} < V_{\mathrm{q},4} \\ - &I_{\mathrm{q},k}^{\max} \ge 0\ \text{for } k=1,\ldots,4 \\ - &0 \le V_{\mathrm{p},1} < V_{\mathrm{p},2} < V_{\mathrm{p},3} < V_{\mathrm{p},4} \\ - &I_{\mathrm{p},k}^{\max} \ge 0\ \text{for } k=1,\ldots,4 -\end{aligned} -``` - -### Model Derived Parameters - -The off-mode flag complements are: - -```math -\begin{aligned} - s_{\mathrm{pf}}^{\mathrm{off}} &= 1 - s_{\mathrm{pf}} \\ - s_V^{\mathrm{off}} &= 1 - s_V \\ - s_Q^{\mathrm{off}} &= 1 - s_Q \\ - s_{PQ}^{\mathrm{off}} &= 1 - s_{PQ} -\end{aligned} -``` - -The VDL functions use GridKit's smooth [Linear Segment](../../../../CommonMath.md#derived-functions) helper and provide flat extrapolation outside the first and fourth voltage points: - -```math -\begin{aligned} - g_q(x) &= - I_{\mathrm{q},1}^{\max} - + \sum_{k=1}^{3} - \text{linseg}\!\left( - x;\, - V_{\mathrm{q},k},\, - V_{\mathrm{q},k+1},\, - I_{\mathrm{q},k+1}^{\max} - I_{\mathrm{q},k}^{\max} - \right) \\ - g_p(x) &= - I_{\mathrm{p},1}^{\max} - + \sum_{k=1}^{3} - \text{linseg}\!\left( - x;\, - V_{\mathrm{p},k},\, - V_{\mathrm{p},k+1},\, - I_{\mathrm{p},k+1}^{\max} - I_{\mathrm{p},k}^{\max} - \right) -\end{aligned} -``` - -## Model Variables - -### Internal Variables - -#### Differential - -Symbol | Units | Description | Note -------------------------|--------|-------------------------------------|------ -$V_{\mathrm{meas}}$ | [p.u.] | Filtered terminal voltage | State 1 in Fig. 1; source label: `Vmeas`; algebraic when $T_{\mathrm{rv}} = 0$ -$P_{\mathrm{meas}}$ | [p.u.] | Filtered electrical power | State 2 in Fig. 1; source label: `Pmeas`; algebraic when $T_{\mathrm{p}} = 0$ -$x_{\mathrm{PIQ}}$ | [p.u.] | Reactive-power PI controller state | State 3 in Fig. 1; source label: `PIQ` -$x_{\mathrm{PIV}}$ | [p.u.] | Voltage PI controller state | State 4 in Fig. 1; source label: `PIV` -$Q_V$ | [p.u.] | Reactive-current command lag state | State 5 in Fig. 1; source label: `Q_V` -$P_{\mathrm{ord}}$ | [p.u.] | Filtered active-power order | State 6 in Fig. 1; source label: `Pord` - -#### Algebraic - -Symbol | Units | Description | Note ---------------------------------|--------|-------------------------------------|------ -$V_T$ | [p.u.] | Terminal voltage magnitude | -$V_{\mathrm{meas}}^{\mathrm{safe}}$ | [p.u.] | Safe filtered terminal voltage for divider blocks | Lower bounded by 0.01 -$s_{\mathrm{dip}}$ | [binary] | Voltage-dip/overvoltage freeze indicator | 1 when outside voltage thresholds -$V_{\mathrm{err}}$ | [p.u.] | Deadbanded voltage error | Defined by CommonMath `deadband2` -$I_{\mathrm{qv}}$ | [p.u.] | Reactive-current injection candidate | Converter base -$Q_{\mathrm{ref}}$ | [p.u.] | Selected reactive-power reference | From power-factor or external reactive-power command -$e_Q$ | [p.u.] | Reactive-power control error | Limited $Q_{\mathrm{ref}}$ minus $Q_{\mathrm{gen}}$ -$V_{\mathrm{PIQ}}$ | [p.u.] | Reactive-power control PI output | Limited by $V^{\min}$ and $V^{\max}$ -$e_{\mathrm{PIV}}$ | [p.u.] | Voltage-control PI error | Selected voltage-control signal minus $V_{\mathrm{meas}}$ -$f_{\mathrm{pord}}$ | [p.u./s] | Active-power order derivative before ramp-rate limiting | Feeds $r_{\mathrm{pord}}$ -$r_{\mathrm{pord}}$ | [p.u./s] | Ramp-rate-limited active-power order derivative | Feeds $P_{\mathrm{ord}}$ anti-windup -$I_{\mathrm{q}}^{\mathrm{circ}}$ | [p.u.] | Reactive-current limit from converter current circle | Converter base; nonnegative algebraic branch -$I_{\mathrm{p}}^{\mathrm{circ}}$ | [p.u.] | Active-current limit from converter current circle | Converter base; nonnegative algebraic branch -$I_{\mathrm{q}}^{\max}$ | [p.u.] | Final reactive-current upper limit | Converter base; updated by VDL1 and current-limit logic -$I_{\mathrm{p}}^{\max}$ | [p.u.] | Final active-current upper limit | Converter base; updated by VDL2 and current-limit logic -$I_{\mathrm{qbase}}$ | [p.u.] | Base reactive-current command | Converter base; before $s_Q$ selection and reactive-current injection -$I_{\mathrm{q}}^{\mathrm{raw}}$ | [p.u.] | Raw reactive-current command before final limit | Converter base -$I_{\mathrm{q}}^{\mathrm{cmd}}$ | [p.u.] | Reactive-current command output | Converter base -$I_{\mathrm{p}}^{\mathrm{cmd}}$ | [p.u.] | Active-current command output | Converter base - -### External Variables - -#### Differential - -Symbol | Units | Description | Note ------------|--------|-------------------------|------ -$\omega$ | [p.u.] | Generator speed deviation | Optional, defaults to zero; source diagram $\omega_g = 1 + \omega$ - -#### Algebraic - -Symbol | Units | Description | Note --------------------------------------|--------|-----------------------------------|------ -$V_{\mathrm{r}}$ | [p.u.] | Terminal voltage, real component | Owned by bus object -$V_{\mathrm{i}}$ | [p.u.] | Terminal voltage, imaginary component | Owned by bus object -$P_e$ | [p.u.] | Electrical active power | Source label: `Pe` -$Q_{\mathrm{gen}}$ | [p.u.] | Reactive-power feedback | Source label: `Qgen` -$Q_{\mathrm{ext}}$ | [p.u.] | External reactive-power command | Optional, defaults to initialized constant -$\phi_{\mathrm{pf}}^{\mathrm{ref}}$ | [rad] | Power-factor angle reference | Source label: `pfaref`; used through tangent block -$P_{\mathrm{ref}}$ | [p.u.] | External active-power reference | Optional, defaults to initialized constant - -## Model Equations - -For readability, define: - -```math -\begin{aligned} - f_{\mathrm{PIQ}} &= K_{\mathrm{qi}} e_Q \\ - f_{\mathrm{PIV}} &= K_{\mathrm{vi}} e_{\mathrm{PIV}} -\end{aligned} -``` - -### Differential Equations - -The state-equation residuals use compact limiter notation where applicable. The measurement filters are written in descriptor form: if $T_{\mathrm{rv}} = 0$ or $T_{\mathrm{p}} = 0$, the corresponding variable should be tagged algebraic. The $Q_V$ equation also uses $T_{\mathrm{iq}}$ as a derivative coefficient, but $T_{\mathrm{iq}} > 0$ remains required because the freeze multiplier makes the zero-time case structurally different. - -```math -\begin{aligned} - 0 &= -T_{\mathrm{rv}}\dot V_{\mathrm{meas}} - V_{\mathrm{meas}} + V_T \\ - 0 &= -T_{\mathrm{p}}\dot P_{\mathrm{meas}} - P_{\mathrm{meas}} + P_e \\ - 0 &= - -\dot x_{\mathrm{PIQ}} - + (1 - s_{\mathrm{dip}}) - \text{antiwindup}\!\left( - V_{\mathrm{PIQ}}, - f_{\mathrm{PIQ}}, - V^{\min}, - V^{\max} - \right) \\ - 0 &= - -\dot x_{\mathrm{PIV}} - + (1 - s_{\mathrm{dip}}) - \text{antiwindup}\!\left( - I_{\mathrm{qbase}}, - f_{\mathrm{PIV}}, - -I_{\mathrm{q}}^{\max}, - I_{\mathrm{q}}^{\max} - \right) \\ - 0 &= - -T_{\mathrm{iq}}\dot Q_V - - (1 - s_{\mathrm{dip}})Q_V - + (1 - s_{\mathrm{dip}})Q_{\mathrm{ref}}/V_{\mathrm{meas}}^{\mathrm{safe}} \\ - 0 &= - -\dot P_{\mathrm{ord}} - + (1 - s_{\mathrm{dip}}) - \text{antiwindup}\!\left( - P_{\mathrm{ord}}, - r_{\mathrm{pord}}, - P^{\min}, - P^{\max} - \right) -\end{aligned} -``` - -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. - -### Algebraic Equations - -The algebraic targets use CommonMath helper notation where applicable: - -```math -\begin{aligned} - 0 &= -V_T^2 + V_\mathrm r^2 + V_\mathrm i^2 \\ - 0 &= -V_\mathrm{meas}^\mathrm{safe} + \max(V_\mathrm{meas}, 0.01) \\ - 0 &= -s_\mathrm{dip} + \text{outside}(V_T, V_\mathrm{dip}, V_\mathrm{up}) \\ - 0 &= -V_\mathrm{err} + \text{deadband2}(V_\mathrm{ref0} - V_\mathrm{meas}, D_\mathrm{bd1}, D_\mathrm{bd2}) \\ - 0 &= -I_\mathrm{qv} + \text{clamp}(K_\mathrm{qv} V_\mathrm{err}, I_\mathrm{qinj}^{\min}, I_\mathrm{qinj}^{\max}) \\ - 0 &= -Q_\mathrm{ref} - + s_\mathrm{pf} P_\mathrm{meas}\tan(\phi_\mathrm{pf}^\mathrm{ref}) - + s_\mathrm{pf}^\mathrm{off} Q_\mathrm{ext} \\ - 0 &= -e_Q + \text{clamp}(Q_\mathrm{ref}, Q^{\min}, Q^{\max}) - Q_\mathrm{gen} \\ - 0 &= -V_\mathrm{PIQ} + \text{clamp}(K_\mathrm{qp} e_Q + x_\mathrm{PIQ}, V^{\min}, V^{\max}) \\ - 0 &= -e_\mathrm{PIV} + s_V V_\mathrm{PIQ} + s_V^\mathrm{off}(Q_\mathrm{ref} + V_\mathrm{ref1}) - V_\mathrm{meas} \\ - 0 &= -T_\mathrm{pord} f_\mathrm{pord} + (1 + s_P\omega)P_\mathrm{ref} - P_\mathrm{ord} \\ - 0 &= -r_\mathrm{pord} + \text{clamp}(f_\mathrm{pord}, R_P^{\min}, R_P^{\max}) -\end{aligned} -``` - -```math -\begin{aligned} - 0 &= -{I_\mathrm{q}^\mathrm{circ}}^2 + (I^{\max})^2 - s_{PQ}(I_\mathrm{p}^\mathrm{cmd})^2 \\ - 0 &= -{I_\mathrm{p}^\mathrm{circ}}^2 + (I^{\max})^2 - s_{PQ}^\mathrm{off}(I_\mathrm{q}^\mathrm{cmd})^2 \\ - 0 &= -I_\mathrm{q}^{\max} + \text{min}(g_q(V_\mathrm{meas}), I_\mathrm{q}^\mathrm{circ}) \\ - 0 &= -I_\mathrm{p}^{\max} + \text{min}(g_p(V_\mathrm{meas}), I_\mathrm{p}^\mathrm{circ}) \\ - 0 &= -I_\mathrm{qbase} + \text{clamp}(K_\mathrm{vp} e_\mathrm{PIV} + x_\mathrm{PIV}, -I_\mathrm{q}^{\max}, I_\mathrm{q}^{\max}) \\ - 0 &= -I_\mathrm{q}^\mathrm{raw} + s_Q I_\mathrm{qbase} + s_Q^\mathrm{off} Q_V + s_\mathrm{dip} I_\mathrm{qv} \\ - 0 &= -I_\mathrm{q}^\mathrm{cmd} + \text{clamp}(I_\mathrm{q}^\mathrm{raw}, -I_\mathrm{q}^{\max}, I_\mathrm{q}^{\max}) \\ - 0 &= -I_\mathrm{p}^\mathrm{cmd} + \text{clamp}(P_\mathrm{ord}/V_\mathrm{meas}^\mathrm{safe}, 0, I_\mathrm{p}^{\max}) -\end{aligned} -``` - -The $V_T$, $I_{\mathrm{q}}^{\mathrm{circ}}$, and $I_{\mathrm{p}}^{\mathrm{circ}}$ variables use nonnegative branches of squared algebraic residuals. This preserves the $s_{PQ}=0$ Q-priority and $s_{PQ}=1$ P-priority current-circle behavior without explicit square roots; a consistent solution should satisfy the nonnegative branch and nonnegative radicands. - -CommonMath defines the helper targets and smooth approximations for [min, max, clamp, deadband2, and outside](../../../../CommonMath.md#derived-functions). - -## Initialization - -Initialization is performed by evaluating the steady-state residuals in dependency order. Let subscript $0$ denote initial values and set all internal derivatives to zero. If optional signals are not connected, use steady-state constants: - -```math -\begin{aligned} - V_{T,0} &= \sqrt{V_{\mathrm{r},0}^2 + V_{\mathrm{i},0}^2} \\ - \omega_0 &= 0 \\ - Q_{\mathrm{ext},0} &= Q_{\mathrm{gen},0} \\ - P_{\mathrm{ref},0} &= \dfrac{P_{e,0}}{1+s_P\omega_0} -\end{aligned} -``` - -Connected optional signals use their supplied initial values; if only some are omitted, compute the omitted constants with the connected initial values. Inconsistent supplied commands require a residual solve or initialization rejection. - -If $V_{\mathrm{ref0}}$ is omitted, set $V_{\mathrm{ref0}} = V_{T,0}$. Initialize the measurement variables from the descriptor-form filter residuals: - -```math -\begin{aligned} - V_{\mathrm{meas},0} &= V_{T,0} \\ - P_{\mathrm{meas},0} &= P_{e,0} -\end{aligned} -``` - -When $T_{\mathrm{rv}} = 0$ or $T_{\mathrm{p}} = 0$, the corresponding relation is an algebraic residual rather than a differential-state initial condition. - -Then evaluate the upstream algebraic chain: - -```math -\begin{aligned} - V_{\mathrm{meas},0}^{\mathrm{safe}} &= \text{max}(V_{\mathrm{meas},0}, 0.01) \\ - s_{\mathrm{dip},0} &= \text{outside}(V_{T,0}, V_{\mathrm{dip}}, V_{\mathrm{up}}) \\ - V_{\mathrm{err},0} &= \text{deadband2}(V_{\mathrm{ref0}} - V_{\mathrm{meas},0}, D_{\mathrm{bd1}}, D_{\mathrm{bd2}}) \\ - I_{\mathrm{qv},0} &= \text{clamp}(K_{\mathrm{qv}} V_{\mathrm{err},0}, I_{\mathrm{qinj}}^{\min}, I_{\mathrm{qinj}}^{\max}) \\ - Q_{\mathrm{ref},0} &= s_{\mathrm{pf}} P_{\mathrm{meas},0}\tan(\phi_{\mathrm{pf},0}^{\mathrm{ref}}) + s_{\mathrm{pf}}^{\mathrm{off}} Q_{\mathrm{ext},0} \\ - e_{Q,0} &= \text{clamp}(Q_{\mathrm{ref},0}, Q^{\min}, Q^{\max}) - Q_{\mathrm{gen},0} \\ - Q_{V,0} &= \dfrac{Q_{\mathrm{ref},0}}{V_{\mathrm{meas},0}^{\mathrm{safe}}} \\ - P_{\mathrm{ord},0} &= (1+s_P\omega_0)P_{\mathrm{ref},0} -\end{aligned} -``` - -Initialize the reactive-power PI output so its residual and zero-derivative anti-windup condition hold: - -```math -\begin{aligned} - V_{\mathrm{PIQ},0} &= \text{clamp}(K_{\mathrm{qp}} e_{Q,0} + x_{\mathrm{PIQ},0}, V^{\min}, V^{\max}) \\ - e_{\mathrm{PIV},0} &= s_V V_{\mathrm{PIQ},0} + s_V^{\mathrm{off}}(Q_{\mathrm{ref},0} + V_{\mathrm{ref1}}) - V_{\mathrm{meas},0} -\end{aligned} -``` - -For an unsaturated zero-derivative start, require $e_{Q,0}=0$ for $x_{\mathrm{PIQ}}$ and choose or verify $e_{\mathrm{PIV},0}=0$ for $x_{\mathrm{PIV}}$. Then $x_{\mathrm{PIQ},0}=V_{\mathrm{PIQ},0}-K_{\mathrm{qp}}e_{Q,0}$; when $s_V=1$, set $V_{\mathrm{PIQ},0}=V_{\mathrm{meas},0}$, and when $s_V=0$, the supplied $Q_{\mathrm{ref},0}+V_{\mathrm{ref1}}$ must equal $V_{\mathrm{meas},0}$. Saturated initial conditions should be solved against the anti-windup residuals, not forced by this unsaturated formula. - -Finish by evaluating $g_q(V_{\mathrm{meas},0})$, $g_p(V_{\mathrm{meas},0})$, and the current-limit and current-command algebraic residuals in priority order. At the command steps, use the power-flow current targets before final limiting: - -```math -\begin{aligned} - I_{\mathrm{qbase},0}^{\star} &= \dfrac{Q_{\mathrm{gen},0}}{V_{\mathrm{meas},0}^{\mathrm{safe}}} \\ - I_{\mathrm{p},0}^{\star} &= \dfrac{P_{\mathrm{ord},0}}{V_{\mathrm{meas},0}^{\mathrm{safe}}} -\end{aligned} -``` - -For $s_{PQ}=0$, use: - -```math -\begin{aligned} -I_{\mathrm{q},0}^{\mathrm{circ}} -\rightarrow I_{\mathrm{q},0}^{\max} -\rightarrow I_{\mathrm{qbase},0} -\rightarrow I_{\mathrm{q},0}^{\mathrm{raw}} -\rightarrow I_{\mathrm{q},0}^{\mathrm{cmd}} -\rightarrow I_{\mathrm{p},0}^{\mathrm{circ}} -\rightarrow I_{\mathrm{p},0}^{\max} -\rightarrow I_{\mathrm{p},0}^{\mathrm{cmd}} -\end{aligned} -``` - -For $s_{PQ}=1$, use: - -```math -\begin{aligned} -I_{\mathrm{p},0}^{\mathrm{circ}} -\rightarrow I_{\mathrm{p},0}^{\max} -\rightarrow I_{\mathrm{p},0}^{\mathrm{cmd}} -\rightarrow I_{\mathrm{q},0}^{\mathrm{circ}} -\rightarrow I_{\mathrm{q},0}^{\max} -\rightarrow I_{\mathrm{qbase},0} -\rightarrow I_{\mathrm{q},0}^{\mathrm{raw}} -\rightarrow I_{\mathrm{q},0}^{\mathrm{cmd}} -\end{aligned} -``` - -After $I_{\mathrm{q},0}^{\max}$ and $I_{\mathrm{qbase},0}$ are known, initialize the voltage PI state from its output residual; the unsaturated zero-derivative start also requires the $e_{\mathrm{PIV},0}=0$ condition above: - -```math -x_{\mathrm{PIV},0} = I_{\mathrm{qbase},0} - K_{\mathrm{vp}} e_{\mathrm{PIV},0} -``` - -The current-circle variables use the nonnegative branch of the squared algebraic residuals; initialization must reject negative radicands. A standard steady-state initialization assumes $s_{\mathrm{dip},0}=0$. If initialized during voltage-dip or overvoltage logic, $Q_V$, $P_{\mathrm{ord}}$, and the PI histories are not uniquely determined without the unsupported hold-timer histories, so the implementation should solve a saturation-consistent state or reject the start. - -## Model Outputs - -Output | Units | Description | Note -----------------|--------|-------------------------------------|------ -`iqcmd` | [p.u.] | Reactive-current command output | Converter base -`ipcmd` | [p.u.] | Active-current command output | Converter base -`vmeas` | [p.u.] | Filtered terminal voltage | -`pmeas` | [p.u.] | Filtered electrical power | -`piq` | [p.u.] | Reactive-power PI controller state | -`piv` | [p.u.] | Voltage PI controller state | -`qv` | [p.u.] | Reactive-current command lag state | -`pord` | [p.u.] | Filtered active-power order | -`qref` | [p.u.] | Selected reactive-power reference | -`sdip` | [binary] | Voltage-dip/overvoltage freeze indicator | -`iqmax` | [p.u.] | Final reactive-current upper limit | Converter base -`ipmax` | [p.u.] | Final active-current upper limit | Converter base -`iqv` | [p.u.] | Reactive-current injection candidate | Converter base -`vqctrl` | [p.u.] | Reactive-power control PI output | -`iqbase` | [p.u.] | Base reactive-current command | Converter base - -## Outstanding - -Nonzero $T_{\mathrm{hld}}$ and $T_{\mathrm{hld2}}$ require timer/history-state support and are not modeled yet. With the required zero values, $I_{\mathrm{qinj}}^{\mathrm{frz}}$ is unreachable and $I_{\mathrm{p}}^{\max}$ is recalculated from VDL2 and current-circle logic at each residual evaluation instead of held after voltage recovery. - -A future smooth approximation of the held reactive-current path could introduce a continuous gate $h_q$: - -```math -\dot h_q = - \dfrac{1}{T_{\mathrm{rise}}} s_{\mathrm{dip}}(1-h_q) - - \dfrac{1}{T_{\mathrm{hld}}} (1-s_{\mathrm{dip}})h_q -``` - -That approximation is a modeling choice and is not part of the present equations. diff --git a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md index 7eecfbd7a..c7b849bca 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md @@ -1,4 +1,4 @@ -# **Renewable Energy Generator/Converter Model (REGCA)** +# REGCA REGCA is a first-generation WECC renewable generator/converter model for inverter-coupled resources. @@ -16,37 +16,36 @@ Figure 1: REGCA generator/converter model. Figure courtesy of the ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note ----------------------------------|----------|----------|-------------------------------------------------------|---------------|------ -$P_0$ | [p.u.] | `p0` | Initial active power injection | 1.0 | System base; required initialization source -$Q_0$ | [p.u.] | `q0` | Initial reactive power injection | 0.0 | System base; required initialization source -$S^\mathrm{base}$ | [MVA] | `mva` | REGCA component power base | 100.0 | -$T_\mathrm{g}$ | [sec] | `Tg` | Converter current-control lag time constant | 0.02 | Block name: `Tg` -$T_M$ | [sec] | `TM` | Terminal voltage sensor time constant | 0.02 | Block name: `Tfltr` -$R_q^{\max}$ | [p.u./s] | `Rqmax` | Reactive-current recovery positive rate limit | 999.0 | Block name: `Iqrmax`; disabled when $R_q^{\max}\le 0$ -$R_q^{\min}$ | [p.u./s] | `Rqmin` | Reactive-current recovery negative rate limit | -999.0 | Block name: `Iqrmin`; disabled when $R_q^{\min}\ge 0$ -$R_p^{\max}$ | [p.u./s] | `Rpmax` | Active-current magnitude recovery rate limit | 999.0 | Block name: `rrpwr`; must be nonnegative -$s_L$ | [binary] | `sL` | LVPL switch | 1 | Block name: `LPVLSW` -$I_{L1}$ | [p.u.] | `IL1` | LVPL upper-current ceiling | 1.1 | Block name: `LVPL1` -$V_{L0}$ | [p.u.] | `VL0` | LVPL zero-crossing voltage | 0.4 | Block name: `zerox` -$V_{L1}$ | [p.u.] | `VL1` | LVPL upper breakpoint voltage | 0.9 | Block name: `brkpt` -$V_{A0}$ | [p.u.] | `VA0` | LVACM lower breakpoint voltage | 0.4 | Block name: `LVPnt0` -$V_{A1}$ | [p.u.] | `VA1` | LVACM upper breakpoint voltage | 0.9 | Block name: `LVPnt1` -$V_\mathrm{hv}^{\max}$ | [p.u.] | `Vhvmax` | HV reactive management activation threshold | 1.2 | Block name: `VLim` -$Q^{\min}$ | [p.u.] | `Qmin` | PowerWorld compatibility field | | Optional; accepted but unused -$K_\mathrm{hv}$ | [p.u.] | `Khv` | HV reactive management gain | 0.7 | Optional; defaults to 0.7; block name: `Khv` -$X_\mathrm{e}$ | [p.u.] | `Xe` | PowerWorld compatibility field | | Optional; accepted but unused +Symbol | Units | JSON | Description | Typical Value | Note +-----------------------|----------|----------|-----------------------------------------------|---------------|-------------------------------------------------------- +$P_0$ | [p.u.] | `p0` | Initial active power injection | 1.0 | System base; required initialization source +$Q_0$ | [p.u.] | `q0` | Initial reactive power injection | 0.0 | System base; required initialization source +$S^\mathrm{base}$ | [MVA] | `mva` | REGCA component power base | 100.0 | +$T_\mathrm{g}$ | [s] | `Tg` | Converter current-control lag time constant | 0.02 | +$T_M$ | [s] | `TM` | Terminal voltage sensor time constant | 0.02 | Source label: `Tfltr` +$R_q^{\max}$ | [p.u./s] | `Rqmax` | Reactive-current recovery positive rate limit | 999.0 | Source label: `Iqrmax`; disabled when $R_q^{\max}\le 0$ +$R_q^{\min}$ | [p.u./s] | `Rqmin` | Reactive-current recovery negative rate limit | -999.0 | Source label: `Iqrmin`; disabled when $R_q^{\min}\ge 0$ +$R_p^{\max}$ | [p.u./s] | `Rpmax` | Active-current magnitude recovery rate limit | 999.0 | Source label: `rrpwr`; must be nonnegative +$s_L$ | [binary] | `sL` | LVPL switch | 1 | Source label: `LPVLSW` +$I_{L1}$ | [p.u.] | `IL1` | LVPL upper-current ceiling | 1.1 | Source label: `LVPL1` +$V_{L0}$ | [p.u.] | `VL0` | LVPL zero-crossing voltage | 0.4 | Source label: `zerox` +$V_{L1}$ | [p.u.] | `VL1` | LVPL upper breakpoint voltage | 0.9 | Source label: `brkpt` +$V_{A0}$ | [p.u.] | `VA0` | LVACM lower breakpoint voltage | 0.4 | Source label: `LVPnt0` +$V_{A1}$ | [p.u.] | `VA1` | LVACM upper breakpoint voltage | 0.9 | Source label: `LVPnt1` +$V_\mathrm{hv}^{\max}$ | [p.u.] | `Vhvmax` | HV reactive management activation threshold | 1.2 | Source label: `VLim` +$Q^{\min}$ | [p.u.] | `Qmin` | PowerWorld compatibility field | | Optional; accepted but unused +$K_\mathrm{hv}$ | [p.u.] | `Khv` | HV reactive management gain | 0.7 | Optional; defaults to 0.7; block name: `Khv` +$X_\mathrm{e}$ | [p.u.] | `Xe` | PowerWorld compatibility field | | Optional; accepted but unused All listed JSON parameters are required unless marked optional. ### Parameter Validation -Invalid REGCA parameter sets are rejected by the following checks. Let $\epsilon_T=10^{-3}$. -Time constants below $\epsilon_T$ are raised to $\epsilon_T$ and logged as a warning, -every other condition is a configuration error. +A valid REGCA parameter set must satisfy the following conditions: ```math \begin{aligned} + \epsilon_T &= 10^{-3} \\ T &\leftarrow \max(T, \epsilon_T) \quad T\in\{T_\mathrm{g},T_M\} \\ S^\mathrm{base} @@ -55,6 +54,8 @@ every other condition is a configuration error. &\ge 0 \\ I_{L1} &\ge 0 \\ + K_L + &> 0 \\ s_L &\in \{0,1\} \\ 0 @@ -66,6 +67,9 @@ every other condition is a configuration error. \end{aligned} ``` +Time constants below $\epsilon_T$ are raised to $\epsilon_T$ and logged as a warning, +every other condition is a configuration error. + ### Model Derived Parameters ```math @@ -108,15 +112,15 @@ $I_p$ | [p.u.] | Active-current state | State 2 in Fig. 1; #### Algebraic -Symbol | Units | Description | Note ----------------------------|----------|-----------------------------------------------------------------------|------ -$V_T$ | [p.u.] | Terminal voltage magnitude | -$I_\mathrm{r}$ | [p.u.] | Branch-current real component | System base -$I_\mathrm{i}$ | [p.u.] | Branch-current imaginary component | System base -$I_q^\mathrm{extra}$ | [p.u.] | Extra inductive current from high-voltage reactive current management | Component base -$I_L$ | [p.u.] | LVPL upper-limit current curve | Component base; function of $V_M$ -$P^\mathrm{br}$ | [p.u.] | Branch active power | System base -$Q^\mathrm{br}$ | [p.u.] | Branch reactive power | System base +Symbol | Units | Description | Note +---------------------|--------|-----------------------------------------------------------------------|---------------------------------- +$V_T$ | [p.u.] | Terminal voltage magnitude | +$I_r$ | [p.u.] | Branch-current real component | System base +$I_i$ | [p.u.] | Branch-current imaginary component | System base +$I_q^\mathrm{extra}$ | [p.u.] | Extra inductive current from high-voltage reactive current management | Component base +$I_L$ | [p.u.] | LVPL upper-limit current curve | Component base; function of $V_M$ +$P^\mathrm{br}$ | [p.u.] | Branch active power | System base +$Q^\mathrm{br}$ | [p.u.] | Branch reactive power | System base ### External Variables @@ -125,15 +129,17 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note ---------------------------------|--------|---------|------------------------------------------------------------------|------ -$V_\mathrm{r}$ | [p.u.] | Known | Terminal voltage, real component | Bus input -$V_\mathrm{i}$ | [p.u.] | Known | Terminal voltage, imaginary component | Bus input -$I_p^\mathrm{cmd}$ | [p.u.] | Unknown | Active-current command in the terminal-voltage reference frame | Optional signal port `ipcmd`; system base -$I_q^\mathrm{cmd}$ | [p.u.] | Unknown | Reactive-current command in the terminal-voltage reference frame | Optional signal port `iqcmd`; system base +Symbol | Units | Description | Note +-------------------|--------|------------------------------------------------------------------|------------------------------------------ +$V_r$ | [p.u.] | Terminal voltage, real component | Bus input +$V_i$ | [p.u.] | Terminal voltage, imaginary component | Bus input +$I_p^\mathrm{cmd}$ | [p.u.] | Active-current command in the terminal-voltage reference frame | Optional signal port `ipcmd`; system base +$I_q^\mathrm{cmd}$ | [p.u.] | Reactive-current command in the terminal-voltage reference frame | Optional signal port `iqcmd`; system base ## Model Equations +Smooth functions: [`clamp`](../../../../CommonMath.md#clamp), [`linseg`](../../../../CommonMath.md#linear-segment), [`max`](../../../../CommonMath.md#maximum), [`min`](../../../../CommonMath.md#minimum), [$\rho$](../../../../CommonMath.md#ramp). + Define the pre-limit current derivatives: ```math @@ -153,12 +159,14 @@ of [Appendix A](#appendix-a-rrpwr): ```math f_\mathrm{p}^{\lim} - = \text{rrpwr}(I_p, f_\mathrm{p}; R_p^{\max}). + = \text{rrpwr}(I_p, f_\mathrm{p}; R_p^{\max}) ``` -### Differential Equations +### Internal Equations + +#### Differential -The $I_q$ limiter branch is selected by the initial reactive power $Q_0$ and +The $I_q$ limiter branch is selected by the configured reactive power $Q_0$ and the sign that enables the corresponding limit. ```math @@ -180,39 +188,35 @@ the sign that enables the corresponding limit. \end{aligned} ``` - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} - 0 &= -V_T^2 + V_\mathrm{r}^2 + V_\mathrm{i}^2 \\ - 0 &= -k_\mathrm{base} V_T I_\mathrm{r} - + V_\mathrm{i}(I_q - I_q^\mathrm{extra}) - + V_\mathrm{r} I_p\,\text{linseg}(V_T; V_{A0}, V_{A1}, 1) \\ - 0 &= -k_\mathrm{base} V_T I_\mathrm{i} - - V_\mathrm{r}(I_q - I_q^\mathrm{extra}) - + V_\mathrm{i} I_p\,\text{linseg}(V_T; V_{A0}, V_{A1}, 1) \\ + 0 &= -V_T^2 + V_r^2 + V_i^2 \\ + 0 &= -k_\mathrm{base} V_T I_r + + V_i(I_q - I_q^\mathrm{extra}) + + V_r I_p\,\text{linseg}(V_T; V_{A0}, V_{A1}, 1) \\ + 0 &= -k_\mathrm{base} V_T I_i + - V_r(I_q - I_q^\mathrm{extra}) + + V_i I_p\,\text{linseg}(V_T; V_{A0}, V_{A1}, 1) \\ 0 &= -I_q^\mathrm{extra} + K_\mathrm{hv}\,\text{ramp}(V_T - V_\mathrm{hv}^{\max}) \\ 0 &= -I_L + \text{linseg}(V_M; V_{L0}, V_{L1}, I_{L1}) + K_L\,\text{ramp}(V_M - V_{L1}) \\ 0 &= -P^\mathrm{br} - + V_\mathrm{r} I_\mathrm{r} + V_\mathrm{i} I_\mathrm{i} \\ + + V_r I_r + V_i I_i \\ 0 &= -Q^\mathrm{br} - + V_\mathrm{i} I_\mathrm{r} - V_\mathrm{r} I_\mathrm{i} + + V_i I_r - V_r I_i \end{aligned} ``` -CommonMath defines the [primitives](../../../../CommonMath.md#primitives) and -[derived functions](../../../../CommonMath.md#derived-functions) used above. - -## Network Interface +### External Equations ```math \begin{aligned} - I_\mathrm{r}^\mathrm{inj} &:= I_\mathrm{r} \\ - I_\mathrm{i}^\mathrm{inj} &:= I_\mathrm{i} + I_r^\mathrm{inj} &:= I_r \\ + I_i^\mathrm{inj} &:= I_i \end{aligned} ``` @@ -222,62 +226,29 @@ CommonMath defines the [primitives](../../../../CommonMath.md#primitives) and ```math \begin{aligned} - V_\mathrm{r}, V_\mathrm{i} - &\leftarrow \text{terminal-bus voltage} \\ - P_0, Q_0 - &\leftarrow \text{power-flow injection on system base} + V_r,V_i &\leftarrow \text{terminal-bus voltage} \\ + P_0,Q_0 &\leftarrow \text{power-flow injection on system base} \end{aligned} ``` ### Internal Initialization -REGCA requires $V_{A1} \le V_{T,0}$, which excludes initialization below the -nominal upper LVACM breakpoint. - -With LVPL enabled, REGCA additionally requires $I_{p,0} \le I_{L,0}$. -Initialization rejects an operating point above the active-current integrator -ceiling. - -Subscript $0$ denotes initial values; all internal derivatives are initialized -to zero: - -```math -\begin{aligned} - V_{T,0} - &= \sqrt{V_{\mathrm{r},0}^2 + V_{\mathrm{i},0}^2} \\ - V_{M,0} - &= V_{T,0} \\ - A_0^\mathrm{LVACM} - &= \text{linseg}(V_{T,0}; V_{A0}, V_{A1}, 1) \\ - I_{L,0} - &= \text{linseg}(V_{T,0}; V_{L0}, V_{L1}, I_{L1}) - + K_L\,\text{ramp}(V_{T,0} - V_{L1}) \\ - I_{p,0} - &= \dfrac{k_\mathrm{base}P_0}{V_{T,0}A_0^\mathrm{LVACM}} \\ - k_\mathrm{base} I_{p,0}^\mathrm{cmd} - &= I_{p,0} \\ - I_{q,0}^\mathrm{extra} - &= K_\mathrm{hv}\,\text{ramp}(V_{T,0} - V_\mathrm{hv}^{\max}) \\ - I_{q,0}^\mathrm{cmd} - &= \dfrac{Q_0}{V_{T,0}} - + \dfrac{I_{q,0}^\mathrm{extra}}{k_\mathrm{base}} \\ - I_{q,0} - &= k_\mathrm{base} I_{q,0}^\mathrm{cmd} -\end{aligned} -``` - -The remaining algebraic quantities are then initialized as follows: +Initialization requires $V_{A1}\le V_T$ and, with LVPL enabled, $I_p\le I_L$. +All internal derivatives initialize to zero. ```math \begin{aligned} - I_{\mathrm{r},0} - &= \dfrac{V_{\mathrm{r},0}P_0 + V_{\mathrm{i},0}Q_0}{V_{T,0}^2} \\ - I_{\mathrm{i},0} - &= \dfrac{V_{\mathrm{i},0}P_0 - V_{\mathrm{r},0}Q_0}{V_{T,0}^2} \\ - P_0^\mathrm{br} - &= P_0 \\ - Q_0^\mathrm{br} - &= Q_0 + V_T &\leftarrow \sqrt{V_r^2+V_i^2} \\ + V_M &\leftarrow V_T \\ + I_L &\leftarrow \text{linseg}(V_T;V_{L0},V_{L1},I_{L1}) + +K_L\,\text{ramp}(V_T-V_{L1}) \\ + I_p &\leftarrow \dfrac{k_\mathrm{base}P_0}{V_T\,\text{linseg}(V_T;V_{A0},V_{A1},1)} \\ + I_q^\mathrm{extra} &\leftarrow K_\mathrm{hv}\,\text{ramp}(V_T-V_\mathrm{hv}^{\max}) \\ + I_q &\leftarrow \dfrac{k_\mathrm{base}Q_0}{V_T}+I_q^\mathrm{extra} \\ + I_r &\leftarrow \dfrac{V_rP_0+V_iQ_0}{V_T^2} \\ + I_i &\leftarrow \dfrac{V_iP_0-V_rQ_0}{V_T^2} \\ + P^\mathrm{br} &\leftarrow P_0 \\ + Q^\mathrm{br} &\leftarrow Q_0 \end{aligned} ``` @@ -285,36 +256,20 @@ The remaining algebraic quantities are then initialized as follows: ```math \begin{aligned} - I_p^\mathrm{cmd} - &\leftarrow I_{p,0}^\mathrm{cmd} \\ - I_q^\mathrm{cmd} - &\leftarrow I_{q,0}^\mathrm{cmd} + I_p^\mathrm{cmd} &\leftarrow \dfrac{I_p}{k_\mathrm{base}} \\ + I_q^\mathrm{cmd} &\leftarrow \dfrac{I_q}{k_\mathrm{base}} \end{aligned} ``` -## Monitorable Outputs +## Monitors -Output | Units | Description | Note --------|--------|-----------------------------|------ +Monitor | Units | Description | Note +--------|--------|-----------------------------|------ `ir` | [p.u.] | Real current injection | System base; exported through `ibranchr` when assigned `ii` | [p.u.] | Imaginary current injection | System base; exported through `ibranchi` when assigned `p` | [p.u.] | Active-power output | System base; exported through `pbranch` when assigned `q` | [p.u.] | Reactive-power output | System base; exported through `qbranch` when assigned -## Testing - -- `validation()` checks construction, monitor creation, parameter validation, bus and signal configuration, and minimum time-constant handling. -- `initializationAndSignals()` checks power-flow initialization, base conversion, signal publication, bus injection, and unattached-command latching. -- `initializationDomain()` checks rejected and accepted voltage and LVPL initialization boundaries. -- `residualEquations()` checks every model residual at a hand-computable midpoint state. -- `activeCurrentControl()` checks `rrpwr`, enabled and bypassed LVPL behavior, and tracking of a moving LVPL ceiling. -- `reactiveCurrentControl()` checks the positive, negative, and unrestricted reactive-current recovery-rate branches. -- `highVoltageManagement()` checks HVRCM initialization, $K_\mathrm{hv}$ loading, threshold behavior, and its local derivative. -- `jacobian()` compares the dependency-tracking and Enzyme Jacobians for enabled and bypassed LVPL configurations when Enzyme support is enabled. - -Tests use model identities rather than frozen smoothing decimals and reserve -$100 \epsilon$ for roundoff checks. - ## Appendix A: `rrpwr` The exact active-current rate-limit rule is @@ -339,10 +294,11 @@ The model evaluates this rule with the following continuously differentiable \text{rrpwr}(x,f;r) &\approx f +\left[1-w_+(x)\right]\text{ramp}(-f-r) - -\left[1-w_-(x)\right]\text{ramp}(f-r). + -\left[1-w_-(x)\right]\text{ramp}(f-r) \end{aligned} ``` +Where $\sigma$ is GridKit's smooth [`sigmoid`](../../../../CommonMath.md#logistic-function). The one-sided weights and their first derivatives vanish at $x=0$. The approximation therefore equals `slew` exactly at zero and preserves the outward rate limit for finite $\mu$ while gradually releasing restoring motion. @@ -371,7 +327,7 @@ The model evaluates this rule with the following smooth approximation: ```math \text{awmax}(x, f; u, \dot u) \approx \dot u - + \left[\sigma(u-x)+\left(1-\sigma(u-x)\right)\sigma(\dot u-f)\right] + + \left[\sigma(u-x)+(1-\sigma(u-x))\sigma(\dot u-f)\right] (f - \dot u) ``` diff --git a/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md b/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md index 32f86f38d..ac6366d41 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md @@ -1,34 +1,29 @@ -# **Renewable Energy Generator/Converter Model (REGCB)** +# REGCB REGCB is a WECC renewable energy generator/converter model for inverter-coupled -resources. This document is a skeleton for the model specification; parameters, -equations, initialization details, and default values must be validated against -the REGCB source standard before implementation. +resources. ## Block Diagram -Standard model diagram for the REGCB converter interface. - ![](../../../../../docs/Figures/PhasorDynamics_REGCB_Diagram.png) Figure 1: Generator/Converter REGCB model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) -Detailed REGCB parameters, variables, equations, initialization details, and -outputs will be added after validation against the REGCB source standard. - - +TBD. diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md index 07a3ccfda..cdc114d67 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md @@ -1,11 +1,16 @@ -# **IEEE Type AC6A Excitation System Model (ESAC6A)** +# ESAC6A ESAC6A is an IEEE Type AC excitation system with sensed terminal-voltage -feedback, cascaded regulator lead-lag blocks, voltage-regulator limits, an +feedback, cascaded regulator lead–lag blocks, voltage-regulator limits, an exciter alternator state, field-current feedback limiting, rectifier loading, saturation, and optional speed multiplier. -Notes: +> [!WARNING] +> Initialization does not yet invert the smooth gates and limits used by the +> model equations. + +## 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. @@ -14,44 +19,42 @@ Notes: ## Block Diagram -Standard model of the ESAC6A Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/ESAC6A_diagram.png) Figure 1: Exciter ESAC6A model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -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 -$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | Block name: `Ka` -$T_A$ | [sec] | `Ta` | Regulator denominator time constant | 0.1 | Block name: `Ta` -$T_K$ | [sec] | `Tk` | Regulator numerator time constant | 0.0 | Block name: `Tk` -$T_B$ | [sec] | `Tb` | Lag time constant for second lead-lag block | 0.0 | Block name: `Tb` -$T_C$ | [sec] | `Tc` | Lead time constant for second lead-lag block | 0.0 | Block name: `Tc` -$V_A^{\max}$ | [p.u.] | `VaMax` | Maximum first regulator block output | 1.0 | Block name: `VAMAX` -$V_A^{\min}$ | [p.u.] | `VaMin` | Minimum first regulator block output | -1.0 | Block name: `VAMIN` -$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` -$V_{\mathrm{fe}}^{\mathrm{lim}}$ | [p.u.] | `Vfelim` | Feedback-limiter summing-junction reference | 0.0 | Source label: `VFELIM` -$K_H$ | [p.u.] | `Kh` | Feedback-limiter gain | 1.0 | Block name: `KH` -$V_H^{\max}$ | [p.u.] | `Vhmax` | Maximum feedback-limiter lead-lag output | 1.0 | Block name: `VHMAX`; lower limit is zero -$T_H$ | [sec] | `Th` | Feedback-limiter denominator time constant | 0.0 | Block name: `TH` -$T_J$ | [sec] | `Tj` | Feedback-limiter numerator time constant | 0.0 | Block name: `TJ` -$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 +Symbol | Units | JSON | Description | Typical Value | Note +---------------------------------|----------|----------|----------------------------------------------|---------------|------------------------------------------- +$T_R$ | [s] | `Tr` | Transducer time constant | 0.0 | if zero, $V_C$ is algebraic +$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | +$T_A$ | [s] | `Ta` | Regulator denominator time constant | 0.1 | +$T_K$ | [s] | `Tk` | Regulator numerator time constant | 0.0 | +$T_B$ | [s] | `Tb` | Lag time constant for second lead–lag block | 0.0 | +$T_C$ | [s] | `Tc` | Lead time constant for second lead–lag block | 0.0 | +$V_A^{\max}$ | [p.u.] | `VaMax` | Maximum first regulator block output | 1.0 | Source label: `VAMAX` +$V_A^{\min}$ | [p.u.] | `VaMin` | Minimum first regulator block output | -1.0 | Source label: `VAMIN` +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | +$T_E$ | [s] | `Te` | Exciter alternator time constant | 0.5 | +$V_{\mathrm{FE}}^{\mathrm{lim}}$ | [p.u.] | `Vfelim` | Feedback-limiter summing-junction reference | 0.0 | Source label: `VFELIM` +$K_H$ | [p.u.] | `Kh` | Feedback-limiter gain | 1.0 | Source label: `KH` +$V_H^{\max}$ | [p.u.] | `Vhmax` | Maximum feedback-limiter lead–lag output | 1.0 | Source label: `VHMAX`; lower limit is zero +$T_H$ | [s] | `Th` | Feedback-limiter denominator time constant | 0.0 | Source label: `TH` +$T_J$ | [s] | `Tj` | Feedback-limiter numerator time constant | 0.0 | Source label: `TJ` +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | forms $I_N$ +$K_D$ | [p.u.] | `Kd` | Demagnetizing factor feedback gain | 0.0 | +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Source label: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Source label: `Se2` +$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | 1 enables the speed multiplier ### Parameter Validation -Invalid ESAC6A parameter sets are rejected by the following checks. +A valid ESAC6A parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -81,35 +84,47 @@ saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +--------|--------|------|------------ +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`speed` | Input | TBD | Machine speed deviation $\omega$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -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$ -$x_A$ | [p.u.] | First regulator lead-lag denominator state | State 3 in Fig. 1; source label: `TA Block` -$x_{\mathrm{ll}}$ | [p.u.] | Second lead-lag denominator state | State 4 in Fig. 1; source label: `VLL` -$V_F$ | [p.u.] | Stabilizing feedback signal | State 5 in Fig. 1; source label: `VF` +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$ +$x_A$ | [p.u.] | First regulator lead–lag denominator state | State 3 in Fig. 1; Source label: `TA Block` +$x_{\mathrm{LL}}$ | [p.u.] | Second lead–lag denominator state | State 4 in Fig. 1; Source label: `VLL` +$V_F$ | [p.u.] | Stabilizing feedback signal | State 5 in Fig. 1; Source label: `VF` #### Algebraic -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$e_V$ | [p.u.] | Voltage-regulator input error before first lead-lag | Summing junction after sensed voltage -$V_A$ | [p.u.] | Limited first regulator lead-lag output | Limited by $V_A^{\min}$ and $V_A^{\max}$ -$V_{\mathrm{ll}}$ | [p.u.] | Second lead-lag output | Input to $V_R$ summing junction -$V_H$ | [p.u.] | Feedback-limiter lead-lag output before $K_H$ | Limited by 0 and $V_H^{\max}$ -$V_H^{\mathrm{pre}}$ | [p.u.] | Feedback-limiter lead-lag output before limits | Bypasses to $V_F$ when $T_H=T_J=0$ -$V_R$ | [p.u.] | Voltage-regulator output | Limited by $V_R^{\min}$ and $V_R^{\max}$ -$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, $K_D I_{\mathrm{fd}}$, and feedback-limiter paths -$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after rectifier loading and optional speed multiplier +Symbol | Units | Description | Note +---------------------|--------|-----------------------------------------------------|-------------------------------------------------------------------------------- +$e_V$ | [p.u.] | Voltage-regulator input error before first lead–lag | Summing junction after sensed voltage +$V_A$ | [p.u.] | Limited first regulator lead–lag output | Limited by $V_A^{\min}$ and $V_A^{\max}$ +$V_{\mathrm{LL}}$ | [p.u.] | Second lead–lag output | Input to $V_R$ summing junction +$V_H$ | [p.u.] | Feedback-limiter lead–lag output before $K_H$ | Limited by 0 and $V_H^{\max}$ +$V_H^{\mathrm{pre}}$ | [p.u.] | Feedback-limiter lead–lag output before limits | Bypasses to $V_F$ when $T_H=T_J=0$ +$V_R$ | [p.u.] | Voltage-regulator output | Limited by $V_R^{\min}$ and $V_R^{\max}$ +$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, $K_D I_{\mathrm{fd}}$, and feedback-limiter paths +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after rectifier loading and optional speed multiplier ### External Variables @@ -130,53 +145,58 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +Smooth functions: [`clamp`](../../../../CommonMath.md#clamp), [$q$](../../../../CommonMath.md#quadratic-ramp). + +### Internal Equations + +#### Differential ```math \begin{aligned} 0 &= -T_R\dot V_C - V_C + E_C \\ 0 &= -T_A\dot x_A - x_A + K_A e_V \\ - 0 &= -T_B\dot x_{\mathrm{ll}} - x_{\mathrm{ll}} + V_A \\ - 0 &= -T_E\dot V_E + V_R - V_{\mathrm{fe}} \\ - 0 &= -T_H\dot V_F - V_F + V_{\mathrm{fe}} + 0 &= -T_B\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + V_A \\ + 0 &= -T_E\dot V_E + V_R - V_{\mathrm{FE}} \\ + 0 &= -T_H\dot V_F - V_F + V_{\mathrm{FE}} \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} 0 &= -e_V + V_{\mathrm{ref}} + V_{\mathrm{uel}} + V_S - V_C - V_F \\ 0 &= -V_A + \text{clamp}\!\left( - x_A + \dfrac{T_K}{T_A}(K_A e_V - x_A), + x_A + \dfrac{T_K}{T_A}(K_A e_V - x_A); V_A^{\min}, V_A^{\max} \right) \\ - 0 &= -T_B(V_{\mathrm{ll}} - x_{\mathrm{ll}}) + T_C(V_A - x_{\mathrm{ll}}) \\ + 0 &= -T_B(V_{\mathrm{LL}} - x_{\mathrm{LL}}) + T_C(V_A - x_{\mathrm{LL}}) \\ 0 &= -V_H^{\mathrm{pre}} + \begin{cases} V_F, & T_H = T_J = 0 \\ - V_F + \dfrac{T_J}{T_H}(V_{\mathrm{fe}} - V_F), & T_H > 0 + V_F + \dfrac{T_J}{T_H}(V_{\mathrm{FE}} - V_F), & T_H > 0 \end{cases} \\ - 0 &= -V_H + \text{clamp}\!\left(V_H^{\mathrm{pre}}, 0, V_H^{\max}\right) \\ - 0 &= -V_R + \text{clamp}(V_{\mathrm{ll}} - K_H V_H, V_R^{\min}, V_R^{\max}) \\ + 0 &= -V_H + \text{clamp}\!(V_H^{\mathrm{pre}}; 0, V_H^{\max}) \\ + 0 &= -V_R + \text{clamp}(V_{\mathrm{LL}} - K_H V_H; V_R^{\min}, V_R^{\max}) \\ 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}} + V_{\mathrm{fe}}^{\mathrm{lim}} \\ + 0 &= -V_{\mathrm{FE}} + + (K_E + S_E)V_E + K_D I_{\mathrm{fd}} + V_{\mathrm{FE}}^{\mathrm{lim}} \\ 0 &= -E_{\mathrm{fd}} - + \left(1+s_{\mathrm{spd}}\omega\right)F_{\mathrm{ex}}V_E + + (1+s_{\mathrm{spd}}\omega)F_{\mathrm{ex}}V_E \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. -When $T_B=T_C=0$, the second lead-lag block is bypassed. When $T_H=T_J=0$, the -feedback-limiter lead-lag block is bypassed before the 0-to-$V_H^{\max}$ clamp. +When $T_B=T_C=0$, the second lead–lag block is bypassed. When $T_H=T_J=0$, the +feedback-limiter lead–lag block is bypassed before the 0-to-$V_H^{\max}$ clamp. + +### External Equations + +None. ## Initialization @@ -186,10 +206,10 @@ 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} + 0 &= -V_E I_N + K_C I_{\mathrm{fd}} \\ + 0 &= -F_{\mathrm{ex}} + f(I_N) \\ + 0 &= -E_{\mathrm{fd}} + + (1+s_{\mathrm{spd}}\omega)F_{\mathrm{ex}}V_E \end{aligned} ``` @@ -197,39 +217,39 @@ 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_{\mathrm{fe}}^{\mathrm{lim}} \\ - V_{F,0} &= V_{\mathrm{fe},0} \\ - V_{H,0}^{\mathrm{pre}} &= V_{F,0} \\ - V_{H,0} &= \text{clamp}(V_{H,0}^{\mathrm{pre}}, 0, V_H^{\max}) \\ - V_{R,0} &= V_{\mathrm{fe},0} \\ - V_{\mathrm{ll},0} &= V_{R,0} + K_H V_{H,0} \\ - V_{A,0} &= V_{\mathrm{ll},0} \\ - x_{A,0} &= V_{A,0} \\ - x_{\mathrm{ll},0} &= V_{\mathrm{ll},0} \\ - V_{C,0} &= E_{C,0} \\ - e_{V,0} &= \dfrac{x_{A,0}}{K_A} \\ - V_{\mathrm{ref},0} &= e_{V,0} + V_{C,0} + V_{F,0} - V_{\mathrm{uel},0} - V_{S,0} + S_E &\leftarrow S_B\,q(V_E - S_A) \\ + V_{\mathrm{FE}} &\leftarrow (K_E + S_E)V_E + K_D I_{\mathrm{fd}} + V_{\mathrm{FE}}^{\mathrm{lim}} \\ + V_F &\leftarrow V_{\mathrm{FE}} \\ + V_H^{\mathrm{pre}} &\leftarrow V_F \\ + V_H &\leftarrow \text{clamp}(V_H^{\mathrm{pre}}; 0, V_H^{\max}) \\ + V_R &\leftarrow V_{\mathrm{FE}} \\ + V_{\mathrm{LL}} &\leftarrow V_R + K_H V_H \\ + V_A &\leftarrow V_{\mathrm{LL}} \\ + x_A &\leftarrow V_A \\ + x_{\mathrm{LL}} &\leftarrow V_{\mathrm{LL}} \\ + V_C &\leftarrow E_C \\ + e_V &\leftarrow \dfrac{x_A}{K_A} \\ + V_{\mathrm{ref}} &\leftarrow e_V + V_C + V_F - V_{\mathrm{uel}} - V_S \end{aligned} ``` -This standard start requires $1+s_{\mathrm{spd}}\omega_0\ne 0$, -$V_{E,0}\ne 0$, inactive $V_A$, $V_R$, and $V_H$ limits, and nonsingular +This standard start requires $1+s_{\mathrm{spd}}\omega\ne 0$, +$V_E\ne 0$, inactive $V_A$, $V_R$, and $V_H$ limits, and nonsingular regulator gains/time constants. Starts that bind those limits 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$ -`va` | [p.u.] | First regulator output | $V_A$ -`vll` | [p.u.] | Second lead-lag output | $V_{\mathrm{ll}}$ -`vf` | [p.u.] | Feedback-limiter state | $V_F$ -`vh` | [p.u.] | Feedback-limiter output | $V_H$ -`vr` | [p.u.] | Voltage-regulator output | $V_R$ -`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$ +## Monitors + +Monitor | 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$ +`va` | [p.u.] | First regulator output | $V_A$ +`vll` | [p.u.] | Second lead–lag output | $V_{\mathrm{LL}}$ +`vf` | [p.u.] | Feedback-limiter state | $V_F$ +`vh` | [p.u.] | Feedback-limiter output | $V_H$ +`vr` | [p.u.] | Voltage-regulator output | $V_R$ +`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$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md index ff7cae735..5d2241887 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md @@ -1,7 +1,7 @@ -# **IEEE DC1A Excitation System Model (ESDC1A)** +# ESDC1A ESDC1A is an IEEE DC1A excitation-system model with a voltage transducer, -input lead-lag compensation, a limited voltage regulator, exciter feedback and +input lead–lag compensation, a limited voltage regulator, exciter feedback and saturation, under-excitation limiter routing, and an optional speed multiplier. ## Notes @@ -9,7 +9,7 @@ saturation, under-excitation limiter routing, and an optional speed multiplier. - Internal voltage signals are on component base. - The source diagram labels the optional multiplier input as `Speed`; GridKit uses machine speed deviation, so the enabled multiplier is $1+\omega$. -- The UEL selector routes $V_{\mathrm{UEL}}$ either through the high-value gate +- The UEL selector routes $V_{\mathrm{uel}}$ either through the high-value gate or through the voltage-error summing junction. ## Block Diagram @@ -21,26 +21,26 @@ Figure 1: ESDC1A exciter model. Figure courtesy of the ## Model Parameters -Symbol | Units | JSON | Description | Typical Value -------------------------------------|-----------|-----------|-------------------------------------------------|-------------- -$T_R$ | [sec] | `Tr` | Voltage transducer time constant | 0.0 -$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 -$T_A$ | [sec] | `Ta` | Voltage-regulator time constant | 0.1 -$T_B$ | [sec] | `Tb` | Input lead-lag denominator time constant | 0.0 -$T_C$ | [sec] | `Tc` | Input lead-lag numerator time constant | 0.0 -$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 -$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 -$K_E$ | [p.u.] | `Ke` | Exciter field resistance line slope margin; 0 requests automatic calculation, not a zero coefficient | 0.1 -$T_E$ | [sec] | `Te` | Exciter time constant | 0.5 -$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 -$T_{F1}$ | [sec] | `Tf1` | Stabilizing feedback time constant | 0.7 -$s_{\mathrm{spd}}$ | [boolean] | `Spdmlt` | Field-voltage speed-multiplier flag | `false` -$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 -$S_E(E_1)$ | [p.u.] | `Se1` | Saturation coefficient at $E_1$ | 0.08 -$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 -$S_E(E_2)$ | [p.u.] | `Se2` | Saturation coefficient at $E_2$ | 0.33 -$I_{\mathrm{UEL}}$ | [integer] | `UEL` | Under-excitation limiter input-routing selector | 0 -$s_{\mathrm{lim}}$ | [boolean] | `exclim` | Exciter field-voltage-state lower-limit flag | `true` +Symbol | Units | JSON | Description | Typical Value | Note +-------------------|-----------|----------|------------------------------------------------------------------------------------------------------|---------------|----- +$T_R$ | [s] | `Tr` | Voltage transducer time constant | 0.0 | +$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | +$T_A$ | [s] | `Ta` | Voltage-regulator time constant | 0.1 | +$T_B$ | [s] | `Tb` | Input lead–lag denominator time constant | 0.0 | +$T_C$ | [s] | `Tc` | Input lead–lag numerator time constant | 0.0 | +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | +$K_E$ | [p.u.] | `Ke` | Exciter field resistance line slope margin; 0 requests automatic calculation, not a zero coefficient | 0.1 | +$T_E$ | [s] | `Te` | Exciter time constant | 0.5 | +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | +$T_{F1}$ | [s] | `Tf1` | Stabilizing feedback time constant | 0.7 | +$s_{\mathrm{spd}}$ | [boolean] | `Spdmlt` | Field-voltage speed-multiplier flag | `false` | +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `Se1` | Saturation coefficient at $E_1$ | 0.08 | +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `Se2` | Saturation coefficient at $E_2$ | 0.33 | +$I_{\mathrm{uel}}$ | [integer] | `UEL` | Under-excitation limiter input-routing selector | 0 | +$s_{\mathrm{lim}}$ | [boolean] | `exclim` | Exciter field-voltage-state lower-limit flag | `true` | Every parameter is optional. All real-valued parameters must be finite. `Spdmlt` and `exclim` must be @@ -48,7 +48,7 @@ JSON booleans, and `UEL` must be a JSON integer. ### Parameter Validation -Invalid ESDC1A parameter sets are rejected by the following checks: +A valid ESDC1A parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -58,9 +58,7 @@ Invalid ESDC1A parameter sets are rejected by the following checks: &\ge 0 \\ V_R^{\min} &\le V_R^{\max} \\ - s_{\mathrm{spd}}, s_{\mathrm{lim}} - &\in \{0,1\} \\ - I_{\mathrm{UEL}} + I_{\mathrm{uel}} &\in \{0,1,2,3\} \end{aligned} ``` @@ -77,7 +75,7 @@ or define a valid two-point scaled-quadratic fit: \begin{aligned} E_1, E_2 &> 0 \\ S_E(E_1), S_E(E_2) &\ge 0 \\ - \left(E_2-E_1\right) + (E_2-E_1) \left[S_E(E_2)-S_E(E_1)\right] &> 0 \end{aligned} ``` @@ -90,20 +88,20 @@ raised to that floor in place, so every equation below uses the raised value: ```math \begin{aligned} T_x - &\leftarrow \max\!\left(T_x,\epsilon_T\right), + &\leftarrow \max\!(T_x,\epsilon_T), \quad x\in\{R,A,B,E,F1\} \\ - s_{\mathrm{UEL}} + s_{\mathrm{uel}} &= \begin{cases} - 1 & I_{\mathrm{UEL}} \ge 2 \\ - 0 & I_{\mathrm{UEL}} < 2 + 1 & I_{\mathrm{uel}} \ge 2 \\ + 0 & I_{\mathrm{uel}} < 2 \end{cases} \end{aligned} ``` When saturation is disabled, $S_A = 0$ and $S_B = 0$. Otherwise, ```math -E S_E(E) = S_B q(E-S_A). +E S_E(E) = S_B q(E-S_A) ``` When one saturation value is zero, @@ -113,7 +111,7 @@ When one saturation value is zero, S_E(E_1)=0 &: \quad S_A=E_1,\qquad S_B=\dfrac{E_2S_E(E_2)}{(E_2-E_1)^2} \\ S_E(E_2)=0 &: \quad S_A=E_2,\qquad - S_B=\dfrac{E_1S_E(E_1)}{(E_1-E_2)^2}. + S_B=\dfrac{E_1S_E(E_1)}{(E_1-E_2)^2} \end{aligned} ``` @@ -144,22 +142,19 @@ units of $V_R^{\max}$: 0 &= V_R -K_E^{\mathrm{eff}}E_{\mathrm{fd}}' - -s_e, \\ + -s_e\\ K_E^{\mathrm{eff}} &= \begin{cases} \dfrac{1}{E_{\mathrm{fd}}'} \left(\dfrac{V_R^{\max}}{10}-s_e\right) - & K_E=0, \\ + & K_E=0\\ K_E - & K_E\ne 0. + & K_E\ne 0 \end{cases} \end{aligned} ``` -Thus $K_E^{\mathrm{eff}}$ is the resolved value of the same exciter -coefficient, not an additional model input. - ## Model Ports Name | Port | Init | Description @@ -171,9 +166,8 @@ Name | Port | Init | Description `vuel` | Input | Known | Under-excitation limiter input `efd` | Output | Known | Field-voltage output -`Known` ports hold their initial values before `initialize()` and are preserved -by it. `Unknown` inputs are resolved during initialization and written to -attached signal storage, or retained as constant inputs when unattached. The +`Known` values are seeded before initialization and preserved. `Unknown` inputs +are initialized in attached signal storage or held constant when unattached. The `efd` output must be assigned. The `speed` input is required when $s_{\mathrm{spd}} = 1$; every other signal input is optional. Unattached `speed`, `vs`, and `vuel` inputs default to zero. @@ -184,24 +178,24 @@ $s_{\mathrm{spd}} = 1$; every other signal input is optional. Unattached `speed` #### Differential -Symbol | Units | Description | Note -------------------------------------|--------|--------------------------------------------------|------ -$E_{\mathrm{fd}}'$ | [p.u.] | Exciter field-voltage state | State 1 in Fig. 1; lower bounded at zero when $s_{\mathrm{lim}} = 1$; before the optional speed multiplier -$V_C$ | [p.u.] | Filtered terminal-voltage magnitude | State 2 in Fig. 1 -$V_R$ | [p.u.] | Voltage-regulator output | State 3 in Fig. 1 -$V_F$ | [p.u.] | Stabilizing feedback state | State 4 in Fig. 1 -$x_{\mathrm{LL}}$ | [p.u.] | Input lead-lag denominator state | State 5 in Fig. 1 +Symbol | Units | Description | Note +-------------------|--------|-------------------------------------|----------------------------------------------------------------------------------------------------------- +$E_{\mathrm{fd}}'$ | [p.u.] | Exciter field-voltage state | State 1 in Fig. 1; lower bounded at zero when $s_{\mathrm{lim}} = 1$; before the optional speed multiplier +$V_C$ | [p.u.] | Filtered terminal-voltage magnitude | State 2 in Fig. 1 +$V_R$ | [p.u.] | Voltage-regulator output | State 3 in Fig. 1 +$V_F$ | [p.u.] | Stabilizing feedback state | State 4 in Fig. 1 +$x_{\mathrm{LL}}$ | [p.u.] | Input lead–lag denominator state | State 5 in Fig. 1 #### Algebraic -Symbol | Units | Description | Note -------------------------------------|--------|-----------------------------------|------ -$e_V$ | [p.u.] | Voltage-error summing output | -$V_{\mathrm{LL}}$ | [p.u.] | Input lead-lag output | -$V_{\mathrm{HV}}$ | [p.u.] | High-value gate output | -$s_e$ | [p.u.] | Scaled-quadratic saturation contribution | $E_{\mathrm{fd}}'S_E(E_{\mathrm{fd}}')$ -$V_{\mathrm{FE}}$ | [p.u.] | Exciter feedback drive | -$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Published through `efd` +Symbol | Units | Description | Note +------------------|--------|------------------------------------------|---------------------------------------- +$e_V$ | [p.u.] | Voltage-error summing output | +$V_{\mathrm{LL}}$ | [p.u.] | Input lead–lag output | +$V_{\mathrm{HV}}$ | [p.u.] | High-value gate output | +$s_e$ | [p.u.] | Scaled-quadratic saturation contribution | $E_{\mathrm{fd}}'S_E(E_{\mathrm{fd}}')$ +$V_{\mathrm{FE}}$ | [p.u.] | Exciter feedback drive | +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Published through `efd` ### External Variables @@ -211,67 +205,71 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note -------------------------------------|--------|---------|----------------------------------------|------ -$V_{\mathrm{r}}$ | [p.u.] | Known | Terminal voltage, real component | Bus input -$V_{\mathrm{i}}$ | [p.u.] | Known | Terminal voltage, imaginary component | Bus input -$\omega$ | [p.u.] | Known | Machine speed deviation | Signal port `speed` -$V_{\mathrm{ref}}$ | [p.u.] | Unknown | Voltage-control reference | Signal port `vref` -$V_S$ | [p.u.] | Known | Stabilizer input signal | Signal port `vs` -$V_{\mathrm{UEL}}$ | [p.u.] | Known | Under-excitation limiter input | Signal port `vuel` +Symbol | Units | Description | Note +-------------------|--------|---------------------------------------|-------------------- +$V_r$ | [p.u.] | Terminal voltage, real component | Bus input +$V_i$ | [p.u.] | Terminal voltage, imaginary component | Bus input +$\omega$ | [p.u.] | Machine speed deviation | Signal port `speed` +$V_{\mathrm{ref}}$ | [p.u.] | Voltage-control reference | Signal port `vref` +$V_S$ | [p.u.] | Stabilizer input signal | Signal port `vs` +$V_{\mathrm{uel}}$ | [p.u.] | Under-excitation limiter input | Signal port `vuel` ## Model Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`max`](../../../../CommonMath.md#maximum), [$q$](../../../../CommonMath.md#quadratic-ramp), [$\rho$](../../../../CommonMath.md#ramp). + +### Internal Equations + +#### Differential + Define the pre-limit exciter field-voltage rate: ```math -f_E = \dfrac{V_R-V_{\mathrm{FE}}}{T_E}. +f_E = \dfrac{V_R-V_{\mathrm{FE}}}{T_E} ``` -### Differential Equations - ```math \begin{aligned} 0 &= -\dot{E}_{\mathrm{fd}}' - + \left(1-s_{\mathrm{lim}}\right)f_E + + (1-s_{\mathrm{lim}})f_E + s_{\mathrm{lim}}\, - \text{awmin}\left(E_{\mathrm{fd}}',f_E;0\right) \\ + \text{awmin}(E_{\mathrm{fd}}',f_E;0) \\ 0 &= -\dot{V}_C + \dfrac{1}{T_R} \left( - \sqrt{V_{\mathrm{r}}^2+V_{\mathrm{i}}^2} + \sqrt{V_r^2+V_i^2} - V_C \right) \\ 0 &= -\dot{V}_R + \dfrac{1}{T_A} \text{antiwindup} - \left( - V_R,\, + ( + V_R,\; -V_R + K_A V_{\mathrm{HV}};\, V_R^{\min}, V_R^{\max} - \right) \\ + ) \\ 0 &= -\dot{V}_F + \dfrac{1}{T_{F1}} \left[ -V_F + \dfrac{K_F}{T_E} - \left(V_R - V_{\mathrm{FE}}\right) + (V_R - V_{\mathrm{FE}}) \right] \\ 0 &= -\dot{x}_{\mathrm{LL}} + \dfrac{1}{T_B} - \left(e_V - x_{\mathrm{LL}}\right) + (e_V - x_{\mathrm{LL}}) \end{aligned} ``` The field-voltage-state limiter uses the fixed-lower-bound anti-windup rule of [Appendix A](#appendix-a-awmin). -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -279,38 +277,38 @@ of [Appendix A](#appendix-a-awmin). -e_V + V_{\mathrm{ref}} + V_S - + s_{\mathrm{UEL}}V_{\mathrm{UEL}} + + s_{\mathrm{uel}}V_{\mathrm{uel}} - V_C - V_F \\ 0 &= -V_{\mathrm{LL}} + x_{\mathrm{LL}} + \dfrac{T_C}{T_B} - \left(e_V - x_{\mathrm{LL}}\right) \\ + (e_V - x_{\mathrm{LL}}) \\ 0 &= -V_{\mathrm{HV}} + \begin{cases} - \text{max}\left(V_{\mathrm{LL}}, V_{\mathrm{UEL}}\right) - & s_{\mathrm{UEL}} = 0 \\ + \text{max}(V_{\mathrm{LL}}, V_{\mathrm{uel}}) + & s_{\mathrm{uel}} = 0 \\ V_{\mathrm{LL}} - & s_{\mathrm{UEL}} = 1 + & s_{\mathrm{uel}} = 1 \end{cases} \\ 0 &= -s_e - + S_B q\left(E_{\mathrm{fd}}' - S_A\right) \\ + + S_B q(E_{\mathrm{fd}}' - S_A) \\ 0 &= -V_{\mathrm{FE}} + K_E^{\mathrm{eff}} E_{\mathrm{fd}}' + s_e \\ 0 &= -E_{\mathrm{fd}} - + \left(1 + s_{\mathrm{spd}}\omega\right)E_{\mathrm{fd}}' + + (1 + s_{\mathrm{spd}}\omega)E_{\mathrm{fd}}' \end{aligned} ``` -CommonMath defines helper targets and smooth approximations for -[max](../../../../CommonMath.md#derived-functions), the [ramp](../../../../CommonMath.md#primitives) -$\rho$, and the [quadratic ramp](../../../../CommonMath.md#primitives) $q$. +### External Equations + +None. ## Initialization @@ -318,7 +316,7 @@ $\rho$, and the [quadratic ramp](../../../../CommonMath.md#primitives) $q$. ```math \begin{aligned} - V_{\mathrm{r}}, V_{\mathrm{i}} + V_r, V_i &\leftarrow \text{terminal-bus voltage} \\ E_{\mathrm{fd}} &\leftarrow \text{machine field voltage} \\ @@ -326,7 +324,7 @@ $\rho$, and the [quadratic ramp](../../../../CommonMath.md#primitives) $q$. &\leftarrow \text{machine speed deviation or }0 \\ V_S &\leftarrow \text{stabilizer signal or }0 \\ - V_{\mathrm{UEL}} + V_{\mathrm{uel}} &\leftarrow \text{under-excitation limiter input or }0 \end{aligned} ``` @@ -335,21 +333,18 @@ Initialization never replaces the seeded value held in $E_{\mathrm{fd}}$. ### Internal Initialization -All internal derivatives are set to zero. The steady-state residuals are then -resolved in dependency order. The smooth high-value gate requires its input to -be recovered through the inverse CommonMath -[ramp](../../../../CommonMath.md#primitives) $\rho^{-1}$ when the UEL input is -routed through the gate: +All internal derivatives initialize to zero. The UEL high-value gate uses the +inverse smooth [ramp](../../../../CommonMath.md#ramp) $\rho^{-1}$: ```math \begin{aligned} V_C - &\leftarrow \sqrt{V_{\mathrm{r}}^2+V_{\mathrm{i}}^2} \\ + &\leftarrow \sqrt{V_r^2+V_i^2} \\ E_{\mathrm{fd}}' &\leftarrow \dfrac{E_{\mathrm{fd}}}{1 + s_{\mathrm{spd}}\omega} \\ s_e - &\leftarrow S_B q\left(E_{\mathrm{fd}}' - S_A\right) \\ + &\leftarrow S_B q(E_{\mathrm{fd}}' - S_A) \\ V_{\mathrm{FE}} &\leftarrow K_E^{\mathrm{eff}} E_{\mathrm{fd}}' + s_e \\ V_R @@ -359,12 +354,12 @@ routed through the gate: V_{\mathrm{LL}} &\leftarrow \begin{cases} - V_{\mathrm{UEL}} + V_{\mathrm{uel}} + \rho^{-1} - \left(V_{\mathrm{HV}}-V_{\mathrm{UEL}}\right) - & s_{\mathrm{UEL}} = 0 \\ + (V_{\mathrm{HV}}-V_{\mathrm{uel}}) + & s_{\mathrm{uel}} = 0 \\ V_{\mathrm{HV}} - & s_{\mathrm{UEL}} = 1 + & s_{\mathrm{uel}} = 1 \end{cases} \\ V_F &\leftarrow 0 \\ @@ -380,11 +375,10 @@ non-finite field-voltage seed, non-finite Known signal inputs, a nonpositive speed multiplier $1 + s_{\mathrm{spd}}\omega$, $E_{\mathrm{fd}}'<0$ while $s_{\mathrm{lim}}=1$, initial $V_R$ outside $[V_R^{\min},V_R^{\max}]$, and high-value-gate active -starts with $s_{\mathrm{UEL}} = 0$ and -$V_{\mathrm{HV}}\le V_{\mathrm{UEL}}$. +starts with $s_{\mathrm{uel}} = 0$ and +$V_{\mathrm{HV}}\le V_{\mathrm{uel}}$. -Every check resolves before any storage is written, so a rejected -initialization leaves state, the `efd` seed, and external signals unchanged. +A rejected initialization leaves states and signals unchanged. ### Output Initialization @@ -396,7 +390,7 @@ initialization leaves state, the `efd` seed, and external signals unchanged. + V_C + V_F - V_S - - s_{\mathrm{UEL}}V_{\mathrm{UEL}} + - s_{\mathrm{uel}}V_{\mathrm{uel}} \end{aligned} ``` @@ -404,9 +398,9 @@ ESDC1A writes the resolved voltage-control reference to an attached `vref` signal input. If no controller is connected, that value is used as a constant reference input. -## Monitorable Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `vc` | [p.u.] | Filtered terminal-voltage magnitude | $V_C$ @@ -415,25 +409,6 @@ Output | Units | Description | Note `se` | [p.u.] | Scaled-quadratic saturation contribution | $s_e$ `vfe` | [p.u.] | Exciter feedback drive | $V_{\mathrm{FE}}$ -## Testing - -- `validation()` checks construction, documented defaults, parameter types - and domains, signal configuration, and minimum time-constant handling. -- `initializationAndSignals()` checks steady initialization, selector - combinations, signal publication and latching, monitor output, and - differentiability tags. -- `initializationDomain()` checks rejected and accepted field-voltage, - terminal-voltage, Known-input, speed-multiplier, regulator-limit, and - high-value-gate operating points. -- `residualEquations()` checks every model residual against a fixed - numerical answer key. -- `voltageRegulation()` checks the transducer, summing junction, lead-lag, - stabilizing feedback, and regulator anti-windup behavior. -- `excitationLimits()` checks high-value-gate routing, saturation, - field-voltage-state limiting, and the optional speed multiplier. -- `jacobian()` compares the dependency-tracking and Enzyme Jacobians when - Enzyme support is enabled. - ## Appendix A: `awmin` The exact anti-windup rule at a fixed lower bound $\ell$ is @@ -446,9 +421,6 @@ The exact anti-windup rule at a fixed lower bound $\ell$ is \end{cases} ``` -Above the bound the unconstrained derivative passes. At or below the bound, -outward motion is blocked and restoring motion is admitted. - The model evaluates this rule with the following smooth approximation: ```math @@ -456,10 +428,10 @@ The model evaluates this rule with the following smooth approximation: \approx \left[ \sigma(f) - + \left(1-\sigma(f)\right)\text{above}(x;\ell) - \right]f. + + (1-\sigma(f))\text{above}(x;\ell) + \right]f ``` -CommonMath defines the [`above`](../../../../CommonMath.md#derived-functions) -and [`sigmoid`](../../../../CommonMath.md#primitives) targets and smooth +CommonMath defines the [`above`](../../../../CommonMath.md#above) +and [`sigmoid`](../../../../CommonMath.md#logistic-function) targets and smooth approximations. diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md index da01f2157..f0c018495 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md @@ -1,10 +1,15 @@ -# **IEEE Type DC2A Excitation System Model (ESDC2A)** +# ESDC2A -ESDC2A is an IEEE Type DC excitation system with a voltage transducer, lead-lag +ESDC2A is an IEEE Type DC excitation system with a voltage transducer, lead–lag input compensation, high-value under-excitation limiter selection, limited voltage regulator, exciter feedback, saturation, and optional speed multiplier. -Notes: +> [!WARNING] +> Initialization does not yet invert the smooth gates and limits used by the +> model equations. + +## Notes + - Internal voltage signals are on model base unless otherwise stated. - The diagram labels the optional multiplier input as `Speed`; GridKit uses machine speed deviation, so the enabled multiplier is $1+\omega$. @@ -15,39 +20,36 @@ Notes: ## Block Diagram -Standard model of the ESDC2A Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/ESDC2A_diagram.png) Figure 1: Exciter ESDC2A model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -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 -$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` -$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`; must be zero when $T_B=0$ -$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` -$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` -$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | Block name: `Kf` -$T_{F1}$ | [sec] | `Tf1` | Feedback lead time constant | 0.7 | Block name: `Tf1` -$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | Block name: `Spdmlt`; 1 enables the speed multiplier -$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` -$I_{\mathrm{uel}}$ | [integer] | `UEL` | Under-excitation limiter input-location selector | 0 | Block name: `UEL`; 0/1 = HV gate input, 2/3 = input-error summing junction -$s_{\mathrm{lim}}$ | [binary] | `exclim` | Exciter feedback lower-limit flag | 1 | Block name: `exclim`; nonzero enables the zero lower limit on $V_{\mathrm{fe}}$ +Symbol | Units | JSON | Description | Typical Value | Note +-------------------|-----------|----------|---------------------------------------------------------|---------------|---------------------------------------------------------- +$T_R$ | [s] | `Tr` | Transducer time constant | 0.0 | if zero, $V_C$ is algebraic +$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | +$T_A$ | [s] | `Ta` | Voltage-regulator time constant | 0.1 | +$T_B$ | [s] | `Tb` | Lag time constant for voltage-regulator input lead–lag | 0.0 | if $T_B=T_C=0$, the lead–lag block is bypassed +$T_C$ | [s] | `Tc` | Lead time constant for voltage-regulator input lead–lag | 0.0 | must be zero when $T_B=0$ +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | +$T_E$ | [s] | `Te` | Exciter time constant | 0.5 | +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | +$T_{F1}$ | [s] | `Tf1` | Feedback lead time constant | 0.7 | +$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | 1 enables the speed multiplier +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Source label: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Source label: `Se2` +$I_{\mathrm{uel}}$ | [integer] | `UEL` | Under-excitation limiter input-location selector | 0 | 0/1 = HV gate input, 2/3 = input-error summing junction +$s_{\mathrm{lim}}$ | [binary] | `exclim` | Exciter feedback lower-limit flag | 1 | nonzero enables the zero lower limit on $V_{\mathrm{FE}}$ ### Parameter Validation -Invalid ESDC2A parameter sets are rejected by the following checks. Source data -may apply PowerWorld-style autocorrections before these equations are evaluated. +A valid ESDC2A parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -104,30 +106,41 @@ saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +--------|--------|------|------------ +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`speed` | Input | TBD | Machine speed deviation $\omega$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$E_{\mathrm{fd}}'$ | [p.u.] | Field-voltage state before optional speed multiplier | State 1 in Fig. 1; source label: `EFD` -$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` -$V_F$ | [p.u.] | Stabilizing feedback washout output | State 4 in Fig. 1; source label: `VF`; algebraic when $T_{F1}=0$ -$x_{\mathrm{ll}}$ | [p.u.] | Lead-lag block state | State 5 in Fig. 1; source label: `Lead-Lag` +Symbol | Units | Description | Note +-------------------|--------|------------------------------------------------------|--------------------------------------------------------------------- +$E_{\mathrm{fd}}'$ | [p.u.] | Field-voltage state before optional speed multiplier | State 1 in Fig. 1; Source label: `EFD` +$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` +$V_F$ | [p.u.] | Stabilizing feedback washout output | State 4 in Fig. 1; Source label: `VF`; algebraic when $T_{F1}=0$ +$x_{\mathrm{LL}}$ | [p.u.] | Lead–lag block state | State 5 in Fig. 1; Source label: `Lead-Lag` #### Algebraic -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$e_V$ | [p.u.] | Voltage-regulator input error before lead-lag block | Includes selected $V_{\mathrm{uel}}$ summing-junction input -$V_{\mathrm{ll}}$ | [p.u.] | Lead-lag block output | Input to high-value gate -$V_{\mathrm{hv}}$ | [p.u.] | High-value gate output | Selects $V_{\mathrm{ll}}$ or alternate $V_{\mathrm{uel}}$ -$S_E$ | [p.u.] | Saturation coefficient evaluated at $E_{\mathrm{fd}}'$ | Uses derived saturation curve -$V_{\mathrm{fe}}$ | [p.u.] | Exciter feedback signal after optional lower limit | Lower limited at zero when $s_{\mathrm{lim}}=1$ -$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after optional speed multiplier +Symbol | Units | Description | Note +------------------|--------|--------------------------------------------------------|------------------------------------------------------------ +$e_V$ | [p.u.] | Voltage-regulator input error before lead–lag block | Includes selected $V_{\mathrm{uel}}$ summing-junction input +$V_{\mathrm{LL}}$ | [p.u.] | Lead–lag block output | Input to high-value gate +$V_{\mathrm{HV}}$ | [p.u.] | High-value gate output | Selects $V_{\mathrm{LL}}$ or alternate $V_{\mathrm{uel}}$ +$S_E$ | [p.u.] | Saturation coefficient evaluated at $E_{\mathrm{fd}}'$ | Uses derived saturation curve +$V_{\mathrm{FE}}$ | [p.u.] | Exciter feedback signal after optional lower limit | Lower limited at zero when $s_{\mathrm{lim}}=1$ +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after optional speed multiplier ### External Variables @@ -147,48 +160,50 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`max`](../../../../CommonMath.md#maximum), [$q$](../../../../CommonMath.md#quadratic-ramp), [$\rho$](../../../../CommonMath.md#ramp). + +### Internal Equations + +#### Differential ```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_B\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + e_V \\ 0 &= -T_A\dot V_R - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_R, - -V_R + K_A V_{\mathrm{hv}}, + -V_R + K_A V_{\mathrm{HV}}; V_R^{\min}, V_R^{\max} - \right) \\ - 0 &= -T_E\dot E_{\mathrm{fd}}' + V_R - V_{\mathrm{fe}} \\ - 0 &= -T_E T_{F1}\dot V_F - T_E V_F + K_F(V_R - V_{\mathrm{fe}}) + ) \\ + 0 &= -T_E\dot E_{\mathrm{fd}}' + V_R - V_{\mathrm{FE}} \\ + 0 &= -T_E T_{F1}\dot V_F - T_E V_F + K_F(V_R - V_{\mathrm{FE}}) \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} 0 &= -e_V + V_{\mathrm{ref}} + V_S + s_{\mathrm{uel}}V_{\mathrm{uel}} - V_C - V_F \\ - 0 &= -T_B(V_{\mathrm{ll}} - x_{\mathrm{ll}}) + T_C(e_V - x_{\mathrm{ll}}) \\ - 0 &= -V_{\mathrm{hv}} - + s_{\mathrm{uel}}V_{\mathrm{ll}} - + s_{\mathrm{uel}}^{\mathrm{off}}\text{max}(V_{\mathrm{ll}}, V_{\mathrm{uel}}) \\ + 0 &= -T_B(V_{\mathrm{LL}} - x_{\mathrm{LL}}) + T_C(e_V - x_{\mathrm{LL}}) \\ + 0 &= -V_{\mathrm{HV}} + + s_{\mathrm{uel}}V_{\mathrm{LL}} + + s_{\mathrm{uel}}^{\mathrm{off}}\text{max}(V_{\mathrm{LL}}, V_{\mathrm{uel}}) \\ 0 &= -S_E + S_B\,q(E_{\mathrm{fd}}' - S_A) \\ - 0 &= -V_{\mathrm{fe}} + 0 &= -V_{\mathrm{FE}} + s_{\mathrm{lim}}^{\mathrm{off}}(K_E + S_E)E_{\mathrm{fd}}' - + s_{\mathrm{lim}}\rho\!\left((K_E + S_E)E_{\mathrm{fd}}'\right) \\ - 0 &= -E_{\mathrm{fd}} + \left(1 + s_{\mathrm{spd}}\omega\right)E_{\mathrm{fd}}' + + s_{\mathrm{lim}}\rho\!((K_E + S_E)E_{\mathrm{fd}}') \\ + 0 &= -E_{\mathrm{fd}} + (1 + s_{\mathrm{spd}}\omega)E_{\mathrm{fd}}' \end{aligned} ``` -CommonMath defines the helper targets and smooth approximations for -[max](../../../../CommonMath.md#derived-functions) and the primitives -[ramp and quadratic ramp](../../../../CommonMath.md#primitives) $\rho$ and $q$. -When $T_B=T_C=0$, the lead-lag block is bypassed so $V_{\mathrm{ll}}=e_V$. +When $T_B=T_C=0$, the lead–lag block is bypassed so $V_{\mathrm{LL}}=e_V$. + +### External Equations + +None. ## Initialization @@ -198,33 +213,35 @@ $V_{\mathrm{uel}}$, sets all internal derivatives to zero, and evaluates: ```math \begin{aligned} - E_{\mathrm{fd},0}' &= \dfrac{E_{\mathrm{fd},0}}{1 + s_{\mathrm{spd}}\omega_0} \\ - S_{E,0} &= S_B\,q(E_{\mathrm{fd},0}' - S_A) \\ - V_{\mathrm{fe},0} - &= s_{\mathrm{lim}}^{\mathrm{off}}(K_E + S_{E,0})E_{\mathrm{fd},0}' - + s_{\mathrm{lim}}\rho\!\left((K_E + S_{E,0})E_{\mathrm{fd},0}'\right) \\ - V_{R,0} &= V_{\mathrm{fe},0} \\ - V_{\mathrm{hv},0} &= \dfrac{V_{R,0}}{K_A} \\ - V_{C,0} &= E_{C,0} \\ - V_{F,0} &= 0 \\ - x_{\mathrm{ll},0} &= V_{\mathrm{ll},0} = e_{V,0} = V_{\mathrm{hv},0} \\ - V_{\mathrm{ref},0} - &= e_{V,0} + V_{C,0} + V_{F,0} - V_{S,0} - s_{\mathrm{uel}}V_{\mathrm{uel},0} + E_{\mathrm{fd}}' &\leftarrow \dfrac{E_{\mathrm{fd}}}{1 + s_{\mathrm{spd}}\omega} \\ + S_E &\leftarrow S_B\,q(E_{\mathrm{fd}}' - S_A) \\ + V_{\mathrm{FE}} + &\leftarrow s_{\mathrm{lim}}^{\mathrm{off}}(K_E + S_E)E_{\mathrm{fd}}' + + s_{\mathrm{lim}}\rho\!((K_E + S_E)E_{\mathrm{fd}}') \\ + V_R &\leftarrow V_{\mathrm{FE}} \\ + V_{\mathrm{HV}} &\leftarrow \dfrac{V_R}{K_A} \\ + V_C &\leftarrow E_C \\ + V_F &\leftarrow 0 \\ + V_{\mathrm{LL}} &\leftarrow V_{\mathrm{HV}} \\ + e_V &\leftarrow V_{\mathrm{LL}} \\ + x_{\mathrm{LL}} &\leftarrow e_V \\ + V_{\mathrm{ref}} + &\leftarrow e_V + V_C + V_F - V_S - s_{\mathrm{uel}}V_{\mathrm{uel}} \end{aligned} ``` -This closed-form start requires $1 + s_{\mathrm{spd}}\omega_0 \ne 0$, -$V_R^{\min} \le V_{R,0} \le V_R^{\max}$, and, when $s_{\mathrm{uel}}=0$, -$V_{\mathrm{hv},0} \ge V_{\mathrm{uel},0}$. Saturated voltage-regulator starts +This closed-form start requires $1 + s_{\mathrm{spd}}\omega \ne 0$, +$V_R^{\min} \le V_R \le V_R^{\max}$, and, when $s_{\mathrm{uel}}=0$, +$V_{\mathrm{HV}} \ge V_{\mathrm{uel}}$. Saturated voltage-regulator starts and active high-value-gate starts are outside these closed-form equations. -## Model Outputs +## Monitors -Output | Units | Description | Note -----------------|--------|-------------------------------------|------ -`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ -`vc` | [p.u.] | Sensed compensated voltage | $V_C$ -`vr` | [p.u.] | Voltage-regulator output | $V_R$ -`vf` | [p.u.] | Stabilizing feedback state | $V_F$ -`se` | [p.u.] | Saturation coefficient | $S_E$ -`vfe` | [p.u.] | Exciter feedback signal | $V_{\mathrm{fe}}$ +Monitor | Units | Description | Note +--------|--------|----------------------------|------------------ +`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ +`vc` | [p.u.] | Sensed compensated voltage | $V_C$ +`vr` | [p.u.] | Voltage-regulator output | $V_R$ +`vf` | [p.u.] | Stabilizing feedback state | $V_F$ +`se` | [p.u.] | Saturation coefficient | $S_E$ +`vfe` | [p.u.] | Exciter feedback signal | $V_{\mathrm{FE}}$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md index 27ae8e018..c63af9969 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md @@ -1,4 +1,4 @@ -# **IEEE Type ST4B Potential- or Compound-Source Controlled-Rectifier Exciter Model (ESST4B)** +# ESST4B ESST4B is a static excitation system with compensated-voltage sensing, an outer proportional/integral voltage regulator, a lag block, an inner @@ -6,48 +6,48 @@ proportional/integral regulator with exciter-output feedback, low-value over-excitation limiter gating, and potential- or compound-source rectifier scaling. -Notes: +> [!WARNING] +> Initialization does not yet invert the smooth gates and limits used by the +> model equations. + +## 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 controlled-rectifier loading curve from Fig. 1; it is not a CommonMath helper. -- The potential-source calculation uses explicit real and imaginary terminal - voltage/current components; the diagram's complex expression is not used as - model-equation notation below. ## Block Diagram -Standard model of the ESST4B Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/ESST4B_diagram.png) Figure 1: Exciter ESST4B model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note -------------------------------------|--------|-------------|---------------------------------------------------------|---------------|------ -$T_R$ | [sec] | `Tr` | Compensated-voltage transducer time constant | 0.0 | Block name: `Tr`; if zero, sensed voltage is algebraic -$K_{\mathrm{pr}}$ | [p.u.] | `Kpr` | Outer regulator proportional gain | 1.0 | Block name: `KPR` -$K_{\mathrm{ir}}$ | [p.u./s] | `Kir` | Outer regulator integral gain | 0.0 | Block name: `KIR` -$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum outer regulator output | 1.0 | Block name: `VRMAX` -$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum outer regulator output | -1.0 | Block name: `VRMIN` -$T_A$ | [sec] | `Ta` | Regulator lag time constant | 0.0 | Block name: `Ta`; if zero, $V_A$ is algebraic -$K_{\mathrm{pm}}$ | [p.u.] | `Kpm` | Inner regulator proportional gain | 1.0 | Block name: `KPM` -$K_{\mathrm{im}}$ | [p.u./s] | `Kim` | Inner regulator integral gain | 0.0 | Block name: `KIM` -$V_M^{\max}$ | [p.u.] | `VmMax` | Maximum inner regulator output | 1.0 | Block name: `VMMAX` -$V_M^{\min}$ | [p.u.] | `VmMin` | Minimum inner regulator output | 0.0 | Block name: `VMMIN` -$K_G$ | [p.u.] | `Kg` | Exciter-output feedback gain into inner regulator | 0.0 | Block name: `KG` -$K_P$ | [p.u.] | `Kp` | Potential-source voltage coefficient magnitude | 0.0 | Source label: `KP` -$K_I$ | [p.u.] | `Ki` | Potential-source current coefficient | 0.0 | Source label: `KI` -$V_B^{\max}$ | [p.u.] | `VbMax` | Maximum rectifier source multiplier | 999.0 | Block name: `VBMAX` -$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | Block name: `Kc`; forms $I_N$ -$X_L$ | [p.u.] | `Xl` | Source reactance term in potential-source calculation | 0.0 | Source label: `XL` -$\theta_P$ | [deg] | `ThetaPDeg` | Potential-source coefficient angle | 0.0 | Source label: `thetaP`; forms $K_P^{\mathrm{r}}$ and $K_P^{\mathrm{i}}$ -$V_G^{\max}$ | [p.u.] | `VgMax` | Maximum exciter-output feedback signal | 999.0 | Block name: `VGMAX`; ceiling on $K_G E_{\mathrm{fd}}$ +Symbol | Units | JSON | Description | Typical Value | Note +------------------|----------|-------------|-------------------------------------------------------|---------------|------------------------------------------------------------------------ +$T_R$ | [s] | `Tr` | Compensated-voltage transducer time constant | 0.0 | if zero, sensed voltage is algebraic +$K_{\mathrm{pr}}$ | [p.u.] | `Kpr` | Outer regulator proportional gain | 1.0 | Source label: `KPR` +$K_{\mathrm{ir}}$ | [p.u./s] | `Kir` | Outer regulator integral gain | 0.0 | Source label: `KIR` +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum outer regulator output | 1.0 | Source label: `VRMAX` +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum outer regulator output | -1.0 | Source label: `VRMIN` +$T_A$ | [s] | `Ta` | Regulator lag time constant | 0.0 | if zero, $V_A$ is algebraic +$K_{\mathrm{pm}}$ | [p.u.] | `Kpm` | Inner regulator proportional gain | 1.0 | Source label: `KPM` +$K_{\mathrm{im}}$ | [p.u./s] | `Kim` | Inner regulator integral gain | 0.0 | Source label: `KIM` +$V_M^{\max}$ | [p.u.] | `VmMax` | Maximum inner regulator output | 1.0 | Source label: `VMMAX` +$V_M^{\min}$ | [p.u.] | `VmMin` | Minimum inner regulator output | 0.0 | Source label: `VMMIN` +$K_G$ | [p.u.] | `Kg` | Exciter-output feedback gain into inner regulator | 0.0 | Source label: `KG` +$K_P$ | [p.u.] | `Kp` | Potential-source voltage coefficient magnitude | 0.0 | Source label: `KP` +$K_I$ | [p.u.] | `Ki` | Potential-source current coefficient | 0.0 | Source label: `KI` +$V_B^{\max}$ | [p.u.] | `VbMax` | Maximum rectifier source multiplier | 999.0 | Source label: `VBMAX` +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | forms $I_N$ +$X_L$ | [p.u.] | `Xl` | Source reactance term in potential-source calculation | 0.0 | Source label: `XL` +$\theta_P$ | [deg] | `ThetaPDeg` | Potential-source coefficient angle | 0.0 | Source label: `thetaP`; forms $K_P^r$ and $K_P^i$ +$V_G^{\max}$ | [p.u.] | `VgMax` | Maximum exciter-output feedback signal | 999.0 | Source label: `VGMAX`; ceiling on $K_G E_{\mathrm{fd}}$ ### Parameter Validation -Invalid ESST4B parameter sets are rejected by the following checks. +A valid ESST4B parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -63,26 +63,42 @@ The potential-source coefficient is resolved into real scalar components: ```math \begin{aligned} - K_P^{\mathrm{r}} &= K_P\cos\theta_P \\ - K_P^{\mathrm{i}} &= K_P\sin\theta_P + K_P^r &= K_P\cos\theta_P \\ + K_P^i &= K_P\sin\theta_P \end{aligned} ``` Here $\theta_P$ is converted from degrees before evaluating the trigonometric functions. +## Model Ports + +Name | Port | Init | Description +--------|--------|------|-------------------------------------------------- +`vcomp` | Input | TBD | Compensated voltage input $V_{\mathrm{comp}}$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`voel` | Input | TBD | Over-excitation limiter input $V_{\mathrm{oel}}$ +`vr` | Input | TBD | Terminal-voltage real component $V_r$ +`vi` | Input | TBD | Terminal-voltage imaginary component $V_i$ +`ir` | Input | TBD | Terminal-current real component $I_r$ +`ii` | Input | TBD | Terminal-current imaginary component $I_i$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$V_M$ | [p.u.] | Inner regulator output | State 1 in Fig. 1 -$V_C$ | [p.u.] | Sensed compensated voltage | State 2 in Fig. 1; source label: `Sensed Vt`; algebraic when $T_R=0$ -$V_A$ | [p.u.] | Lagged outer-regulator output | State 3 in Fig. 1; algebraic when $T_A=0$ -$x_R$ | [p.u.] | Outer regulator integral state | State 4 in Fig. 1; source label: `VR` +Symbol | Units | Description | Note +-------|--------|--------------------------------|--------------------------------------------------------------------- +$V_M$ | [p.u.] | Inner regulator output | State 1 in Fig. 1 +$V_C$ | [p.u.] | Sensed compensated voltage | State 2 in Fig. 1; Source label: `Sensed Vt`; algebraic when $T_R=0$ +$V_A$ | [p.u.] | Lagged outer-regulator output | State 3 in Fig. 1; algebraic when $T_A=0$ +$x_R$ | [p.u.] | Outer regulator integral state | State 4 in Fig. 1; Source label: `VR` #### Algebraic @@ -93,8 +109,8 @@ $V_R$ | [p.u.] | Limited outer regulator output $V_G$ | [p.u.] | Limited exciter-output feedback signal | $K_G E_{\mathrm{fd}}$ limited by $V_G^{\max}$ $e_M$ | [p.u.] | Inner regulator error | $V_A$ minus $V_G$ $V_{\mathrm{lv}}$ | [p.u.] | Low-value gate output | Lesser of $V_M$ and $V_{\mathrm{oel}}$ -$V_{\mathrm{src}}^{\mathrm{r}}$ | [p.u.] | Real component of the potential-source expression | From terminal voltage/current components -$V_{\mathrm{src}}^{\mathrm{i}}$ | [p.u.] | Imaginary component of the potential-source expression | From terminal voltage/current components +$V_{\mathrm{src}}^r$ | [p.u.] | Real component of the potential-source expression | From terminal voltage/current components +$V_{\mathrm{src}}^i$ | [p.u.] | Imaginary component of the potential-source expression | From terminal voltage/current components $V_E$ | [p.u.] | Potential- or compound-source voltage magnitude | Nonnegative source magnitude $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)$ @@ -109,69 +125,70 @@ None. #### Algebraic -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$V_{\mathrm{comp}}$ | [p.u.] | Compensated voltage input | Source label: `VCOMP` -$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 a high value when omitted -$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` +Symbol | Units | Description | Note +--------------------|--------|--------------------------------------|---------------------------------------------------------------------- +$V_{\mathrm{comp}}$ | [p.u.] | Compensated voltage input | Source label: `VCOMP` +$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 a high value when omitted +$V_r$ | [p.u.] | Terminal-voltage real component | Source label: `VT` +$V_i$ | [p.u.] | Terminal-voltage imaginary component | Source label: `VT` +$I_r$ | [p.u.] | Terminal-current real component | Source label: `IT` +$I_i$ | [p.u.] | Terminal-current imaginary component | Source label: `IT` +$I_{\mathrm{fd}}$ | [p.u.] | Machine field current | Source label: `IFD` ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`min`](../../../../CommonMath.md#minimum). + +### Internal Equations + +#### Differential ```math \begin{aligned} 0 &= -T_R\dot V_C - V_C + V_{\mathrm{comp}} \\ 0 &= -\dot x_R - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_R, - K_{\mathrm{ir}}e_V, + K_{\mathrm{ir}}e_V; V_R^{\min}, V_R^{\max} - \right) \\ + ) \\ 0 &= -T_A\dot V_A - V_A + V_R \\ 0 &= -\dot V_M - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_M, - K_{\mathrm{im}}e_M, + K_{\mathrm{im}}e_M; V_M^{\min}, V_M^{\max} - \right) + ) \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} 0 &= -e_V + V_{\mathrm{ref}} + V_{\mathrm{uel}} + V_S - V_C \\ - 0 &= -V_R + \text{clamp}(K_{\mathrm{pr}}e_V + x_R, V_R^{\min}, V_R^{\max}) \\ + 0 &= -V_R + \text{clamp}(K_{\mathrm{pr}}e_V + x_R; V_R^{\min}, V_R^{\max}) \\ 0 &= -V_G + \text{min}(K_G E_{\mathrm{fd}}, V_G^{\max}) \\ 0 &= -e_M + V_A - V_G \\ 0 &= -V_{\mathrm{lv}} + \text{min}(V_M, V_{\mathrm{oel}}) \\ - 0 &= -V_{\mathrm{src}}^{\mathrm{r}} - + K_P V_{\mathrm{r}} - - X_L K_P^{\mathrm{i}} I_{\mathrm{r}} - - \left(K_I + X_L K_P^{\mathrm{r}}\right)I_{\mathrm{i}} \\ - 0 &= -V_{\mathrm{src}}^{\mathrm{i}} - + K_P V_{\mathrm{i}} - + \left(K_I + X_L K_P^{\mathrm{r}}\right)I_{\mathrm{r}} - - X_L K_P^{\mathrm{i}} I_{\mathrm{i}} \\ + 0 &= -V_{\mathrm{src}}^r + + K_P V_r + - X_L K_P^i I_r + - (K_I + X_L K_P^r)I_i \\ + 0 &= -V_{\mathrm{src}}^i + + K_P V_i + + (K_I + X_L K_P^r)I_r + - X_L K_P^i I_i \\ 0 &= -V_E^2 - + \left(V_{\mathrm{src}}^{\mathrm{r}}\right)^2 - + \left(V_{\mathrm{src}}^{\mathrm{i}}\right)^2 \\ + + (V_{\mathrm{src}}^r)^2 + + (V_{\mathrm{src}}^i)^2 \\ 0 &= -V_E I_N + K_C I_{\mathrm{fd}} \\ 0 &= -F_{\mathrm{ex}} + f(I_N) \\ 0 &= -V_B + \text{min}(V_E F_{\mathrm{ex}}, V_B^{\max}) \\ @@ -179,54 +196,55 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines helper targets for [min and clamp](../../../../CommonMath.md#derived-functions). -The rectifier loading function $f(I_N)$ is the source curve shown in Fig. 1. +### External Equations + +None. ## Initialization For a standard unsaturated start, the machine initializes -$E_{\mathrm{fd},0}$ and $I_{\mathrm{fd},0}$ first. ESST4B reads those values, +$E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ first. ESST4B reads those values, sets all internal derivatives to zero, and evaluates: ```math \begin{aligned} - V_{C,0} &= V_{\mathrm{comp},0} \\ - V_{\mathrm{src},0}^{\mathrm{r}} - &= K_P V_{\mathrm{r},0} - - X_L K_P^{\mathrm{i}} I_{\mathrm{r},0} - - \left(K_I + X_L K_P^{\mathrm{r}}\right)I_{\mathrm{i},0} \\ - V_{\mathrm{src},0}^{\mathrm{i}} - &= K_P V_{\mathrm{i},0} - + \left(K_I + X_L K_P^{\mathrm{r}}\right)I_{\mathrm{r},0} - - X_L K_P^{\mathrm{i}} I_{\mathrm{i},0} \\ - V_{E,0} &= + V_C &\leftarrow V_{\mathrm{comp}} \\ + V_{\mathrm{src}}^r + &\leftarrow K_P V_r + - X_L K_P^i I_r + - (K_I + X_L K_P^r)I_i \\ + V_{\mathrm{src}}^i + &\leftarrow K_P V_i + + (K_I + X_L K_P^r)I_r + - X_L K_P^i I_i \\ + V_E &\leftarrow \sqrt{ - \left(V_{\mathrm{src},0}^{\mathrm{r}}\right)^2 - + \left(V_{\mathrm{src},0}^{\mathrm{i}}\right)^2 + (V_{\mathrm{src}}^r)^2 + + (V_{\mathrm{src}}^i)^2 } \\ - 0 &= -V_{E,0}I_{N,0} + K_C I_{\mathrm{fd},0} \\ - F_{\mathrm{ex},0} &= f(I_{N,0}) \\ - V_{B,0} &= \text{min}(V_{E,0}F_{\mathrm{ex},0}, V_B^{\max}) \\ - V_{\mathrm{lv},0} &= \dfrac{E_{\mathrm{fd},0}}{V_{B,0}} \\ - V_{M,0} &= V_{\mathrm{lv},0} \\ - V_{G,0} &= \text{min}(K_G E_{\mathrm{fd},0}, V_G^{\max}) \\ - e_{M,0} &= 0 \\ - V_{A,0} &= V_{G,0} \\ - V_{R,0} &= V_{A,0} \\ - x_{R,0} &= V_{R,0} \\ - e_{V,0} &= 0 \\ - V_{\mathrm{ref},0} &= V_{C,0} - V_{\mathrm{uel},0} - V_{S,0} + I_N &\leftarrow \dfrac{K_C I_{\mathrm{fd}}}{V_E} \\ + F_{\mathrm{ex}} &\leftarrow f(I_N) \\ + V_B &\leftarrow \text{min}(V_E F_{\mathrm{ex}}, V_B^{\max}) \\ + V_{\mathrm{lv}} &\leftarrow \dfrac{E_{\mathrm{fd}}}{V_B} \\ + V_M &\leftarrow V_{\mathrm{lv}} \\ + V_G &\leftarrow \text{min}(K_G E_{\mathrm{fd}}, V_G^{\max}) \\ + e_M &\leftarrow 0 \\ + V_A &\leftarrow V_G \\ + V_R &\leftarrow V_A \\ + x_R &\leftarrow V_R \\ + e_V &\leftarrow 0 \\ + V_{\mathrm{ref}} &\leftarrow V_C - V_{\mathrm{uel}} - V_S \end{aligned} ``` -This closed-form start requires $V_{E,0}\ne 0$, $V_{B,0}\ne 0$, inactive +This closed-form start requires $V_E\ne 0$, $V_B\ne 0$, inactive $V_R$, $V_M$, $V_G$, and $V_B$ limits, and the low-value gate selecting $V_M$. Starts with active low-value gate limiting or saturated PI states are outside these closed-form equations. -## Model Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `vm` | [p.u.] | Inner regulator output | $V_M$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md index 31f04139a..30c5e26ca 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md @@ -1,11 +1,12 @@ -# **IEEE Type AC1 Excitation System Model (EXAC1)** +# EXAC1 EXAC1 is an IEEE Type AC excitation system with a terminal-voltage transducer, -lead-lag compensated voltage regulator, alternator field-voltage state, +lead–lag compensated voltage regulator, alternator field-voltage state, stabilizing feedback, exciter saturation, rectifier loading, and optional speed multiplier. -Notes: +## 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. @@ -14,38 +15,36 @@ Notes: ## Block Diagram -Standard model of the EXAC1 Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/EXAC1_diagram.png) Figure 1: Exciter EXAC1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -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 +Symbol | Units | JSON | Description | Typical Value | Note +-------------------|----------|----------|---------------------------------------------------------|---------------|----------------------------------------------- +$T_R$ | [s] | `Tr` | Transducer time constant | 0.0 | if zero, $V_C$ is algebraic +$T_B$ | [s] | `Tb` | Lag time constant for voltage-regulator input lead–lag | 0.0 | if $T_B=T_C=0$, the lead–lag block is bypassed +$T_C$ | [s] | `Tc` | Lead time constant for voltage-regulator input lead–lag | 0.0 | +$K_A$ | [p.u.] | `Ka` | Voltage-regulator gain | 40.0 | +$T_A$ | [s] | `Ta` | Voltage-regulator time constant | 0.1 | +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | +$T_E$ | [s] | `Te` | Exciter alternator time constant | 0.5 | +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | +$T_F$ | [s] | `Tf` | Stabilizing feedback time constant | 0.7 | if zero, $V_F$ is algebraic +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | forms $I_N$ +$K_D$ | [p.u.] | `Kd` | Demagnetizing factor feedback gain | 0.0 | +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Source label: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Source label: `Se2` +$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | 1 enables the speed multiplier ### Parameter Validation -Invalid EXAC1 parameter sets are rejected by the following checks. +A valid EXAC1 parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -87,31 +86,44 @@ saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +--------|--------|------|------------ +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`voel` | Input | TBD | Over-excitation limiter input $V_{\mathrm{oel}}$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`speed` | Input | TBD | Machine speed deviation $\omega$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -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$ +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 -------------------------------------|--------|---------------------------------------------------------|------ -$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 +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 @@ -133,46 +145,49 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [$q$](../../../../CommonMath.md#quadratic-ramp). + +### Internal Equations + +#### Differential ```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_B\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + e_V \\ 0 &= -T_A\dot V_R - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_R, - -V_R + K_A V_{\mathrm{ll}}, + -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_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#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```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 &= -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 &= -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 + + (1+s_{\mathrm{spd}}\omega)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$. +When $T_B=T_C=0$, the lead–lag block is bypassed so +$V_{\mathrm{LL}}=e_V$. + +### External Equations + +None. ## Initialization @@ -184,10 +199,10 @@ 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} + 0 &= -V_E I_N + K_C I_{\mathrm{fd}} \\ + 0 &= -F_{\mathrm{ex}} + f(I_N) \\ + 0 &= -E_{\mathrm{fd}} + + (1+s_{\mathrm{spd}}\omega)F_{\mathrm{ex}}V_E \end{aligned} ``` @@ -195,33 +210,34 @@ 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} + S_E &\leftarrow S_B\,q(V_E - S_A) \\ + V_{\mathrm{FE}} &\leftarrow (K_E + S_E)V_E + K_D I_{\mathrm{fd}} \\ + V_R &\leftarrow V_{\mathrm{FE}} \\ + V_{\mathrm{LL}} &\leftarrow \dfrac{V_R}{K_A} \\ + V_C &\leftarrow E_C \\ + V_F &\leftarrow 0 \\ + e_V &\leftarrow V_{\mathrm{LL}} \\ + x_{\mathrm{LL}} &\leftarrow e_V \\ + V_{\mathrm{ref}} + &\leftarrow e_V + V_C + V_F + - V_S - V_{\mathrm{uel}} - V_{\mathrm{oel}} \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 +This standard start requires $1+s_{\mathrm{spd}}\omega\ne 0$, +$V_E\ne 0$, and $V_R^{\min}\le V_R\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$ +## Monitors + +Monitor | 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$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md index f957d31ff..d702740fb 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md @@ -1,11 +1,16 @@ -# **IEEE Type AC2 Excitation System Model (EXAC2)** +# EXAC2 -EXAC2 is an IEEE Type AC excitation system with a voltage transducer, lead-lag +EXAC2 is an IEEE Type AC excitation system with a voltage transducer, lead–lag input compensation, limited voltage-amplifier state, low-value gate, voltage regulator limits, exciter alternator state, stabilizing feedback, rectifier loading, saturation, and optional speed multiplier. -Notes: +> [!WARNING] +> Initialization does not yet invert the smooth gates and limits used by the +> model equations. + +## 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. @@ -14,44 +19,42 @@ Notes: ## Block Diagram -Standard model of the EXAC2 Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/EXAC2_diagram.png) Figure 1: Exciter EXAC2 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -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` -$T_C$ | [sec] | `Tc` | Lead time constant for voltage-regulator input lead-lag | 0.0 | Block name: `Tc` -$K_A$ | [p.u.] | `Ka` | Voltage-amplifier gain | 40.0 | Block name: `Ka` -$T_A$ | [sec] | `Ta` | Voltage-amplifier time constant | 0.1 | Block name: `Ta` -$V_A^{\max}$ | [p.u.] | `VaMax` | Maximum voltage-amplifier output | 1.0 | Block name: `VAMAX` -$V_A^{\min}$ | [p.u.] | `VaMin` | Minimum voltage-amplifier output | -1.0 | Block name: `VAMIN` -$K_B$ | [p.u.] | `Kb` | Regulator pre-limit gain after low-value gate | 1.0 | Block name: `KB` -$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_L$ | [p.u.] | `Kl` | Field-current limiter feedback gain | 0.0 | Block name: `KL` -$K_H$ | [p.u.] | `Kh` | Regulator feedback path gain | 0.0 | Block name: `KH` -$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` -$V_{\mathrm{lr}}$ | [p.u.] | `VLr` | Low-value gate lower reference | 0.0 | Source label: `VLR` -$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 +Symbol | Units | JSON | Description | Typical Value | Note +-------------------|----------|----------|---------------------------------------------------------|---------------|------------------------------- +$T_R$ | [s] | `Tr` | Transducer time constant | 0.0 | if zero, $V_C$ is algebraic +$T_B$ | [s] | `Tb` | Lag time constant for voltage-regulator input lead–lag | 0.0 | +$T_C$ | [s] | `Tc` | Lead time constant for voltage-regulator input lead–lag | 0.0 | +$K_A$ | [p.u.] | `Ka` | Voltage-amplifier gain | 40.0 | +$T_A$ | [s] | `Ta` | Voltage-amplifier time constant | 0.1 | +$V_A^{\max}$ | [p.u.] | `VaMax` | Maximum voltage-amplifier output | 1.0 | Source label: `VAMAX` +$V_A^{\min}$ | [p.u.] | `VaMin` | Minimum voltage-amplifier output | -1.0 | Source label: `VAMIN` +$K_B$ | [p.u.] | `Kb` | Regulator pre-limit gain after low-value gate | 1.0 | Source label: `KB` +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum voltage-regulator output | -1.0 | +$T_E$ | [s] | `Te` | Exciter alternator time constant | 0.5 | +$K_L$ | [p.u.] | `Kl` | Field-current limiter feedback gain | 0.0 | Source label: `KL` +$K_H$ | [p.u.] | `Kh` | Regulator feedback path gain | 0.0 | Source label: `KH` +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.05 | +$T_F$ | [s] | `Tf` | Stabilizing feedback time constant | 0.7 | if zero, $V_F$ is algebraic +$K_C$ | [p.u.] | `Kc` | Rectifier loading current coefficient | 0.0 | forms $I_N$ +$K_D$ | [p.u.] | `Kd` | Demagnetizing factor feedback gain | 0.0 | +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | +$V_{\mathrm{lr}}$ | [p.u.] | `VLr` | Low-value gate lower reference | 0.0 | Source label: `VLR` +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Source label: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Source label: `Se2` +$s_{\mathrm{spd}}$ | [binary] | `Spdmlt` | Speed multiplier flag | 0 | 1 enables the speed multiplier ### Parameter Validation -Invalid EXAC2 parameter sets are rejected by the following checks. +A valid EXAC2 parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -80,35 +83,48 @@ saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +--------|--------|------|------------ +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`voel` | Input | TBD | Over-excitation limiter input $V_{\mathrm{oel}}$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`speed` | Input | TBD | Machine speed deviation $\omega$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -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_A$ | [p.u.] | Limited voltage-amplifier output | State 3 in Fig. 1; source label: `VA` -$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$ +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_A$ | [p.u.] | Limited voltage-amplifier output | State 3 in Fig. 1; Source label: `VA` +$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 -------------------------------------|--------|---------------------------------------------------------|------ -$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 amplifier -$V_H$ | [p.u.] | Regulator feedback path signal | Block name: `KH` -$V_L$ | [p.u.] | Field-current limiter low-value gate input | Block name: `KL`; lower reference $V_{\mathrm{lr}}$ -$V_{\mathrm{lv}}$ | [p.u.] | Low-value gate output | Lesser of amplifier path and limiter path -$V_R$ | [p.u.] | Voltage-regulator output | Limited by $V_R^{\min}$ and $V_R^{\max}$ -$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 +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 amplifier +$V_H$ | [p.u.] | Regulator feedback path signal | Source label: `KH` +$V_L$ | [p.u.] | Field-current limiter low-value gate input | Source label: `KL`; lower reference $V_{\mathrm{lr}}$ +$V_{\mathrm{lv}}$ | [p.u.] | Low-value gate output | Lesser of amplifier path and limiter path +$V_R$ | [p.u.] | Voltage-regulator output | Limited by $V_R^{\min}$ and $V_R^{\max}$ +$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 @@ -130,50 +146,52 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`min`](../../../../CommonMath.md#minimum), [$q$](../../../../CommonMath.md#quadratic-ramp). + +### Internal Equations + +#### Differential ```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_B\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + e_V \\ 0 &= -T_A\dot V_A - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_A, - -V_A + K_A V_{\mathrm{ll}}, + -V_A + K_A V_{\mathrm{LL}}; V_A^{\min}, V_A^{\max} - \right) \\ - 0 &= -T_E\dot V_E + V_R - V_{\mathrm{fe}} \\ + ) \\ + 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#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```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 &= -V_H + K_H V_{\mathrm{fe}} \\ - 0 &= -V_L + V_{\mathrm{lr}} + K_L V_{\mathrm{fe}} \\ + 0 &= -T_B(V_{\mathrm{LL}} - x_{\mathrm{LL}}) + T_C(e_V - x_{\mathrm{LL}}) \\ + 0 &= -V_H + K_H V_{\mathrm{FE}} \\ + 0 &= -V_L + V_{\mathrm{lr}} + K_L V_{\mathrm{FE}} \\ 0 &= -V_{\mathrm{lv}} + \text{min}(V_A + V_H,\ V_L) \\ - 0 &= -V_R + \text{clamp}(K_B V_{\mathrm{lv}}, V_R^{\min}, V_R^{\max}) \\ + 0 &= -V_R + \text{clamp}(K_B V_{\mathrm{lv}}; V_R^{\min}, V_R^{\max}) \\ 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 &= -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 + + (1+s_{\mathrm{spd}}\omega)F_{\mathrm{ex}}V_E \end{aligned} ``` -CommonMath defines helper targets for [min and 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. -When $T_B=T_C=0$, the lead-lag block is bypassed so $V_{\mathrm{ll}}=e_V$. +When $T_B=T_C=0$, the lead–lag block is bypassed so $V_{\mathrm{LL}}=e_V$. + +### External Equations + +None. ## Initialization @@ -183,10 +201,10 @@ derivatives to zero, and first solves 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} + 0 &= -V_E I_N + K_C I_{\mathrm{fd}} \\ + 0 &= -F_{\mathrm{ex}} + f(I_N) \\ + 0 &= -E_{\mathrm{fd}} + + (1+s_{\mathrm{spd}}\omega)F_{\mathrm{ex}}V_E \end{aligned} ``` @@ -194,8 +212,8 @@ Then evaluate the feedback path: ```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} + S_E &\leftarrow S_B\,q(V_E - S_A) \\ + V_{\mathrm{FE}} &\leftarrow (K_E + S_E)V_E + K_D I_{\mathrm{fd}} \end{aligned} ``` @@ -203,39 +221,40 @@ Then solve the low-value gate and voltage-regulator chain: ```math \begin{aligned} - V_{R,0} &= V_{\mathrm{fe},0} \\ - V_{H,0} &= K_H V_{\mathrm{fe},0} \\ - V_{L,0} &= V_{\mathrm{lr}} + K_L V_{\mathrm{fe},0} \\ - V_{\mathrm{lv},0} &= \dfrac{V_{R,0}}{K_B} \\ - V_{A,0} &= V_{\mathrm{lv},0} - V_{H,0} \\ - V_{\mathrm{ll},0} &= \dfrac{V_{A,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} + V_R &\leftarrow V_{\mathrm{FE}} \\ + V_H &\leftarrow K_H V_{\mathrm{FE}} \\ + V_L &\leftarrow V_{\mathrm{lr}} + K_L V_{\mathrm{FE}} \\ + V_{\mathrm{lv}} &\leftarrow \dfrac{V_R}{K_B} \\ + V_A &\leftarrow V_{\mathrm{lv}} - V_H \\ + V_{\mathrm{LL}} &\leftarrow \dfrac{V_A}{K_A} \\ + V_C &\leftarrow E_C \\ + V_F &\leftarrow 0 \\ + e_V &\leftarrow V_{\mathrm{LL}} \\ + x_{\mathrm{LL}} &\leftarrow e_V \\ + V_{\mathrm{ref}} + &\leftarrow e_V + V_C + V_F + - V_S - V_{\mathrm{uel}} - V_{\mathrm{oel}} \end{aligned} ``` -This standard start requires $1+s_{\mathrm{spd}}\omega_0\ne 0$, -$V_{E,0}\ne 0$, $K_A\ne 0$, $K_B\ne 0$, inactive $V_A$ and $V_R$ limits, and +This standard start requires $1+s_{\mathrm{spd}}\omega\ne 0$, +$V_E\ne 0$, $K_A\ne 0$, $K_B\ne 0$, inactive $V_A$ and $V_R$ limits, and the low-value gate selecting the amplifier path. Starts with active low-value gate limiting or saturated regulator states 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$ -`va` | [p.u.] | Voltage-amplifier state | $V_A$ -`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$ -`vlv` | [p.u.] | Low-value gate output | $V_{\mathrm{lv}}$ -`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$ +## Monitors + +Monitor | 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$ +`va` | [p.u.] | Voltage-amplifier state | $V_A$ +`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$ +`vlv` | [p.u.] | Low-value gate output | $V_{\mathrm{lv}}$ +`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$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md index db6f96886..85ffa922c 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md @@ -1,107 +1,259 @@ -# **EXDC1** - -> [!NOTE] -> This documentation is not in the standard format and EXDC1 is not scheduled to be developed as of 06/26/2025. - - -![](../../../../../docs/Figures/EXDC1.JPG) - -Figure 1: Exciter EXDC1 model. Figure courtesy of [PoweWorld](https://www.powerworld.com/WebHelp/). - -## 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 +# EXDC1 + +EXDC1 is a direct-current excitation-system model with a voltage transducer, +input lead–lag compensation, a limited voltage regulator, exciter saturation, +and stabilizing feedback. + +## Notes + +- Internal voltage signals are on component base. +- The speed input is machine speed deviation, so the field-voltage multiplier + is $1 + \omega$. + +## Block Diagram + +![EXDC1 exciter block diagram](../../../../../docs/Figures/EXDC1.JPG) + +Figure 1: EXDC1 exciter model. Figure courtesy of the +[PowerWorld EXDC1 model reference](https://www.powerworld.com/WebHelp/Content/TransientModels_HTML/Exciter%20EXDC1.htm). + +## Model Parameters + +Symbol | Units | JSON | Description | Typical Value | Note +-------------|--------|------|--------------------------------------------|---------------|----- +$T_R$ | [s] | TBD | Voltage transducer time constant | 0.0 | +$K_A$ | [p.u.] | TBD | Voltage-regulator gain | 40.0 | +$T_A$ | [s] | TBD | Voltage-regulator time constant | 0.1 | +$T_B$ | [s] | TBD | Input lead–lag denominator time constant | 0.0 | +$T_C$ | [s] | TBD | Input lead–lag numerator time constant | 0.0 | +$V_R^{\max}$ | [p.u.] | TBD | Maximum voltage-regulator output | 1.0 | +$V_R^{\min}$ | [p.u.] | TBD | Minimum voltage-regulator output | -1.0 | +$K_E$ | [p.u.] | TBD | Exciter field resistance line slope margin | 0.1 | +$T_E$ | [s] | TBD | Exciter time constant | 0.5 | +$K_F$ | [p.u.] | TBD | Stabilizing feedback gain | 0.05 | +$T_{F1}$ | [s] | TBD | Stabilizing feedback time constant | 0.7 | +$E_1$ | [p.u.] | TBD | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | TBD | Saturation coefficient at $E_1$ | 0.08 | +$E_2$ | [p.u.] | TBD | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | TBD | Saturation coefficient at $E_2$ | 0.33 | + +JSON parameter names are not yet specified. + +### Parameter Validation + +A valid EXDC1 parameter set must satisfy the following conditions: + ```math -\dfrac{d\dfrac{E_{FD}}{\omega}}{dt}=\dfrac{1}{T_{E}}(V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega}) +\begin{aligned} +K_A &> 0 \\ +T_R, T_B, T_C, T_{F1} &\ge 0 \\ +T_A, T_E &> 0 \\ +T_B &> 0 + \quad\text{or}\quad +T_B = T_C = 0 \\ +V_R^{\min} &\le V_R^{\max} +\end{aligned} ``` -Feedback loop + +All parameters must be finite. + +The saturation points are either disabled together, + ```math -\dfrac{dx_{2}}{dt}=-\dfrac{V_{F}}{T_{F1}} +S_E(E_1) = S_E(E_2) = 0 ``` + +or define a valid two-point scaled-quadratic fit: + ```math -V_{F}=x_{2}+\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega} +\begin{aligned} +E_1, E_2 &> 0 \\ +S_E(E_1), S_E(E_2) &\ge 0 \\ +(E_2 - E_1) \left[S_E(E_2) - S_E(E_1)\right] &> 0 +\end{aligned} ``` -Saturation is modeled using an alternative quadratic function, with the value of Se specified at two points : + +### Model Derived Parameters + +The scaled saturation contribution is + ```math -Sat(x) = \begin{cases} - \dfrac{B(x-A)^2}{x} &\text{if } x>A \\ - 0 &\text{if } x<=A -\end{cases} +E S_E(E) = S_B q(E - S_A) ``` -same as with the synchronous machines. There are two solutions, and one where $A<1$ should be chosen. - -## Initialization + +where $q$ is the quadratic ramp. When saturation is disabled, + ```math -V_{t}=V_{t_{0}} +S_A = S_B = 0 ``` + +When one saturation value is zero, + ```math -E_{C}=V_{t_{0}} +\begin{aligned} +S_E(E_1) = 0 &: \quad + S_A = E_1, \qquad + S_B = \dfrac{E_2 S_E(E_2)}{(E_2 - E_1)^2} \\ +S_E(E_2) = 0 &: \quad + S_A = E_2, \qquad + S_B = \dfrac{E_1 S_E(E_1)}{(E_1 - E_2)^2} +\end{aligned} ``` + +When both saturation values are positive, + ```math -(V_{REF}-V_{t}-V_{F}+V_{S}+V_{UEL}+V_{OEL})=V_{B} +\begin{aligned} +C &= \sqrt{\dfrac{E_2 S_E(E_2)}{E_1 S_E(E_1)}} \\ +S_A &= \dfrac{C E_1 - E_2}{C - 1} \\ +S_B &= \dfrac{E_1 S_E(E_1)}{(E_1 - S_A)^2} +\end{aligned} ``` + +## Model Ports + +Name | Port | Init | Description +--------|--------|---------|------------ +`ec` | Input | Known | Compensated terminal-voltage magnitude +`speed` | Input | Known | Machine speed deviation +`vref` | Input | Unknown | Voltage-control reference +`vs` | Input | Known | Stabilizer input signal +`vuel` | Input | Known | Under-excitation limiter input +`voel` | Input | Known | Over-excitation limiter input +`efd` | Output | Known | Field-voltage output + +## Model Variables + +### Internal Variables + +#### Differential + +Symbol | Units | Description | Note +--------------------|--------|-------------------------------------|----- +$V_C$ | [p.u.] | Filtered terminal-voltage magnitude | Algebraic when $T_R = 0$ +$x_{\mathrm{LL}}$ | [p.u.] | Input lead–lag denominator state | Algebraic when $T_B = 0$ +$V_R$ | [p.u.] | Voltage-regulator output | +$E_{\mathrm{fd}}'$ | [p.u.] | Field-voltage state | Before the speed multiplier +$V_F$ | [p.u.] | Stabilizing feedback state | Algebraic when $T_{F1} = 0$ + +#### Algebraic + +Symbol | Units | Description | Note +------------------|--------|------------------------------------------|----- +$e_V$ | [p.u.] | Voltage-error summing output | +$V_B$ | [p.u.] | Input lead–lag output | +$s_e$ | [p.u.] | Scaled-quadratic saturation contribution | +$V_{\mathrm{FE}}$ | [p.u.] | Exciter feedback drive | +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------------------|--------|----------------------------------------|----- +$E_C$ | [p.u.] | Compensated terminal-voltage magnitude | +$\omega$ | [p.u.] | Machine speed deviation | +$V_{\mathrm{ref}}$ | [p.u.] | Voltage-control reference | +$V_S$ | [p.u.] | Stabilizer input signal | +$V_{\mathrm{uel}}$ | [p.u.] | Under-excitation limiter input | +$V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input | + +## Model Equations + +### Internal Equations + +#### Differential + ```math -V_{R}=V{R_{0}} +\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} + ( + V_R, -V_R + K_A V_B; + V_R^{\min}, V_R^{\max} + ) \\ +0 &= -T_E \dot{E}_{\mathrm{fd}}' + V_R - V_{\mathrm{FE}} \\ +0 &= -T_{F1} \dot{V}_F - V_F + + \dfrac{K_F}{T_E} (V_R - V_{\mathrm{FE}}) +\end{aligned} ``` + +#### Algebraic + ```math -V_{B}=\dfrac{V{R_{0}}}{K_{A}} +\begin{aligned} +0 &= -e_V + V_{\mathrm{ref}} + V_S + V_{\mathrm{uel}} + V_{\mathrm{oel}} - V_C - V_F \\ +0 &= + \begin{cases} + -V_B + e_V & T_B = T_C = 0 \\ + -T_B (V_B - x_{\mathrm{LL}}) + + T_C (e_V - x_{\mathrm{LL}}) & T_B > 0 + \end{cases} \\ +0 &= -s_e + S_B q(E_{\mathrm{fd}}' - S_A) \\ +0 &= -V_{\mathrm{FE}} + K_E E_{\mathrm{fd}}' + s_e \\ +0 &= -E_{\mathrm{fd}} + (1 + \omega) E_{\mathrm{fd}}' +\end{aligned} ``` + +The limiter and saturation use the CommonMath +[antiwindup](../../../../CommonMath.md#antiwindup) and +[quadratic ramp](../../../../CommonMath.md#quadratic-ramp) functions. + +### External Equations + +None. + +## Initialization + +### Input Initialization + ```math -\dfrac{E_{FD}}{\omega}=\dfrac{E_{FD_{0}}}{\omega} +\begin{aligned} +E_C &\leftarrow \text{compensated terminal-voltage magnitude} \\ +E_{\mathrm{fd}} &\leftarrow \text{machine field voltage} \\ +\omega &\leftarrow \text{machine speed deviation or }0 \\ +V_S &\leftarrow \text{stabilizer signal or }0 \\ +V_{\mathrm{uel}} &\leftarrow \text{under-excitation limiter input or }0 \\ +V_{\mathrm{oel}} &\leftarrow \text{over-excitation limiter input or }0 +\end{aligned} ``` + +### Internal Initialization + ```math -V_{R}-\dfrac{(K_{E}+S_{E})E_{FD}}{\omega}=0 +\begin{aligned} +V_C &\leftarrow E_C \\ +E_{\mathrm{fd}}' &\leftarrow \dfrac{E_{\mathrm{fd}}}{1 + \omega} \\ +s_e &\leftarrow S_B q(E_{\mathrm{fd}}' - S_A) \\ +V_{\mathrm{FE}} &\leftarrow K_E E_{\mathrm{fd}}' + s_e \\ +V_R &\leftarrow V_{\mathrm{FE}} \\ +V_B &\leftarrow \dfrac{V_R}{K_A} \\ +V_F &\leftarrow 0 \\ +e_V &\leftarrow V_B \\ +x_{\mathrm{LL}} &\leftarrow e_V \\ +\dot{V}_C, \dot{x}_{\mathrm{LL}}, \dot{V}_R, +\dot{E}_{\mathrm{fd}}', \dot{V}_F &\leftarrow 0 +\end{aligned} ``` + +Initialization requires $1 + \omega > 0$ and +$V_R^{\min} \le V_R \le V_R^{\max}$. + +### Output Initialization + ```math -V_{F}=0 +V_{\mathrm{ref}} +\leftarrow +e_V + V_C + V_F - V_S - V_{\mathrm{uel}} - V_{\mathrm{oel}} ``` -```math -x_{2_{0}}=-\dfrac{K_{F}}{T_{F1}}\dfrac{E_{FD}}{\omega} + +## Monitors + +TBD. diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md index fe51dbaca..5caa32e99 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md @@ -1,11 +1,16 @@ -# **Proportional/Integral Excitation System Model (EXPIC1)** +# EXPIC1 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: +> [!WARNING] +> The PI proportional path, regulator output limits, $T_E=0$ bypass, and +> initialization still need reconciliation with the source diagram. + +## 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. @@ -15,44 +20,42 @@ Notes: ## Block Diagram -Standard model of the EXPIC1 Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/EXPIC1_diagram.png) Figure 1: Exciter EXPIC1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -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$ +Symbol | Units | JSON | Description | Typical Value | Note +-------------------------|--------|----------|------------------------------------------------------|---------------|-------------------------------- +$T_R$ | [s] | `Tr` | Transducer time constant | 0.0 | if zero, $E_T$ is algebraic +$K_A$ | [p.u.] | `Ka` | PI regulator gain | 1.0 | +$T_{A1}$ | [s] | `Ta1` | PI regulator numerator time constant | 0.0 | +$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}$ | [s] | `Ta2` | First denominator time constant in regulator filter | 0.0 | +$T_{A3}$ | [s] | `Ta3` | Numerator time constant in regulator filter | 0.0 | +$T_{A4}$ | [s] | `Ta4` | Second denominator time constant in regulator filter | 0.0 | +$V_R^{\max}$ | [p.u.] | `Vrmax` | Maximum regulator output before source multiplier | 1.0 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Minimum regulator output before source multiplier | -1.0 | +$K_F$ | [p.u.] | `Kf` | Stabilizing feedback gain | 0.0 | +$T_{F1}$ | [s] | `Tf1` | First feedback denominator time constant | 0.0 | +$T_{F2}$ | [s] | `Tf2` | Second feedback denominator time constant | 0.0 | +$E_{\mathrm{fd}}^{\max}$ | [p.u.] | `Efdmax` | Maximum exciter input limit | 5.0 | Source label: `EFDMAX` +$E_{\mathrm{fd}}^{\min}$ | [p.u.] | `Efdmin` | Minimum exciter input limit | -5.0 | Source label: `EFDMIN` +$K_E$ | [p.u.] | `Ke` | Exciter field-resistance line-slope margin | 0.1 | +$T_E$ | [s] | `Te` | Exciter time constant | 0.5 | if zero, $E_{\mathrm{fd}}=E_0$ +$E_1$ | [p.u.] | `E1` | First saturation voltage point | 2.8 | +$S_E(E_1)$ | [p.u.] | `SE1` | Saturation value at $E_1$ | 0.08 | Source label: `Se1` +$E_2$ | [p.u.] | `E2` | Second saturation voltage point | 3.7 | +$S_E(E_2)$ | [p.u.] | `SE2` | Saturation value at $E_2$ | 0.33 | Source label: `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 | forms $I_N$ ### Parameter Validation -Invalid EXPIC1 parameter sets are rejected by the following checks. +A valid EXPIC1 parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -78,39 +81,54 @@ saturation factors are zero, use $S_A=0$ and $S_B=0$. Otherwise: \end{aligned} ``` -The source calculation uses explicit real and imaginary terminal voltage/current -components: +The source voltage components are: ```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}} + V_{\mathrm{src}}^r &= K_P V_r - K_I I_i \\ + V_{\mathrm{src}}^i &= K_P V_i + K_I I_r \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +-------|--------|------|-------------------------------------------------- +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`voel` | Input | TBD | Over-excitation limiter input $V_{\mathrm{oel}}$ +`vr` | Input | TBD | Terminal-voltage real component $V_r$ +`vi` | Input | TBD | Terminal-voltage imaginary component $V_i$ +`ir` | Input | TBD | Terminal-current real component $I_r$ +`ii` | Input | TBD | Terminal-current imaginary component $I_i$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables #### Differential -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` +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 ------------------------------------|--------|---------------------------------------------------------|------ $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}}^r$ | [p.u.] | Real component of the source expression | From terminal voltage/current components +$V_{\mathrm{src}}^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)$ @@ -126,34 +144,38 @@ None. #### Algebraic -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` +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_r$ | [p.u.] | Terminal-voltage real component | Source label: `VT` +$V_i$ | [p.u.] | Terminal-voltage imaginary component | Source label: `VT` +$I_r$ | [p.u.] | Terminal-current real component | Source label: `IT` +$I_i$ | [p.u.] | Terminal-current imaginary component | Source label: `IT` +$I_{\mathrm{fd}}$ | [p.u.] | Machine field current | Source label: `IFD` ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [$q$](../../../../CommonMath.md#quadratic-ramp). + +### Internal Equations + +#### Differential ```math \begin{aligned} 0 &= -T_R\dot E_T - E_T + E_C \\ 0 &= -\dot V_A - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( V_A, - K_A e_V, + 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 \\ @@ -162,19 +184,16 @@ $I_{\mathrm{fd}}$ | [p.u.] | Machine field current \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```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}}^r + K_P V_r - K_I I_i \\ + 0 &= -V_{\mathrm{src}}^i + K_P V_i + K_I I_r \\ 0 &= -V_{\mathrm{src}}^2 - + \left(V_{\mathrm{src}}^{\mathrm{r}}\right)^2 - + \left(V_{\mathrm{src}}^{\mathrm{i}}\right)^2 \\ + + (V_{\mathrm{src}}^r)^2 + + (V_{\mathrm{src}}^i)^2 \\ 0 &= \begin{cases} -I_N & K_P=0\ \text{and}\ K_I=0 \\ @@ -190,72 +209,73 @@ target and smooth approximation. 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 &= -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. +### External Equations + +None. + ## Initialization For a standard unsaturated start, the machine initializes -$E_{\mathrm{fd},0}$ and $I_{\mathrm{fd},0}$ first. EXPIC1 reads those values, +$E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ 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 + E_T &\leftarrow E_C \\ + V_{\mathrm{src}}^r &\leftarrow K_P V_r - K_I I_i \\ + V_{\mathrm{src}}^i &\leftarrow K_P V_i + K_I I_r \\ + V_{\mathrm{src}} + &\leftarrow \sqrt{ + (V_{\mathrm{src}}^r)^2 + + (V_{\mathrm{src}}^i)^2 } \\ - 0 &= + I_N &\leftarrow \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} + 0 & K_P=0\ \text{and}\ K_I=0 \\ + \dfrac{K_C I_{\mathrm{fd}}}{V_{\mathrm{src}}} & \text{otherwise} \end{cases} \\ - F_{\mathrm{ex},0} &= + F_{\mathrm{ex}} &\leftarrow \begin{cases} 1 & K_P=0\ \text{and}\ K_I=0 \\ - f(I_{N,0}) & \text{otherwise} + f(I_N) & \text{otherwise} \end{cases} \\ - V_{B,0} &= + V_B &\leftarrow \begin{cases} 1 & K_P=0\ \text{and}\ K_I=0 \\ - V_{\mathrm{src},0}F_{\mathrm{ex},0} & \text{otherwise} + V_{\mathrm{src}}F_{\mathrm{ex}} & \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} + S_E &\leftarrow S_B\,q(E_{\mathrm{fd}} - S_A) \\ + E_0 &\leftarrow (K_E + S_E)E_{\mathrm{fd}} \\ + V_R &\leftarrow \dfrac{E_0}{V_B} \\ + x_{R1} &\leftarrow V_R \\ + V_A &\leftarrow x_{R1} \\ + V_{F1} &\leftarrow V_R \\ + V_F &\leftarrow 0 \\ + e_V &\leftarrow \dfrac{V_A}{K_A} \\ + V_{\mathrm{ref}} + &\leftarrow e_V + E_T + V_F + - V_{\mathrm{uel}} - V_S - V_{\mathrm{oel}} \end{aligned} ``` -This closed-form start requires nonzero $K_A$ and $V_{B,0}$, inactive PI and +This closed-form start requires nonzero $K_A$ and $V_B$, 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$. +$K_P$ and $K_I$ are not both zero, it also requires $V_{\mathrm{src}}\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 +$E_{\mathrm{fd}}=E_0$. Starts that bind the PI regulator, cascaded regulator, or exciter limits are outside these closed-form equations. -## Model Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `et` | [p.u.] | Sensed terminal voltage | $E_T$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md b/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md index c33a3e9b3..80eeec31c 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md @@ -1,11 +1,15 @@ -# **IEEE Type 1 Excitation System Model (IEEET1)** +# IEEET1 -## Block Diagram +IEEE Type 1 excitation-system model. + +> [!WARNING] +> Compensation impedance is not modeled. -Standard model of the IEEET1 Exciter. +## Notes -Notes: -- The voltage-sensing input currently uses the positive bus-voltage magnitude $\sqrt{V_r^2 + V_i^2}$; a separate compensation-impedance path is not modeled here. +- Voltage sensing uses the bus-voltage magnitude $\sqrt{V_r^2 + V_i^2}$. + +## Block Diagram ![](../../../../../docs/Figures/PhasorDynamics_IEEET1_Diagram.png) @@ -13,33 +17,31 @@ Figure 1: Exciter IEEET1 model. Figure courtesy of [PowerWorld](https://www.powe ## Model Parameters - -Symbol | Units | Description | Typical Value | Note -------------|--------|--------------------------------------|---------| ------ -$T_R$ | [sec] | Time constant for voltage sensing | 0 | -$K_A$ | [p.u.] | Coefficient for voltage regulation | 50 | -$T_A$ | [sec] | Time constant for voltage regulation | 0.04 | -$K_E$ | [p.u.] | Exciter field resistance line slope margin; 0 requests automatic calculation, not a zero coefficient | -0.06 | -$T_E$ | [sec] | Time constant for excitation system | 0.6 | -$K_F$ | [p.u.] | Coefficient for feedback | 0.09 | -$T_F$ | [sec] | Time constant for feedback | 1.46 | -$V_R^{\min}$ | [p.u.] | Lower limit to voltage regulation | -1 | -$V_R^{\max}$ | [p.u.] | Upper limit to voltage regulation | 1 | -$E_1$ | [p.u.] | Saturation Parameter | 2.8 | -$E_2$ | [p.u.] | Saturation Parameter | 3.73 | -$S_1$ | [p.u.] | Saturation Parameter | 0.04 | -$S_2$ | [p.u.] | Saturation Parameter | 0.33 | -$I_{\mathrm{spdlim}}$ | [binary] | Speed limit flag indicator | 0 | +Symbol | Units | JSON | Description | Typical Value | Note +----------------------|----------|-----------|------------------------------------------------------------------------------------------------------|---------------|----- +$T_R$ | [s] | `Tr` | Time constant for voltage sensing | 0 | +$K_A$ | [p.u.] | `Ka` | Coefficient for voltage regulation | 50 | +$T_A$ | [s] | `Ta` | Time constant for voltage regulation | 0.04 | +$K_E$ | [p.u.] | `Ke` | Exciter field resistance line slope margin; 0 requests automatic calculation, not a zero coefficient | -0.06 | +$T_E$ | [s] | `Te` | Time constant for excitation system | 0.6 | +$K_F$ | [p.u.] | `Kf` | Coefficient for feedback | 0.09 | +$T_F$ | [s] | `Tf` | Time constant for feedback | 1.46 | +$V_R^{\min}$ | [p.u.] | `Vrmin` | Lower limit to voltage regulation | -1 | +$V_R^{\max}$ | [p.u.] | `Vrmax` | Upper limit to voltage regulation | 1 | +$E_1$ | [p.u.] | `E1` | Saturation Parameter | 2.8 | +$E_2$ | [p.u.] | `E2` | Saturation Parameter | 3.73 | +$S_1$ | [p.u.] | `Se1` | Saturation Parameter | 0.04 | +$S_2$ | [p.u.] | `Se2` | Saturation Parameter | 0.33 | +$I_{\mathrm{spdlim}}$ | [binary] | `Ispdlim` | Speed limit flag indicator | 0 | ### Parameter Validation -Invalid IEEET1 parameter sets are rejected by the following checks. Let $\epsilon_T=10^{-3}$. -Time constants below $\epsilon_T$ are raised to $\epsilon_T$ and logged as a warning; -every other condition is a configuration error. +A valid IEEET1 parameter set must satisfy the following conditions: ```math \begin{aligned} - T &\leftarrow \max\!\left(T, \epsilon_T\right) + \epsilon_T &= 10^{-3} \\ + T &\leftarrow \max\!(T, \epsilon_T) \quad T \in \{T_R, T_A, T_E, T_F\} \\ K_A &> 0 \\ @@ -47,7 +49,7 @@ every other condition is a configuration error. &\le V_R^{\max} \\ I_{\mathrm{spdlim}} &\in \{0,1\} \\ - \left(S_1, S_2\right) + (S_1, S_2) &=(0,0) \quad\text{or}\quad \begin{gathered} @@ -57,6 +59,9 @@ every other condition is a configuration error. \end{aligned} ``` +Time constants below $\epsilon_T$ are raised to $\epsilon_T$ and logged as a warning; +every other condition is a configuration error. + ### Model Derived Parameters When saturation is disabled, $S_A=0$ and $S_B=0$. Otherwise, @@ -78,7 +83,7 @@ corresponding voltage as the quadratic knee: S_1=0 &: \quad S_A=E_1,\qquad S_B=\dfrac{E_2S_2}{(E_2-E_1)^2} \\ S_2=0 &: \quad S_A=E_2,\qquad - S_B=\dfrac{E_1S_1}{(E_1-E_2)^2}. + S_B=\dfrac{E_1S_1}{(E_1-E_2)^2} \end{aligned} ``` @@ -120,23 +125,20 @@ units of $V_R^{\max}$: \begin{aligned} 0 &= V_R - -k_\text{sat} - -K_E^{\mathrm{eff}}E_{fd}', \\ + -k_\mathrm{sat} + -K_E^{\mathrm{eff}}E_{\mathrm{fd}}'\\ K_E^{\mathrm{eff}} &= \begin{cases} - \dfrac{1}{E_{fd}'} - \left(\dfrac{V_R^{\max}}{10}-k_\text{sat}\right) - & K_E=0, \\ + \dfrac{1}{E_{\mathrm{fd}}'} + \left(\dfrac{V_R^{\max}}{10}-k_\mathrm{sat}\right) + & K_E=0\\ K_E - & K_E\ne 0. + & K_E\ne 0 \end{cases} \end{aligned} ``` -Thus $K_E^{\mathrm{eff}}$ is the resolved value of the same exciter -coefficient, not an additional model input. - ## Model Ports Name | Port | Init | Description @@ -155,24 +157,22 @@ Name | Port | Init | Description #### Differential -Symbol | Units | Description | Note -----------|--------|------------------------------------|------- -$V_{ts}$ | [p.u.] | Sensed terminal voltage | -$V_R$ | [p.u.] | Voltage regulator | -$E_{fd}'$ | [p.u.] | Field voltage before the speed multiplier | -$V_{fx}$ | [p.u.] | Exciter feedback internal state | - +Symbol | Units | Description | Note +-------------------|--------|-------------------------------------------|----- +$V_\mathrm{ts}$ | [p.u.] | Sensed terminal voltage | +$V_R$ | [p.u.] | Voltage regulator | +$E_{\mathrm{fd}}'$ | [p.u.] | Field voltage before the speed multiplier | +$V_\mathrm{fx}$ | [p.u.] | Exciter feedback internal state | #### Algebraic - -Symbol | Units | Description | Note -----------------|--------|-----------------------------------|------- -$V_{tr}$ | [p.u.] | Terminal Voltage Error | -$V_f$ | [p.u.] | Feedback Voltage | -$V_E$ | [p.u.] | Excitation control voltage | -$E_{fd}$ | [p.u.] | Field winding voltage | -$k_\text{sat}$ | [p.u.] | Scaled-quadratic saturation contribution | $E_{fd}'S(E_{fd}')$ +Symbol | Units | Description | Note +------------------|--------|------------------------------------------|-------------------------------------- +$V_{\mathrm{tr}}$ | [p.u.] | Terminal Voltage Error | +$V_\mathrm{f}$ | [p.u.] | Feedback Voltage | +$V_E$ | [p.u.] | Excitation control voltage | +$E_{\mathrm{fd}}$ | [p.u.] | Field winding voltage | +$k_\mathrm{sat}$ | [p.u.] | Scaled-quadratic saturation contribution | $E_{\mathrm{fd}}'S(E_{\mathrm{fd}}')$ ### External Variables @@ -182,19 +182,20 @@ None. #### Algebraic -Symbol | Units | Description | Note -----------------|--------|-----------------------------------|------- -$V_r$ | [p.u.] | Real bus voltage component | -$V_i$ | [p.u.] | Imaginary bus voltage component | -$V_\text{ref}$ | [p.u.] | Reference terminal voltage | Signal port `vref` -$V_{UEL}$ | [p.u.] | Input from under excitation limiter | Signal port `vuel` -$V_{OEL}$ | [p.u.] | Input from over excitation limiter | Signal port `voel` -$V_S$ | [p.u.] | Input from stabilizer controller | Signal port `vs` -$\omega$ | [p.u.] | Machine speed deviation | Signal port `speed` - +Symbol | Units | Description | Note +-------------------|--------|-------------------------------------|-------------------- +$V_r$ | [p.u.] | Real bus voltage component | +$V_i$ | [p.u.] | Imaginary bus voltage component | +$V_\mathrm{ref}$ | [p.u.] | Reference terminal voltage | Signal port `vref` +$V_{\mathrm{uel}}$ | [p.u.] | Input from under excitation limiter | Signal port `vuel` +$V_{\mathrm{oel}}$ | [p.u.] | Input from over excitation limiter | Signal port `voel` +$V_S$ | [p.u.] | Input from stabilizer controller | Signal port `vs` +$\omega$ | [p.u.] | Machine speed deviation | Signal port `speed` ## Model Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [$q$](../../../../CommonMath.md#quadratic-ramp). + ### Internal Equations #### Differential @@ -203,7 +204,7 @@ For readability, define the pre-limit derivative of $V_R$ and voltage-sensing in ```math \begin{aligned} -f_R &:= \dfrac{1}{T_A}\left(-V_R + K_A V_{tr}\right) \\ +f_R &:= \dfrac{1}{T_A}(-V_R + K_A V_{\mathrm{tr}}) \\ E_C &:= \sqrt{V_r^2 + V_i^2} \end{aligned} ``` @@ -212,58 +213,48 @@ The IEEET1 differential equations, as derived from the model diagram, are: ```math \begin{aligned} - 0 &= -\dot V_{ts} + \dfrac{1}{T_R}\left(E_C - V_{ts}\right) \\ + 0 &= -\dot V_\mathrm{ts} + \dfrac{1}{T_R}(E_C - V_\mathrm{ts}) \\ 0 &= -\dot V_R + \text{antiwindup} - \left(V_R, f_R; V_R^{\min}, V_R^{\max}\right) \\ - 0 &= -\dot E_{fd}' + \dfrac{1}{T_E}\left(V_R - V_E - K_E^{\mathrm{eff}} E_{fd}'\right) \\ - 0 &= -\dot V_{fx} + \dfrac{1}{T_F}\left(V_f\right) + (V_R, f_R; V_R^{\min}, V_R^{\max}) \\ + 0 &= -\dot E_{\mathrm{fd}}' + \dfrac{1}{T_E}(V_R - V_E - K_E^{\mathrm{eff}} E_{\mathrm{fd}}') \\ + 0 &= -\dot V_\mathrm{fx} + \dfrac{1}{T_F}(V_\mathrm{f}) \end{aligned} ``` -CommonMath defines the smooth [Anti-Windup](../../../../CommonMath.md#antiwindup) target and approximation. - #### Algebraic -The algebraic equations of the exciter. ```math \begin{aligned} - 0 &= -V_{ts} + V_\text{ref} + V_{UEL} + V_{OEL} + V_S - V_{tr} - V_f \\ - 0 &= -T_F(V_f + V_{fx}) + K_F E_{fd}' \\ - 0 &= -V_E + k_\text{sat} \\ - 0 &= -E_{fd} + (1 + \omega I_{\mathrm{spdlim}})E_{fd}' \\ - 0 &= -k_\text{sat} + S_B\, q(E_{fd}' - S_A) + 0 &= -V_\mathrm{ts} + V_\mathrm{ref} + V_{\mathrm{uel}} + V_{\mathrm{oel}} + V_S - V_{\mathrm{tr}} - V_\mathrm{f} \\ + 0 &= -T_F(V_\mathrm{f} + V_\mathrm{fx}) + K_F E_{\mathrm{fd}}' \\ + 0 &= -V_E + k_\mathrm{sat} \\ + 0 &= -E_{\mathrm{fd}} + (1 + \omega I_{\mathrm{spdlim}})E_{\mathrm{fd}}' \\ + 0 &= -k_\mathrm{sat} + S_B\, q(E_{\mathrm{fd}}' - S_A) \end{aligned} ``` -Here $q$ is GridKit's [Quadratic Ramp](../../../../CommonMath.md#quadratic-ramp). - ### External Equations None. ## Initialization -The machine initializes $E_{fd}$ first. IEEET1 -reads that value, along with any attached $\omega$, $V_S$, $V_{UEL}$, and $V_{OEL}$, and -solves the steady-state algebraic chain so all residuals vanish with -$\dot y = 0$. The sensed terminal voltage initializes from the positive -bus-voltage magnitude. Saturation is included when enabled, and the speed-limit -flag is included directly. $V_\text{ref}$ is set to close the $V_{tr}$ equation -with the current input values. +The machine initializes $E_{\mathrm{fd}}$ first. Set $V_\mathrm{ref}$ to close +the $V_{\mathrm{tr}}$ equation: ```math \begin{aligned} - E_C &:= \sqrt{V_r^2 + V_i^2} \\ - E_{fd}' &= \dfrac{E_{fd}}{1 + I_{\mathrm{spdlim}}\,\omega} \\ - k_\text{sat} &= S_B\, q(E_{fd}' - S_A) \\ - V_E &= k_\text{sat} \\ - V_R &= K_E^{\mathrm{eff}} E_{fd}' + V_E \\ - V_{tr} &= \dfrac{V_R}{K_A} \\ - V_{fx} &= \dfrac{K_F}{T_F}\, E_{fd}' \\ - V_{ts} &= E_C \\ - V_f &= 0 \\ - V_\text{ref} &= E_C + V_{tr} - V_{UEL} - V_{OEL} - V_S + E_C &\leftarrow \sqrt{V_r^2 + V_i^2} \\ + E_{\mathrm{fd}}' &\leftarrow \dfrac{E_{\mathrm{fd}}}{1 + I_{\mathrm{spdlim}}\,\omega} \\ + k_\mathrm{sat} &\leftarrow S_B\, q(E_{\mathrm{fd}}' - S_A) \\ + V_E &\leftarrow k_\mathrm{sat} \\ + V_R &\leftarrow K_E^{\mathrm{eff}} E_{\mathrm{fd}}' + V_E \\ + V_{\mathrm{tr}} &\leftarrow \dfrac{V_R}{K_A} \\ + V_\mathrm{fx} &\leftarrow \dfrac{K_F}{T_F}\, E_{\mathrm{fd}}' \\ + V_\mathrm{ts} &\leftarrow E_C \\ + V_\mathrm{f} &\leftarrow 0 \\ + V_\mathrm{ref} &\leftarrow E_C + V_{\mathrm{tr}} - V_{\mathrm{uel}} - V_{\mathrm{oel}} - V_S \end{aligned} ``` @@ -271,7 +262,7 @@ All internal derivatives initialize to zero. ## Monitors -Monitor | Units | Description | Note ----------|--------|-----------------------------------|------ -`efd` | [p.u.] | Field winding voltage | -`ksat` | [p.u.] | Scaled-quadratic saturation contribution | $S_B\,q(E_{fd}'-S_A)$ +Monitor | Units | Description | Note +--------|--------|------------------------------------------|------------------------------- +`efd` | [p.u.] | Field winding voltage | +`ksat` | [p.u.] | Scaled-quadratic saturation contribution | $S_B\,q(E_{\mathrm{fd}}'-S_A)$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/README.md b/GridKit/Model/PhasorDynamics/Exciter/README.md index 69e1851d5..34f9068ea 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/README.md @@ -1,25 +1,17 @@ -# **Exciter Models** - -> [!NOTE] -> IEEET1, SEXS-PTI, and ESDC1A exciters are currently implemented. - - -## Introduction - -An exciter generally models, regulates, and sustains -device internal voltage. +# Exciter Models +Exciters regulate machine field voltage. IEEET1, SEXS-PTI, and ESDC1A are implemented. ## Types -There are a few standard Exciter models -- ESAC6A Excitation Model (See [ESAC6A](ESAC6A/README.md)) -- IEEE Type 1 Excitation Model (See [IEEET1](IEEET1/README.md)) -- IEEE DC1 Excitation Model (See [EXDC1](EXDC1/README.md)) -- IEEE DC1A Excitation Model (See [ESDC1A](ESDC1A/README.md)) -- ESDC2A Excitation Model (See [ESDC2A](ESDC2A/README.md)) -- EXAC1 Excitation Model (See [EXAC1](EXAC1/README.md)) -- IEEE ST4B Excitation Model (See [ESST4B](ESST4B/README.md)) -- SCRX Excitation Model (See [SCRX](SCRX/README.md)) -- EXAC2 Excitation Model (See [EXAC2](EXAC2/README.md)) -- EXPIC1 Excitation Model (See [EXPIC1](EXPIC1/README.md)) -- Simplified Excitation System Model (See [SEXS-PTI](SEXS-PTI/README.md)) + +- [ESAC6A](ESAC6A/README.md) +- [ESDC1A](ESDC1A/README.md) +- [ESDC2A](ESDC2A/README.md) +- [ESST4B](ESST4B/README.md) +- [EXAC1](EXAC1/README.md) +- [EXAC2](EXAC2/README.md) +- [EXDC1](EXDC1/README.md) +- [EXPIC1](EXPIC1/README.md) +- [IEEET1](IEEET1/README.md) +- [SCRX](SCRX/README.md) +- [SEXS-PTI](SEXS-PTI/README.md) diff --git a/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md b/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md index e5eca2ed8..bb726cc53 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md @@ -1,43 +1,42 @@ -# **Bus Fed or Solid Fed Static Excitation System Model (SCRX)** +# SCRX -SCRX is a static excitation system with a voltage-error lead-lag block, a +SCRX is a static excitation system with a voltage-error lead–lag block, a limited exciter lag, and a source selector that scales the exciter output by either terminal voltage or a constant source. -Notes: +## Notes + - Internal voltage signals are on model base unless otherwise stated. - The source diagram shows a shared SCRX/SCRX1-style selector. In the diagram, `C_SWITCH = 0` selects the bus-fed multiplier $E_T$, and `C_SWITCH = 1` selects the solid-fed multiplier 1. -- Some source material labels the lead-lag numerator input as `TA/TB`; the +- Some source material labels the lead–lag numerator input as `TA/TB`; the model equations below use explicit time constants $T_A$ and $T_B$. - `Rc_Rfd` is a source-data parameter for input compatibility, but it is not an active block in Fig. 1 and is not used by the equations below. ## Block Diagram -Standard model of the SCRX Exciter. - ![](../../../../../docs/Figures/PhasorDynamics/SCRX_diagram.png) Figure 1: Exciter SCRX model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note -------------------------------------|----------|------------|---------------------------------------------------------|---------------|------ -$T_A$ | [sec] | `Ta` | Lead-lag numerator time constant | 0.0 | Source label: `TA/TB` in some SCRX source data -$T_B$ | [sec] | `Tb` | Lead-lag denominator time constant | 0.0 | Block name: `TB`; if zero, the lead-lag block is algebraic -$K$ | [p.u.] | `K` | Exciter gain | 1.0 | Block name: `K` -$T_E$ | [sec] | `Te` | Exciter lag time constant | 0.0 | Block name: `TE`; if zero, $E_{\mathrm{fd}}'$ is algebraic -$E_{\mathrm{fd}}^{\max}$ | [p.u.] | `Efdmax` | Maximum limited exciter output before source multiplier | 5.0 | Block name: `EFDMAX` -$E_{\mathrm{fd}}^{\min}$ | [p.u.] | `Efdmin` | Minimum limited exciter output before source multiplier | -5.0 | Block name: `EFDMIN` -$C_{\mathrm{sw}}$ | [binary] | `Cswitch` | Source multiplier selector | 0 | Source label: `C_SWITCH`; 0 = bus-fed $E_T$, 1 = solid-fed constant 1 -$R_c/R_{\mathrm{fd}}$ | [p.u.] | `Rc_Rfd` | Source-data compatibility parameter | 0.0 | Not active in Fig. 1 equations +Symbol | Units | JSON | Description | Typical Value | Note +-------------------------|----------|-----------|---------------------------------------------------------|---------------|---------------------------------------------------------------------- +$T_A$ | [s] | `Ta` | Lead–lag numerator time constant | 0.0 | Source label: `TA/TB` in some SCRX source data +$T_B$ | [s] | `Tb` | Lead–lag denominator time constant | 0.0 | Source label: `TB`; if zero, the lead–lag block is algebraic +$K$ | [p.u.] | `K` | Exciter gain | 1.0 | +$T_E$ | [s] | `Te` | Exciter lag time constant | 0.0 | Source label: `TE`; if zero, $E_{\mathrm{fd}}'$ is algebraic +$E_{\mathrm{fd}}^{\max}$ | [p.u.] | `Efdmax` | Maximum limited exciter output before source multiplier | 5.0 | Source label: `EFDMAX` +$E_{\mathrm{fd}}^{\min}$ | [p.u.] | `Efdmin` | Minimum limited exciter output before source multiplier | -5.0 | Source label: `EFDMIN` +$C_{\mathrm{sw}}$ | [binary] | `Cswitch` | Source multiplier selector | 0 | Source label: `C_SWITCH`; 0 = bus-fed $E_T$, 1 = solid-fed constant 1 +$R_c/R_{\mathrm{fd}}$ | [p.u.] | `Rc_Rfd` | Source-data compatibility parameter | 0.0 | Not active in Fig. 1 equations ### Parameter Validation -Invalid SCRX parameter sets are rejected by the following checks. +A valid SCRX parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -58,8 +57,17 @@ The source multiplier is: \end{aligned} ``` -When $T_B=0$, the lead-lag block is treated as a bypass with -$V_{\mathrm{ll}}=e_V$. +## Model Ports + +Name | Port | Init | Description +-------|--------|------|------------ +`ec` | Input | TBD | Compensated terminal voltage magnitude $E_C$ +`et` | Input | TBD | Terminal-voltage source multiplier $E_T$ +`vref` | Input | TBD | Voltage-control reference $V_{\mathrm{ref}}$ +`vuel` | Input | TBD | Under-excitation limiter input $V_{\mathrm{uel}}$ +`vs` | Input | TBD | Stabilizer input signal $V_S$ +`voel` | Input | TBD | Over-excitation limiter input $V_{\mathrm{oel}}$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ ## Model Variables @@ -67,19 +75,19 @@ $V_{\mathrm{ll}}=e_V$. #### Differential -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$x_{\mathrm{ll}}$ | [p.u.] | Lead-lag block state | State 1 in Fig. 1 -$E_{\mathrm{fd}}'$ | [p.u.] | Limited exciter output before source multiplier | State 2 in Fig. 1; algebraic when $T_E=0$ +Symbol | Units | Description | Note +-------------------|--------|-------------------------------------------------|------------------------------------------ +$x_{\mathrm{LL}}$ | [p.u.] | Lead–lag block state | State 1 in Fig. 1 +$E_{\mathrm{fd}}'$ | [p.u.] | Limited exciter output before source multiplier | State 2 in Fig. 1; algebraic when $T_E=0$ #### Algebraic -Symbol | Units | Description | Note -------------------------------------|--------|---------------------------------------------------------|------ -$e_V$ | [p.u.] | Voltage-error signal before lead-lag block | Summing junction in Fig. 1 -$V_{\mathrm{ll}}$ | [p.u.] | Lead-lag output | Drives the limited exciter lag -$M_{\mathrm{src}}$ | [p.u.] | Source multiplier | $E_T$ when $C_{\mathrm{sw}}=0$, 1 when $C_{\mathrm{sw}}=1$ -$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after source multiplier +Symbol | Units | Description | Note +-------------------|--------|--------------------------------------------|----------------------------------------------------------- +$e_V$ | [p.u.] | Voltage-error signal before lead–lag block | Summing junction in Fig. 1 +$V_{\mathrm{LL}}$ | [p.u.] | Lead–lag output | Drives the limited exciter lag +$M_{\mathrm{src}}$ | [p.u.] | Source multiplier | $E_T$ when $C_{\mathrm{sw}}=0$, 1 when $C_{\mathrm{sw}}=1$ +$E_{\mathrm{fd}}$ | [p.u.] | Field-voltage output | Output after source multiplier ### External Variables @@ -100,37 +108,42 @@ $V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup). + +### Internal Equations + +#### Differential ```math \begin{aligned} - 0 &= -T_B\dot x_{\mathrm{ll}} - x_{\mathrm{ll}} + e_V \\ + 0 &= -T_B\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + e_V \\ 0 &= -T_E\dot E_{\mathrm{fd}}' - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( E_{\mathrm{fd}}', - -E_{\mathrm{fd}}' + K V_{\mathrm{ll}}, + -E_{\mathrm{fd}}' + K V_{\mathrm{LL}}; E_{\mathrm{fd}}^{\min}, E_{\mathrm{fd}}^{\max} - \right) + ) \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} 0 &= -e_V + V_{\mathrm{ref}} + V_{\mathrm{uel}} + V_S + V_{\mathrm{oel}} - E_C \\ - 0 &= -T_B(V_{\mathrm{ll}} - x_{\mathrm{ll}}) + T_A(e_V - x_{\mathrm{ll}}) \\ + 0 &= -T_B(V_{\mathrm{LL}} - x_{\mathrm{LL}}) + T_A(e_V - x_{\mathrm{LL}}) \\ 0 &= -M_{\mathrm{src}} + (1 - C_{\mathrm{sw}})E_T + C_{\mathrm{sw}} \\ 0 &= -E_{\mathrm{fd}} + M_{\mathrm{src}}E_{\mathrm{fd}}' \end{aligned} ``` -When $T_B=0$, SCRX bypasses the lead-lag block so $V_{\mathrm{ll}}=e_V$. +When $T_B=0$, SCRX bypasses the lead–lag block so $V_{\mathrm{LL}}=e_V$. + +### External Equations + +None. ## Initialization @@ -140,25 +153,26 @@ or stabilizer inputs, sets all internal derivatives to zero, and evaluates: ```math \begin{aligned} - M_{\mathrm{src},0} &= (1 - C_{\mathrm{sw}})E_{T,0} + C_{\mathrm{sw}} \\ - E_{\mathrm{fd},0}' &= \dfrac{E_{\mathrm{fd},0}}{M_{\mathrm{src},0}} \\ - V_{\mathrm{ll},0} &= \dfrac{E_{\mathrm{fd},0}'}{K} \\ - x_{\mathrm{ll},0} &= e_{V,0} = V_{\mathrm{ll},0} \\ - V_{\mathrm{ref},0} - &= e_{V,0} + E_{C,0} - - V_{\mathrm{uel},0} - V_{S,0} - V_{\mathrm{oel},0} + M_{\mathrm{src}} &\leftarrow (1 - C_{\mathrm{sw}})E_T + C_{\mathrm{sw}} \\ + E_{\mathrm{fd}}' &\leftarrow \dfrac{E_{\mathrm{fd}}}{M_{\mathrm{src}}} \\ + V_{\mathrm{LL}} &\leftarrow \dfrac{E_{\mathrm{fd}}'}{K} \\ + e_V &\leftarrow V_{\mathrm{LL}} \\ + x_{\mathrm{LL}} &\leftarrow e_V \\ + V_{\mathrm{ref}} + &\leftarrow e_V + E_C + - V_{\mathrm{uel}} - V_S - V_{\mathrm{oel}} \end{aligned} ``` -This closed-form start requires $M_{\mathrm{src},0}\ne 0$, $K\ne 0$, and -$E_{\mathrm{fd}}^{\min}\le E_{\mathrm{fd},0}'\le E_{\mathrm{fd}}^{\max}$. +This closed-form start requires $M_{\mathrm{src}}\ne 0$, $K\ne 0$, and +$E_{\mathrm{fd}}^{\min}\le E_{\mathrm{fd}}'\le E_{\mathrm{fd}}^{\max}$. Starts that bind the exciter limit are outside these closed-form equations. -## Model Outputs +## Monitors -Output | Units | Description | Note -----------------|--------|-------------------------------------|------ -`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ -`efd_pre` | [p.u.] | Limited exciter output before source multiplier | $E_{\mathrm{fd}}'$ -`vll` | [p.u.] | Lead-lag output | $V_{\mathrm{ll}}$ -`msrc` | [p.u.] | Source multiplier | $M_{\mathrm{src}}$ +Monitor | Units | Description | Note +----------|--------|-------------------------------------------------|------------------- +`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ +`efd_pre` | [p.u.] | Limited exciter output before source multiplier | $E_{\mathrm{fd}}'$ +`vll` | [p.u.] | Lead–lag output | $V_{\mathrm{LL}}$ +`msrc` | [p.u.] | Source multiplier | $M_{\mathrm{src}}$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md index ed8bbd46d..bfb2735ca 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md @@ -1,8 +1,8 @@ -# **Simplified Excitation System Model (SEXS-PTI)** +# SEXS-PTI -## Block Diagram +Simplified excitation-system model. -Simplified excitation system model. +## Block Diagram ![](../../../../../docs/Figures/SEXS_PTI_DIAGRAM.png) @@ -10,14 +10,14 @@ Figure 1: Exciter SEXS-PTI model. Figure courtesy of [PowerWorld](https://www.po ## Model Parameters -Symbol | Units | Description | Typical Value | Note -----------------|--------|-----------------------------------------------|---------------|------ -$T_A$ | [sec] | Numerator time constant of lag-lead block | | -$T_B$ | [sec] | Denominator time constant of lag-lead block | | -$T_E$ | [sec] | Exciter field time constant | | -$K$ | [p.u.] | Voltage regulator gain | | -$E_{fd}^{\max}$ | [p.u.] | Maximum excitation output | | -$E_{fd}^{\min}$ | [p.u.] | Minimum excitation output | | +Symbol | Units | JSON | Description | Typical Value | Note +-------------------------|--------|----------|---------------------------------------------|---------------|----- +$T_A$ | [s] | `Ta` | Numerator time constant of lead–lag block | | +$T_B$ | [s] | `Tb` | Denominator time constant of lead–lag block | | +$T_E$ | [s] | `Te` | Exciter field time constant | | +$K$ | [p.u.] | `K` | Voltage regulator gain | | +$E_{\mathrm{fd}}^{\max}$ | [p.u.] | `Efdmax` | Maximum excitation output | | +$E_{\mathrm{fd}}^{\min}$ | [p.u.] | `Efdmin` | Minimum excitation output | | PowerWorld/PSS/E SEXS_PTI data often gives $T_A/T_B$ as a ratio. GridKit stores $T_A$ and $T_B$ separately, so convert ratio-format data with @@ -27,13 +27,13 @@ All six parameters are required; there are no defaults. ### Parameter Validation -Invalid SEXS-PTI parameter sets are rejected by the following checks: +A valid SEXS-PTI parameter set must satisfy the following conditions: ```math \begin{aligned} T_A &\ge 0 \\ T_B, T_E, K &> 0 \\ - E_{fd}^{\min} &< E_{fd}^{\max} + E_{\mathrm{fd}}^{\min} &< E_{\mathrm{fd}}^{\max} \end{aligned} ``` @@ -58,16 +58,16 @@ Name | Port | Init | Description #### Differential -Symbol | Units | Description | Note -----------|--------|-----------------------------------|----- -$V_R$ | [p.u.] | Lag-lead block state | -$E_{fd}$ | [p.u.] | Exciter field voltage output | +Symbol | Units | Description | Note +------------------|--------|------------------------------|----- +$V_R$ | [p.u.] | Lead–lag block state | +$E_{\mathrm{fd}}$ | [p.u.] | Exciter field voltage output | #### Algebraic -Symbol | Units | Description | Note -----------|--------|-----------------------------------|----- -$V_{tr}$ | [p.u.] | Terminal voltage error signal | +Symbol | Units | Description | Note +------------------|--------|-------------------------------|----- +$V_{\mathrm{tr}}$ | [p.u.] | Terminal voltage error signal | ### External Variables @@ -77,56 +77,40 @@ None. #### Algebraic -Symbol | Units | Description | Note -----------------|--------|----------------------------------------------|----- -$V_r$ | [p.u.] | Terminal voltage, real component | Bus input -$V_i$ | [p.u.] | Terminal voltage, imaginary component | Bus input -$V_{ref}$ | [p.u.] | Reference voltage | Signal port `vref` -$V_S$ | [p.u.] | Stabilizer output | Signal port `vs` -$V_{OEL}$ | [p.u.] | Over-excitation limiter signal | Signal port `voel` -$V_{UEL}$ | [p.u.] | Under-excitation limiter signal | Signal port `vuel` +Symbol | Units | Description | Note +-------------------|--------|---------------------------------------|------------------- +$V_r$ | [p.u.] | Terminal voltage, real component | Bus input +$V_i$ | [p.u.] | Terminal voltage, imaginary component | Bus input +$V_{\mathrm{ref}}$ | [p.u.] | Reference voltage | Signal port `vref` +$V_S$ | [p.u.] | Stabilizer output | Signal port `vs` +$V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter signal | Signal port `voel` +$V_{\mathrm{uel}}$ | [p.u.] | Under-excitation limiter signal | Signal port `vuel` ## Model Equations -Define the compensated terminal voltage magnitude for readability: +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup). ```math -E_C = \sqrt{V_r^2+V_i^2}. +E_C = \sqrt{V_r^2+V_i^2} ``` ### Internal Equations #### Differential -The SEXS-PTI differential equations, as derived from the model diagram. Define the pre-limit derivative of $E_{fd}$ - -```math -f = \dfrac{1}{T_E}\left[-E_{fd} + \dfrac{K}{T_B}(-V_R + T_A V_{tr})\right] -``` - -so that $\dot E_{fd}$ can be written in piecewise form compactly. - ```math \begin{aligned} - \dot V_R &= -V_{tr} + \dfrac{1}{T_B}(-V_R + T_A V_{tr}) \\ - \dot E_{fd} &= - \begin{cases} - f - & \text{if } (E_{fd}^{\min} < E_{fd} < E_{fd}^{\max}) & \lor \\ - & \quad (E_{fd} \leq E_{fd}^{\min} \land f > 0) & \lor \\ - & \quad (E_{fd} \geq E_{fd}^{\max} \land f < 0) \\ - 0 & \text{else} - \end{cases} +f &= \dfrac{-E_{\mathrm{fd}}+(K/T_B)(-V_R+T_AV_{\mathrm{tr}})}{T_E} \\ +0 &= -\dot V_R-V_{\mathrm{tr}}+\dfrac{-V_R+T_AV_{\mathrm{tr}}}{T_B} \\ +0 &= -\dot E_{\mathrm{fd}}+\text{antiwindup}(E_{\mathrm{fd}},f;E_{\mathrm{fd}}^{\min},E_{\mathrm{fd}}^{\max}) \end{aligned} ``` -In simulation the piecewise form above is replaced with a smooth approximation where $\phi$ is GridKit's smooth anti-windup indicator. See [CommonMath: Anti-Windup Indicator](../../../../CommonMath.md#antiwindup) for its definition, behavior, and design rationale. - #### Algebraic ```math \begin{aligned} -0&=-V_{tr}-E_C+V_{ref}+V_S+V_{OEL}+V_{UEL} +0&=-V_{\mathrm{tr}}-E_C+V_{\mathrm{ref}}+V_S+V_{\mathrm{oel}}+V_{\mathrm{uel}} \end{aligned} ``` @@ -137,13 +121,13 @@ None. ## Initialization The generator initializes the EFD signal first. SEXS-PTI then reads that value -and any attached $V_S$, $V_{OEL}$, and $V_{UEL}$ signals and assumes steady state: +and any attached $V_S$, $V_{\mathrm{oel}}$, and $V_{\mathrm{uel}}$ signals and assumes steady state: ```math \begin{aligned} -V_{tr,0} &= \dfrac{E_{fd,0}}{K} \\ -V_{R,0} &= (T_A - T_B)V_{tr,0} \\ -V_{ref} &= E_C + V_{tr,0} - V_S - V_{OEL} - V_{UEL} +V_{\mathrm{tr}} &\leftarrow \dfrac{E_{\mathrm{fd}}}{K} \\ +V_R &\leftarrow (T_A - T_B)V_{\mathrm{tr}} \\ +V_{\mathrm{ref}} &\leftarrow E_C + V_{\mathrm{tr}} - V_S - V_{\mathrm{oel}} - V_{\mathrm{uel}} \end{aligned} ``` @@ -152,5 +136,5 @@ All derivatives initialize to zero. ## Monitors Monitor | Units | Description | Note ---------|--------|----------------------|------ -`efd` | [p.u.] | Field-voltage output | $E_{fd}$ +--------|--------|----------------------|------------------ +`efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ diff --git a/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md b/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md index d5696627a..8d2dc1315 100644 --- a/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md @@ -1,8 +1,12 @@ -# **Gas Turbine-Governor Model (GASTPTI)** +# GASTPTI GASTPTI is a gas turbine-governor model with speed-droop fuel control and an exhaust-temperature low-value selector. +> [!WARNING] +> GridKit does not yet apply the associated generator's Governor Response Limits +> modes `Down Only` and `Fixed` to GASTPTI. Normal response is always used. + ## Notes - PowerWorld caps its load reference at $A_T$ during transient simulation; @@ -11,10 +15,6 @@ exhaust-temperature low-value selector. - Unlike PowerWorld, GridKit rejects rather than swaps reversed $V^{\min}$ and $V^{\max}$ values. -> [!WARNING] -> GridKit does not yet apply the associated generator's Governor Response Limits -> modes `Down Only` and `Fixed` to GASTPTI. Normal response is always used. - ## Block Diagram ![GASTPTI governor block diagram](../../../../../docs/Figures/PhasorDynamics/GASTPTI/diagram.png) @@ -24,21 +24,22 @@ Figure 1: GASTPTI governor model. Figure courtesy of the ## Model Parameters -Symbol | Units | JSON | Description | Default | Note -------------------|-----------|---------|---------------------------------------|-------------|----- -$R$ | [p.u.] | `R` | Permanent speed droop | 0.05 | Speed deviation per component-base power deviation -$T_1$ | [sec] | `T1` | Fuel-valve time constant | 0.4 | -$T_2$ | [sec] | `T2` | Fuel-flow time constant | 0.1 | -$T_3$ | [sec] | `T3` | Exhaust-temperature time constant | 3.0 | -$A_T$ | [p.u.] | `At` | Ambient-temperature load limit | 1.0 | Component base -$K_T$ | [p.u.] | `Kt` | Exhaust-temperature feedback gain | 2.0 | -$V^{\max}$ | [p.u.] | `Vmax` | Upper valve response limit | 1.0 | Component base -$V^{\min}$ | [p.u.] | `Vmin` | Lower valve response limit | 0.0 | Component base -$D^\mathrm{turb}$ | [p.u.] | `Dturb` | Turbine damping coefficient | 0.0 | Component-base power per speed deviation -$T^\mathrm{rate}$ | [MW] | `Trate` | Turbine rating | Required | Same-valued MVA component base; GridKit addition +Symbol | Units | JSON | Description | Typical Value | Note +------------------|--------|---------|-----------------------------------|---------------|--------------------------------------------------------------- +$R$ | [p.u.] | `R` | Permanent speed droop | 0.05 | Speed deviation per component-base power deviation +$T_1$ | [s] | `T1` | Fuel-valve time constant | 0.4 | +$T_2$ | [s] | `T2` | Fuel-flow time constant | 0.1 | +$T_3$ | [s] | `T3` | Exhaust-temperature time constant | 3.0 | +$A_T$ | [p.u.] | `At` | Ambient-temperature load limit | 1.0 | Component base +$K_T$ | [p.u.] | `Kt` | Exhaust-temperature feedback gain | 2.0 | +$V^{\max}$ | [p.u.] | `Vmax` | Upper valve response limit | 1.0 | Component base +$V^{\min}$ | [p.u.] | `Vmin` | Lower valve response limit | 0.0 | Component base +$D^\mathrm{turb}$ | [p.u.] | `Dturb` | Turbine damping coefficient | 0.0 | Component-base power per speed deviation +$T^\mathrm{rate}$ | [MW] | `Trate` | Turbine rating | Required | Same-valued MVA component base; GridKit addition ### Parameter Validation +A valid GASTPTI parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -57,7 +58,7 @@ $\epsilon_T$ are raised to that floor in place: ```math \begin{aligned} - T_x &\leftarrow \max\!\left(T_x,\epsilon_T\right), + T_x &\leftarrow \max\!(T_x,\epsilon_T), && x\in\{1,2,3\} \\ S^{\mathrm{base}} &\leftarrow 10^6 T^\mathrm{rate} \\ @@ -96,7 +97,7 @@ Symbol | Units | Description | Note $V_D$ | [p.u.] | Speed/load fuel demand | Component base $V_T$ | [p.u.] | Temperature-limit fuel demand | Component base $V$ | [p.u.] | Low-value selector output | Component base -$P_{\text{m}}$ | [p.u.] | Mechanical power output | System base +$P_\mathrm{m}$ | [p.u.] | Mechanical power output | System base ### External Variables @@ -106,13 +107,15 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note ------------------|--------|---------|-----------------------------|----- -$\omega$ | [p.u.] | Known | Machine speed deviation | Optional `speed`; defaults to zero -$P^\mathrm{ref}$ | [p.u.] | Unknown | Active-power/load reference | Optional `pref`; system base +Symbol | Units | Description | Note +-----------------|--------|-----------------------------|----------------------------------- +$\omega$ | [p.u.] | Machine speed deviation | Optional `speed`; defaults to zero +$P^\mathrm{ref}$ | [p.u.] | Active-power/load reference | Optional `pref`; system base ## Model Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`min`](../../../../CommonMath.md#minimum). + ### Internal Equations #### Differential @@ -126,16 +129,16 @@ $V_{\mathrm{resp}}^{\max}$, and $s^{\mathrm{valve}}$ are defined under 0 &= -\dot{x}_V + \dfrac{s^{\mathrm{valve}}}{T_1} - \text{antiwindup}\!\left( + \text{antiwindup}\!( x_V,V-x_V; V_{\mathrm{resp}}^{\min},V_{\mathrm{resp}}^{\max} - \right) \\ + ) \\ 0 &= -\dot{x}_F - + \dfrac{1}{T_2}\left(-x_F+x_V\right) \\ + + \dfrac{1}{T_2}(-x_F+x_V) \\ 0 &= -\dot{x}_T - + \dfrac{1}{T_3}\left(-x_T+x_F\right). + + \dfrac{1}{T_3}(-x_T+x_F) \end{aligned} ``` @@ -146,13 +149,10 @@ $V_{\mathrm{resp}}^{\max}$, and $s^{\mathrm{valve}}$ are defined under 0 &= - \omega + R(k_{\mathrm{base}}P^\mathrm{ref}-V_D) \\ 0 &= -V_T + A_T+K_T(A_T-x_T) \\ 0 &= -V + \text{min}(V_D,V_T) \\ - 0 &= -k_{\mathrm{base}}P_{\text{m}} + x_F-D^\mathrm{turb}\omega. + 0 &= -k_{\mathrm{base}}P_\mathrm{m} + x_F-D^\mathrm{turb}\omega \end{aligned} ``` -CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) -and [`min`](../../../../CommonMath.md#min) targets and smooth approximations. - ### External Equations None. @@ -164,7 +164,7 @@ None. ```math \begin{aligned} \omega &\leftarrow \text{machine speed deviation} \\ - P_{\text{m}} &\leftarrow \text{machine mechanical power} + P_\mathrm{m} &\leftarrow \text{machine mechanical power} \end{aligned} ``` @@ -173,17 +173,17 @@ None. ```math \begin{aligned} x_F - &\leftarrow k_{\mathrm{base}}P_{\text{m}} + &\leftarrow k_{\mathrm{base}}P_\mathrm{m} +D^\mathrm{turb}\omega \\ x_V,x_T &\leftarrow x_F \\ V_T - &\leftarrow A_T+K_T\left(A_T-x_F\right) \\ + &\leftarrow A_T+K_T(A_T-x_F) \\ m_T &\leftarrow V_T-x_F \\ - \left(V_{\mathrm{resp}}^{\min},V_{\mathrm{resp}}^{\max}\right) + (V_{\mathrm{resp}}^{\min},V_{\mathrm{resp}}^{\max}) &\leftarrow - \left(\min(V^{\min},x_F),\max(V^{\max},x_F)\right) + (\min(V^{\min},x_F),\max(V^{\max},x_F)) \end{aligned} ``` @@ -197,18 +197,18 @@ s^{\mathrm{valve}} ``` ```math -\left(V_{D},V\right) +(V_{D},V) \leftarrow \begin{cases} - \left( - V_T-\text{iramp}\!\left(m_T\right), - x_F - \right) + ( + V_T-\text{iramp}\!(m_T), + x_F, + ) & s^{\mathrm{valve}}=1 \\ - \left( + ( x_F, - \text{min}\!\left(x_F,V_T\right) - \right) + \text{min}\!(x_F,V_T) + ) & s^{\mathrm{valve}}=0 \end{cases} ``` @@ -218,52 +218,42 @@ $m_T$ so `iramp` is defined. All candidates and response bounds are validated before state, derivatives, or signals are changed; failed initialization is atomic. +A response limit that excludes the initialized fuel flow is widened to include +it, and a warning is logged. This matches PowerWorld's default +`Modify Limits and Run` treatment of initial limit violations. + ### Output Initialization ```math P^\mathrm{ref} \leftarrow \dfrac{1}{k_{\mathrm{base}}} - \left(V_D+\dfrac{\omega}{R}\right). + \left(V_D+\dfrac{\omega}{R}\right) ``` -Initialization preserves the machine-seeded system-base $P_{\mathrm{m}}$. An +Initialization preserves the machine-seeded system-base $P_\mathrm{m}$. An attached `pref` signal receives the initialized reference; an unattached port latches that value for subsequent residual evaluations. -## Monitorable Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ---------|--------|------------------------------------|----- -`pmech` | [p.u.] | Mechanical-power output | $P_{\text{m}}$; system base +`pmech` | [p.u.] | Mechanical-power output | $P_\mathrm{m}$; system base `xvalve` | [p.u.] | Fuel-valve state | $x_V$; component base `xflow` | [p.u.] | Fuel-flow state | $x_F$; component base `xtemp` | [p.u.] | Exhaust-temperature feedback state | $x_T$; component base `vload` | [p.u.] | Speed/load fuel demand | $V_D$; component base `vtemp` | [p.u.] | Temperature-limit fuel demand | $V_T$; component base -## Testing - -- `validation()` checks defaults, parameter domains, signal configuration, and - time-constant floors. -- `initializationAndSignals()` checks base conversion, signal initialization, - monitor values, and unattached-reference latching. -- `initializationDomain()` checks accepted and rejected operating points. -- `initializationExactness()` checks the smooth-selector inverse. -- `residualEquations()` checks every residual against a fixed numerical answer key. -- `governorControl()` checks droop, damping, response limits, and anti-windup. -- `temperatureLimiting()` checks the low-value selector. -- `jacobian()` compares full Enzyme and DependencyTracking maps across selector, - anti-windup, and collapsed-limit configurations when enabled. - ## Appendix A: `iramp` For a positive smooth-ramp output $v>0$ and CommonMath smoothing parameter $\mu$, ```math -\text{iramp}(v) = v+\dfrac{1}{\mu}\log\left(1-e^{-\mu v}\right). +\text{iramp}(v) = v+\dfrac{1}{\mu}\log(1-\exp(-\mu v)) ``` This is the positive-range inverse of GridKit's smooth -[`ramp`](../../../../CommonMath.md#rho-ramp). +[`ramp`](../../../../CommonMath.md#ramp). diff --git a/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md b/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md index 4b14a4662..5ede07219 100644 --- a/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md @@ -1,72 +1,72 @@ -# **GE General Governor-Turbine Model (GGOV1)** +# GGOV1 GGOV1 is a general governor-turbine model with electrical-power measurement, speed/load reference selection, proportional/integral/derivative governor control, load limiting, acceleration limiting, temperature limiting, actuator rate limits, turbine lag/lead dynamics, and optional diesel damping. -Notes: +> [!WARNING] +> The damping, fuel-flow, PID, limiter, temperature, and transport-delay paths +> remain incomplete or unverified. The initialization below does not yet +> establish a consistent steady state for the smooth selector paths. + +## Notes + - Internal control, valve-stroke, and turbine-power quantities are on the GGOV1 component base unless otherwise stated. - The dashed speed deadband block and `Db` source field are only for GGOV1D. GGOV1 uses the speed input directly. -- Source governor-response settings may modify $V^{\max}$ and $V^{\min}$ before - the equations are evaluated. - The source diagram notes that `Rup` and `Rdown` inputs are not implemented in Simulator; the equations below do not use those source fields. ## Block Diagram -Standard model of the GGOV1 Governor. - ![](../../../../../docs/Figures/PhasorDynamics/GGOV1_diagram.png) Figure 1: Governor GGOV1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note --------------------------------- | ----------- | ------------ | ----------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- -$P^{\mathrm{rate}}$ | [MW] | `Trate` | Optional turbine-rating power base | 0.0 | `Trate > 0` defines the governor base -$I_R$ | [integer] | `Rselect` | Droop feedback selector | 1 | Source label: `Rselect`; selects speed, electrical power, or valve feedback -$s_\mathrm{flag}$ | [binary] | `Flag` | Turbine-speed multiplier selector | 1 | 1 uses $1+\omega$, 0 uses 1.0 -$R$ | [p.u.] | `R` | Permanent droop | 0.05 | Source label: `r` -$T_\mathrm{pelec}$ | [sec] | `Tpelec` | Electrical-power measurement time constant | 0.0 | State 1 in Fig. 1 -$e^{\max}$ | [p.u.] | `Maxerr` | Maximum governor error | 1.0 | Source label: `maxerr` -$e^{\min}$ | [p.u.] | `Minerr` | Minimum governor error | -1.0 | Source label: `minerr` -$K_\mathrm{pgov}$ | [p.u.] | `Kpgov` | Governor proportional gain | 10.0 | Block name: `Kpgov` -$K_\mathrm{igov}$ | [p.u./s] | `Kigov` | Governor integral gain | 1.0 | Block name: `Kigov`; State 3 -$K_\mathrm{dgov}$ | [p.u.] | `Kdgov` | Governor differential gain | 0.0 | Block name: `Kdgov`; State 2 -$T_\mathrm{dgov}$ | [sec] | `Tdgov` | Governor differential time constant | 0.0 | Block name: `Tdgov` -$V^{\max}$ | [p.u.] | `Vmax` | Maximum governor output before actuator | 1.0 | Governor response limits may adjust this value -$V^{\min}$ | [p.u.] | `Vmin` | Minimum governor output before actuator | 0.0 | Governor response limits may adjust this value -$T_\mathrm{act}$ | [sec] | `Tact` | Turbine actuator time constant | 0.1 | State 4 in Fig. 1 -$R_\mathrm{open}$ | [p.u./s] | `Ropen` | Maximum actuator opening rate | 1.0 | Source label: `Ropen` -$R_\mathrm{close}$ | [p.u./s] | `Rclose` | Maximum actuator closing rate | -1.0 | Source label: `Rclose` -$K_\mathrm{turb}$ | [p.u.] | `Kturb` | Turbine gain | 1.0 | Block name: `Kturb` -$W_\mathrm{fnl}$ | [p.u.] | `Wfnl` | No-load fuel flow | 0.0 | Source label: `Wfnl` -$T_B$ | [sec] | `Tb` | Turbine lead-lag denominator time constant | 0.0 | State 5 in Fig. 1 -$T_C$ | [sec] | `Tc` | Turbine lead-lag numerator time constant | 0.0 | Block name: `Tc` -$T_\mathrm{eng}$ | [sec] | `Teng` | Engine transport lag | 0.0 | Source label: `e^{-sTeng}`; source transport delay is not represented as a differential state below -$T_\mathrm{fload}$ | [sec] | `Tfload` | Load-limiter lag time constant | 0.0 | State 6 in Fig. 1 -$K_\mathrm{pload}$ | [p.u.] | `Kpload` | Load-limiter proportional gain | 0.0 | Block name: `Kpload`; note path changes when zero -$K_\mathrm{iload}$ | [p.u./s] | `Kiload` | Load-limiter integral gain | 0.0 | State 7 in Fig. 1 -$L_\mathrm{dref}$ | [p.u.] | `Ldref` | Load reference | 1.0 | Source label: `Ldref` -$D_m$ | [p.u.] | `Dm` | Diesel damping gain | 0.0 | Source label: `Dm`; sign-dependent speed term in Fig. 1 -$K_\mathrm{imw}$ | [p.u./s] | `Kimw` | Supervisory load-control integral gain | 0.0 | State 8 in Fig. 1 -$A_\mathrm{set}$ | [p.u.] | `Aset` | Acceleration-control reference | 0.0 | Source label: `aset` -$K_A$ | [p.u.] | `Ka` | Acceleration-control gain | 0.0 | Block name: `KA` -$T_A$ | [sec] | `Ta` | Acceleration-control time constant | 0.0 | State 9 in Fig. 1 -$T_\mathrm{sa}$ | [sec] | `Tsa` | Temperature-detection numerator time constant | 0.0 | State 10 in Fig. 1 -$T_\mathrm{sb}$ | [sec] | `Tsb` | Temperature-detection denominator time constant | 0.0 | State 10 in Fig. 1 -$R_\mathrm{up}$ | [p.u./s] | `Rup` | Source upward ramp input | 0.0 | Source note says not implemented in Simulator -$R_\mathrm{down}$ | [p.u./s] | `Rdown` | Source downward ramp input | 0.0 | Source note says not implemented in Simulator +Symbol | Units | JSON | Description | Typical Value | Note +--------------------|-----------|-----------|-------------------------------------------------|---------------|---------------------------------------------------------------------------------------------------- +$P^{\mathrm{rate}}$ | [MW] | `Trate` | Optional turbine-rating power base | 0.0 | `Trate > 0` defines the governor base +$I_R$ | [integer] | `Rselect` | Droop feedback selector | 1 | selects speed, electrical power, or valve feedback +$s_\mathrm{flag}$ | [binary] | `Flag` | Turbine-speed multiplier selector | 1 | 1 uses $1+\omega$, 0 uses 1.0 +$R$ | [p.u.] | `R` | Permanent droop | 0.05 | Source label: `r` +$T_\mathrm{pelec}$ | [s] | `Tpelec` | Electrical-power measurement time constant | 0.0 | State 1 in Fig. 1 +$e^{\max}$ | [p.u.] | `Maxerr` | Upper limit on the signed governor error | 1.0 | Source label: `maxerr` +$e^{\min}$ | [p.u.] | `Minerr` | Lower limit on the signed governor error | -1.0 | Source label: `minerr` +$K_\mathrm{pgov}$ | [p.u.] | `Kpgov` | Governor proportional gain | 10.0 | +$K_\mathrm{igov}$ | [p.u./s] | `Kigov` | Governor integral gain | 1.0 | State 3 +$K_\mathrm{dgov}$ | [p.u.] | `Kdgov` | Governor differential gain | 0.0 | State 2 +$T_\mathrm{dgov}$ | [s] | `Tdgov` | Governor differential time constant | 0.0 | +$V^{\max}$ | [p.u.] | `Vmax` | Maximum governor output before actuator | 1.0 | Governor response limits may adjust this value +$V^{\min}$ | [p.u.] | `Vmin` | Minimum governor output before actuator | 0.0 | Governor response limits may adjust this value +$T_\mathrm{act}$ | [s] | `Tact` | Turbine actuator time constant | 0.1 | State 4 in Fig. 1 +$R_\mathrm{open}$ | [p.u./s] | `Ropen` | Maximum actuator opening rate | 1.0 | +$R_\mathrm{close}$ | [p.u./s] | `Rclose` | Maximum actuator closing rate | -1.0 | +$K_\mathrm{turb}$ | [p.u.] | `Kturb` | Turbine gain | 1.0 | +$W_\mathrm{fnl}$ | [p.u.] | `Wfnl` | No-load fuel flow | 0.0 | +$T_B$ | [s] | `Tb` | Turbine lead–lag denominator time constant | 0.0 | State 5 in Fig. 1 +$T_C$ | [s] | `Tc` | Turbine lead–lag numerator time constant | 0.0 | +$T_\mathrm{eng}$ | [s] | `Teng` | Engine transport lag | 0.0 | Source label: `e^{-sTeng}`; source transport delay is not represented as a differential state below +$T_\mathrm{fload}$ | [s] | `Tfload` | Load-limiter lag time constant | 0.0 | State 6 in Fig. 1 +$K_\mathrm{pload}$ | [p.u.] | `Kpload` | Load-limiter proportional gain | 0.0 | note path changes when zero +$K_\mathrm{iload}$ | [p.u./s] | `Kiload` | Load-limiter integral gain | 0.0 | State 7 in Fig. 1 +$L_\mathrm{dref}$ | [p.u.] | `Ldref` | Load reference | 1.0 | +$D_\mathrm{m}$ | [p.u.] | `Dm` | Diesel damping gain | 0.0 | sign-dependent speed term in Fig. 1 +$K_\mathrm{imw}$ | [p.u./s] | `Kimw` | Supervisory load-control integral gain | 0.0 | State 8 in Fig. 1 +$A_\mathrm{set}$ | [p.u.] | `Aset` | Acceleration-control reference | 0.0 | Source label: `aset` +$K_A$ | [p.u.] | `Ka` | Acceleration-control gain | 0.0 | Source label: `KA` +$T_A$ | [s] | `Ta` | Acceleration-control time constant | 0.0 | State 9 in Fig. 1 +$T_\mathrm{sa}$ | [s] | `Tsa` | Temperature-detection numerator time constant | 0.0 | State 10 in Fig. 1 +$T_\mathrm{sb}$ | [s] | `Tsb` | Temperature-detection denominator time constant | 0.0 | State 10 in Fig. 1 +$R_\mathrm{up}$ | [p.u./s] | `Rup` | Source upward ramp input | 0.0 | Source note says not implemented in Simulator +$R_\mathrm{down}$ | [p.u./s] | `Rdown` | Source downward ramp input | 0.0 | Source note says not implemented in Simulator ### Parameter Validation -Invalid GGOV1 parameter sets are rejected by the following checks. If source -governor-response settings adjust limits, apply these checks to the effective -values used by the equations. +A valid GGOV1 parameter set must satisfy the following conditions: ```math \begin{aligned} @@ -84,52 +84,66 @@ The component base and flag complements are: ```math \begin{aligned} - S_\mathrm{gov}^{\mathrm{base}} + S^{\mathrm{base}} &= \begin{cases} P^{\mathrm{rate}} & P^{\mathrm{rate}} \gt 0 \\ - S^{\mathrm{machine}} & \text{otherwise} + S^{\mathrm{sys}} & \text{otherwise} \end{cases} \\ s_\mathrm{flag}^{\mathrm{off}} &= 1 - s_\mathrm{flag} \end{aligned} ``` +$S^{\mathrm{sys}}$ is the system power base. + +## Model Ports + +Name | Port | Init | Description +-----------|--------|------|------------ +`pref` | Input | TBD | Governor reference +`paux` | Input | TBD | Auxiliary power input +`pmwset` | Input | TBD | Supervisory MW setpoint +`pelec` | Input | TBD | Electrical active power +`ldref` | Input | TBD | Load reference +`speed` | Input | TBD | Machine speed deviation +`pmech` | Output | TBD | Mechanical-power output + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description | Note ---------------------------------- | -------- | ------------------------------------- | ------------------------------------------------- -$P_\mathrm{elec}^{\mathrm{meas}}$ | [p.u.] | Measured electrical power | State 1 in Fig. 1; source label: `Pelec Measured` -$x_D$ | [p.u.] | Governor differential control state | State 2 in Fig. 1 -$x_I$ | [p.u.] | Governor integral control state | State 3 in Fig. 1 -$x_\mathrm{act}$ | [p.u.] | Turbine actuator or valve stroke | State 4 in Fig. 1 -$x_\mathrm{turb}$ | [p.u.] | Turbine lead-lag state | State 5 in Fig. 1; source label: `Turbine LL` -$x_\mathrm{load}$ | [p.u.] | Turbine load-limiter lag state | State 6 in Fig. 1 -$x_\mathrm{ldint}$ | [p.u.] | Turbine load integral-control state | State 7 in Fig. 1 -$x_\mathrm{mw}$ | [p.u.] | Supervisory load-control state | State 8 in Fig. 1 -$x_\mathrm{acc}$ | [p.u.] | Acceleration-control state | State 9 in Fig. 1 -$x_\mathrm{temp}$ | [p.u.] | Temperature-detection lead-lag state | State 10 in Fig. 1 +Symbol | Units | Description | Note +----------------------------------|--------|--------------------------------------|-------------------------------------------------- +$P_\mathrm{elec}^{\mathrm{meas}}$ | [p.u.] | Measured electrical power | State 1 in Fig. 1; Source label: `Pelec Measured` +$x_D$ | [p.u.] | Governor differential control state | State 2 in Fig. 1 +$x_I$ | [p.u.] | Governor integral control state | State 3 in Fig. 1 +$x_\mathrm{act}$ | [p.u.] | Turbine actuator or valve stroke | State 4 in Fig. 1 +$x_\mathrm{turb}$ | [p.u.] | Turbine lead–lag state | State 5 in Fig. 1; Source label: `Turbine LL` +$x_\mathrm{load}$ | [p.u.] | Turbine load-limiter lag state | State 6 in Fig. 1 +$x_\mathrm{ldint}$ | [p.u.] | Turbine load integral-control state | State 7 in Fig. 1 +$x_\mathrm{mw}$ | [p.u.] | Supervisory load-control state | State 8 in Fig. 1 +$x_\mathrm{acc}$ | [p.u.] | Acceleration-control state | State 9 in Fig. 1 +$x_\mathrm{temp}$ | [p.u.] | Temperature-detection lead–lag state | State 10 in Fig. 1 #### Algebraic -Symbol | Units | Description | Note --------------------------------- | ---------- | ----------------------------------------- | --------------------------------------------------- -$P_\mathrm{mwref}$ | [p.u.] | Supervisory load-control reference | From $P_\mathrm{mwset}-P_\mathrm{elec}$ -$y_R$ | [p.u.] | Selected droop feedback | Controlled by `Rselect` -$e_G$ | [p.u.] | Limited governor error | After $e^{\min}$ and $e^{\max}$ -$f_\mathrm{pid}$ | [p.u.] | Governor PID output | Forms `fsrn` -$f_\mathrm{srn}$ | [p.u.] | Normal governor fuel/stroke request | Low-value select input -$f_\mathrm{sra}$ | [p.u.] | Acceleration-control request | Low-value select input -$f_\mathrm{srt}$ | [p.u.] | Temperature/load request | Low-value select input -$f_\mathrm{srl}$ | [p.u.] | Acceleration/temperature low-value select | Lesser of $f_\mathrm{sra}$ and $f_\mathrm{srt}$ -$f_\mathrm{sr}$ | [p.u.] | Low-value select output | Limited by $V^{\min}$ and $V^{\max}$ -$r_\mathrm{act}$ | [p.u./s] | Actuator rate-limited derivative | Limited by $R_\mathrm{close}$ and $R_\mathrm{open}$ -$P_\mathrm{turb}$ | [p.u.] | Turbine power before damping | After turbine lead-lag and transport lag -$P_\mathrm{damp}$ | [p.u.] | Damping power term | Source label: `Dm` -$P_m$ | [p.u.] | Mechanical-power output | Source label: `Pmech` +Symbol | Units | Description | Note +-------------------|----------|-------------------------------------------|---------------------------------------------------- +$P_\mathrm{mwref}$ | [p.u.] | Supervisory load-control reference | From $P_\mathrm{mwset}-P_\mathrm{elec}$ +$y_R$ | [p.u.] | Selected droop feedback | Controlled by `Rselect` +$e_G$ | [p.u.] | Limited governor error | After $e^{\min}$ and $e^{\max}$ +$f_\mathrm{pid}$ | [p.u.] | Governor PID output | Forms `fsrn` +$f_\mathrm{srn}$ | [p.u.] | Normal governor fuel/stroke request | Low-value select input +$f_\mathrm{sra}$ | [p.u.] | Acceleration-control request | Low-value select input +$f_\mathrm{srt}$ | [p.u.] | Temperature/load request | Low-value select input +$f_\mathrm{srl}$ | [p.u.] | Acceleration/temperature low-value select | Lesser of $f_\mathrm{sra}$ and $f_\mathrm{srt}$ +$f_\mathrm{sr}$ | [p.u.] | Low-value select output | Limited by $V^{\min}$ and $V^{\max}$ +$r_\mathrm{act}$ | [p.u./s] | Actuator rate-limited derivative | Limited by $R_\mathrm{close}$ and $R_\mathrm{open}$ +$P_\mathrm{turb}$ | [p.u.] | Turbine power before damping | After turbine lead–lag and transport lag +$P_\mathrm{damp}$ | [p.u.] | Damping power term | Source label: `Dm` +$P_\mathrm{m}$ | [p.u.] | Mechanical-power output | Source label: `Pmech` ### External Variables @@ -150,7 +164,11 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`min`](../../../../CommonMath.md#minimum). + +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -158,26 +176,23 @@ $\omega$ | [p.u.] | Machine speed deviation 0 &= -T_\mathrm{dgov}\dot x_D - x_D + e_G \\ 0 &= -\dot x_I - + \text{antiwindup}\left( + + \text{antiwindup}( f_\mathrm{pid}, - K_\mathrm{igov}e_G, + K_\mathrm{igov}e_G; V^{\min}, V^{\max} - \right) \\ - 0 &= -T_\mathrm{act}\dot x_\mathrm{act} + r_\mathrm{act} \\ + ) \\ + 0 &= -\dot x_\mathrm{act} + r_\mathrm{act} \\ 0 &= -T_B\dot x_\mathrm{turb} - x_\mathrm{turb} + x_\mathrm{act} \\ 0 &= -T_\mathrm{fload}\dot x_\mathrm{load} - x_\mathrm{load} + f_\mathrm{srt} \\ - 0 &= -\dot x_\mathrm{ldint} + K_\mathrm{iload}\left(L_\mathrm{dref}-x_\mathrm{load}\right) \\ - 0 &= -\dot x_\mathrm{mw} + K_\mathrm{imw}\left(P_\mathrm{mwset}-P_\mathrm{elec}\right) \\ + 0 &= -\dot x_\mathrm{ldint} + K_\mathrm{iload}(L_\mathrm{dref}-x_\mathrm{load}) \\ + 0 &= -\dot x_\mathrm{mw} + K_\mathrm{imw}(P_\mathrm{mwset}-P_\mathrm{elec}) \\ 0 &= -T_A\dot x_\mathrm{acc} - x_\mathrm{acc} + \omega \\ 0 &= -T_\mathrm{sb}\dot x_\mathrm{temp} - x_\mathrm{temp} + f_\mathrm{sr} \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -188,14 +203,14 @@ target and smooth approximation. P_\mathrm{elec}^{\mathrm{meas}} & I_R = -1 \\ x_\mathrm{act} & I_R = -2 \end{cases} \\ - 0 &= -e_G + \text{clamp}(P_\mathrm{mwref} - y_R,\ e^{\min},\ e^{\max}) \\ + 0 &= -e_G + \text{clamp}(P_\mathrm{mwref} - y_R;\ e^{\min},\ e^{\max}) \\ 0 &= -f_\mathrm{pid} + K_\mathrm{pgov}e_G + K_\mathrm{dgov}(e_G - x_D) + x_I \\ - 0 &= -f_\mathrm{srn} + \text{clamp}(f_\mathrm{pid}, V^{\min}, V^{\max}) \\ - 0 &= -f_\mathrm{sra} + \text{clamp}\left(A_\mathrm{set} - K_A x_\mathrm{acc}, V^{\min}, V^{\max}\right) \\ - 0 &= -f_\mathrm{srt} + \text{clamp}\left(\dfrac{L_\mathrm{dref} + P_\mathrm{aux}}{K_\mathrm{turb}} + W_\mathrm{fnl} + x_\mathrm{ldint}, V^{\min}, V^{\max}\right) \\ - 0 &= -f_\mathrm{srl} + \min\left(f_\mathrm{sra}, f_\mathrm{srt}\right) \\ - 0 &= -f_\mathrm{sr} + \min\left(f_\mathrm{srn}, f_\mathrm{srl}\right) \\ - 0 &= -r_\mathrm{act} + \text{clamp}\left(\dfrac{f_\mathrm{sr}-x_\mathrm{act}}{T_\mathrm{act}}, R_\mathrm{close}, R_\mathrm{open}\right) \\ + 0 &= -f_\mathrm{srn} + \text{clamp}(f_\mathrm{pid}; V^{\min}, V^{\max}) \\ + 0 &= -f_\mathrm{sra} + \text{clamp}(A_\mathrm{set} - K_A x_\mathrm{acc}; V^{\min}, V^{\max}) \\ + 0 &= -f_\mathrm{srt} + \text{clamp}\left(\dfrac{L_\mathrm{dref} + P_\mathrm{aux}}{K_\mathrm{turb}} + W_\mathrm{fnl} + x_\mathrm{ldint}; V^{\min}, V^{\max}\right) \\ + 0 &= -f_\mathrm{srl} + \text{min}(f_\mathrm{sra}, f_\mathrm{srt}) \\ + 0 &= -f_\mathrm{sr} + \text{min}(f_\mathrm{srn}, f_\mathrm{srl}) \\ + 0 &= -r_\mathrm{act} + \text{clamp}\left(\dfrac{f_\mathrm{sr}-x_\mathrm{act}}{T_\mathrm{act}}; R_\mathrm{close}, R_\mathrm{open}\right) \\ 0 &= -P_\mathrm{turb} + K_\mathrm{turb} \begin{cases} @@ -203,37 +218,32 @@ target and smooth approximation. x_\mathrm{turb} + \dfrac{T_C}{T_B}(x_\mathrm{act}-x_\mathrm{turb}) - W_\mathrm{fnl} & T_B \gt 0 \end{cases} \\ 0 &= -P_\mathrm{damp} - + D_m + + D_\mathrm{m} \begin{cases} - \omega & D_m \ge 0 \\ - (1+\omega)^{D_m} & D_m \lt 0 + \omega & D_\mathrm{m} \ge 0 \\ + (1+\omega)^{D_\mathrm{m}} & D_\mathrm{m} \lt 0 \end{cases} \\ - 0 &= -P_m + P_\mathrm{turb} + P_\mathrm{damp} + 0 &= -P_\mathrm{m} + P_\mathrm{turb} + P_\mathrm{damp} \end{aligned} ``` -CommonMath defines helper targets and smooth approximations for -[clamp and min](../../../../CommonMath.md#derived-functions). -When $T_B=T_C=0$, the turbine lead-lag block is bypassed before the turbine +When $T_B=T_C=0$, the turbine lead–lag block is bypassed before the turbine gain and no-load fuel-flow calculation. -If `Kpgov = 0`, the source diagram routes the integral path in parallel with -the derivative control; document that effective structure before changing the -equations. If `Kpload = 0`, the source diagram feeds `Kiload/s` from the -`Kpload` input and avoids the `fsrn` feedback path. + +### External Equations + +None. ## Initialization -Initialization is performed by evaluating the steady-state residuals in -dependency order. Let subscript $0$ denote initial values and set all internal -derivatives to zero: +For a power-flow start, require $\omega=0$ and initialize all internal derivatives to zero: ```math \begin{aligned} - \omega_0 &= 0 \\ - P_{\mathrm{aux},0} &= 0 \\ - P_{\mathrm{elec},0}^{\mathrm{meas}} &= P_{\mathrm{elec},0} \\ - x_{\mathrm{acc},0} &= 0 \\ - P_{\mathrm{damp},0} &= 0 + P_{\mathrm{aux}} &\leftarrow 0,\quad \text{if omitted} \\ + P_{\mathrm{elec}}^{\mathrm{meas}} &\leftarrow P_{\mathrm{elec}} \\ + x_{\mathrm{acc}} &\leftarrow 0 \\ + P_{\mathrm{damp}} &\leftarrow 0 \end{aligned} ``` @@ -241,57 +251,55 @@ Given initialized machine mechanical power, solve the actuator and turbine path: ```math \begin{aligned} - P_{\mathrm{turb},0} &= P_{m,0} - P_{\mathrm{damp},0} \\ - x_{\mathrm{act},0} &= W_\mathrm{fnl} + \dfrac{P_{\mathrm{turb},0}}{K_\mathrm{turb}} \\ - x_{\mathrm{turb},0} &= x_{\mathrm{act},0} \\ - f_{\mathrm{sr},0} &= x_{\mathrm{act},0} \\ - f_{\mathrm{srn},0} &= f_{\mathrm{sra},0} = f_{\mathrm{srt},0} = f_{\mathrm{srl},0} = f_{\mathrm{sr},0} + P_{\mathrm{turb}} &\leftarrow P_{\mathrm{m}} - P_{\mathrm{damp}} \\ + x_{\mathrm{act}} &\leftarrow W_\mathrm{fnl} + \dfrac{P_{\mathrm{turb}}}{K_\mathrm{turb}} \\ + x_{\mathrm{turb}} &\leftarrow x_{\mathrm{act}} \\ + f_{\mathrm{sr}} &\leftarrow x_{\mathrm{act}} \\ + f_{\mathrm{srn}},f_{\mathrm{sra}},f_{\mathrm{srt}},f_{\mathrm{srl}} &\leftarrow f_{\mathrm{sr}} \end{aligned} ``` -Then seed the limiter and control states consistently: +Initialize the limiter and control states: ```math \begin{aligned} - x_{\mathrm{load},0} &= f_{\mathrm{srt},0} \\ - x_{\mathrm{ldint},0} - &= f_{\mathrm{srt},0} - - \dfrac{L_{\mathrm{dref},0}+P_{\mathrm{aux},0}}{K_\mathrm{turb}} + x_{\mathrm{load}} &\leftarrow f_{\mathrm{srt}} \\ + x_{\mathrm{ldint}} + &\leftarrow f_{\mathrm{srt}} + - \dfrac{L_{\mathrm{dref}}+P_{\mathrm{aux}}}{K_\mathrm{turb}} - W_\mathrm{fnl} \\ - x_{\mathrm{mw},0} &= 0 \\ - 0 &= + x_{\mathrm{mw}} &\leftarrow 0 \\ + y_R &\leftarrow \dfrac{1}{R} \begin{cases} - -R y_{R,0} + \omega_0 & I_R = 1 \\ - -R y_{R,0} + P_{\mathrm{elec},0}^{\mathrm{meas}} & I_R = -1 \\ - -R y_{R,0} + x_{\mathrm{act},0} & I_R = -2 + \omega & I_R = 1 \\ + P_{\mathrm{elec}}^{\mathrm{meas}} & I_R = -1 \\ + x_{\mathrm{act}} & I_R = -2 \end{cases} \\ - P_{\mathrm{mwref},0} &= f_{\mathrm{pid},0} + y_{R,0} \\ - P_{\mathrm{ref},0} &= P_{\mathrm{mwref},0} - P_{\mathrm{aux},0} - x_{\mathrm{mw},0} + P_{\mathrm{mwref}} &\leftarrow f_{\mathrm{pid}} + y_R \\ + P_{\mathrm{ref}} &\leftarrow P_{\mathrm{mwref}} - P_{\mathrm{aux}} - x_{\mathrm{mw}} \end{aligned} ``` -This closed-form start requires inactive low-value select alternatives, -inactive actuator rate limits, $V^{\min}\le f_{\mathrm{sr},0}\le V^{\max}$, -and $K_\mathrm{turb}\ne 0$. Starts where governor response settings fix -$V^{\min}$ or $V^{\max}$ to the initial condition must document those effective -limits before applying the residuals. - -## Model Outputs - -Output | Units | Description | Note ----------------- | -------- | ------------------------------------- | ----------------------- -`pmech` | [p.u.] | Mechanical-power output | $P_m$ -`pelec_meas` | [p.u.] | Measured electrical power | State 1 -`xd` | [p.u.] | Governor differential-control state | State 2 -`xi` | [p.u.] | Governor integral-control state | State 3 -`valve` | [p.u.] | Turbine actuator or valve stroke | State 4 -`turbine_ll` | [p.u.] | Turbine lead-lag state | State 5 -`load_limiter` | [p.u.] | Turbine load-limiter state | State 6 -`load_int` | [p.u.] | Turbine load integral-control state | State 7 -`mw_control` | [p.u.] | Supervisory load-control state | State 8 -`accel_control` | [p.u.] | Acceleration-control state | State 9 -`temp_ll` | [p.u.] | Temperature-detection lead-lag state | State 10 -`fsrn` | [p.u.] | Normal governor request | Low-value select input -`fsra` | [p.u.] | Acceleration-control request | Low-value select input -`fsrt` | [p.u.] | Temperature/load request | Low-value select input -`fsr` | [p.u.] | Selected governor request | Low-value select output +These assignments assume inactive low-value select alternatives, +inactive actuator rate limits, $V^{\min}\le f_{\mathrm{sr}}\le V^{\max}$, +and $K_\mathrm{turb}\ne 0$. + +## Monitors + +Monitor | Units | Description | Note +----------------|--------|--------------------------------------|------------------------ +`pmech` | [p.u.] | Mechanical-power output | $P_\mathrm{m}$ +`pelec_meas` | [p.u.] | Measured electrical power | State 1 +`xd` | [p.u.] | Governor differential-control state | State 2 +`xi` | [p.u.] | Governor integral-control state | State 3 +`valve` | [p.u.] | Turbine actuator or valve stroke | State 4 +`turbine_ll` | [p.u.] | Turbine lead–lag state | State 5 +`load_limiter` | [p.u.] | Turbine load-limiter state | State 6 +`load_int` | [p.u.] | Turbine load integral-control state | State 7 +`mw_control` | [p.u.] | Supervisory load-control state | State 8 +`accel_control` | [p.u.] | Acceleration-control state | State 9 +`temp_ll` | [p.u.] | Temperature-detection lead–lag state | State 10 +`fsrn` | [p.u.] | Normal governor request | Low-value select input +`fsra` | [p.u.] | Acceleration-control request | Low-value select input +`fsrt` | [p.u.] | Temperature/load request | Low-value select input +`fsr` | [p.u.] | Selected governor request | Low-value select output diff --git a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md index 42d892fe6..aaea78f2d 100644 --- a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md @@ -1,13 +1,15 @@ -# **Hydro Turbine-Governor Model (HYGOV)** +# HYGOV HYGOV is a hydro turbine-governor model with temporary droop, a gate servo, and a nonlinear single-penstock turbine. +> [!WARNING] +> HYGOVD `dbL`/`dbH`, mechanical backlash (`db2`), and Kaplan blade-servo +> behavior are not modeled. Nonzero `db2` values log a warning and are ignored. + ## Notes -- HYGOVD `dbL`/`dbH`, `db2` backlash, and Kaplan blade-servo fields are not - modeled. The `db2` JSON field is accepted for source-format compatibility. - A nonzero value logs a warning and is ignored. +None. ## Block Diagram @@ -19,22 +21,22 @@ Figure 1: HYGOV governor model. Figure courtesy of the ## Model Parameters Symbol | Units | JSON | Description | Typical Value | Note -------------------------|----------|---------------|------------------------------------------|---------------|------ +------------------------|----------|---------------|------------------------------------------|---------------|------------------------------------ $T^\mathrm{rate}$ | [MW] | `Trate` | Turbine-rating power base | 100.0 | Required $R_{\mathrm{perm}}$ | [p.u.] | `Rperm` | Permanent droop | 0.04 | Source label: `R` $R_{\mathrm{temp}}$ | [p.u.] | `Rtemp` | Temporary droop | 0.3 | Source label: `r` -$T_r$ | [sec] | `Tr` | Temporary-droop reset time constant | 5.0 | -$T_f$ | [sec] | `Tf` | Governor error filter time constant | 0.05 | -$T_g$ | [sec] | `Tg` | Gate servo time constant | 0.5 | +$T_\mathrm{r}$ | [s] | `Tr` | Temporary-droop reset time constant | 5.0 | +$T_\mathrm{f}$ | [s] | `Tf` | Governor error filter time constant | 0.05 | +$T_\mathrm{g}$ | [s] | `Tg` | Gate servo time constant | 0.5 | $V_{\mathrm{elm}}$ | [p.u./s] | `Velm` | Maximum desired-gate velocity magnitude | 0.2 | $G^{\max}$ | [p.u.] | `Gmax` | Configured upper gate response limit | 1.0 | $G^{\min}$ | [p.u.] | `Gmin` | Configured lower gate response limit | 0.0 | -$T_w$ | [sec] | `Tw` | Water inertia time constant | 1.0 | -$A_t$ | [p.u.] | `At` | Turbine gain | 1.2 | +$T_\mathrm{w}$ | [s] | `Tw` | Water inertia time constant | 1.0 | +$A_\mathrm{t}$ | [p.u.] | `At` | Turbine gain | 1.2 | $D_{\mathrm{turb}}$ | [p.u.] | `Dturb` | Turbine damping coefficient | 0.5 | $q_{\mathrm{NL}}$ | [p.u.] | `Qnl` | No-load flow at nominal head | 0.05 | -$T_n$ | [sec] | `Tn` | Speed lead-lag numerator time constant | 0.0 | -$T_{\mathrm{np}}$ | [sec] | `Tnp` | Speed lead-lag denominator time constant | 0.0 | +$T_\mathrm{n}$ | [s] | `Tn` | Speed lead–lag numerator time constant | 0.0 | +$T_{\mathrm{np}}$ | [s] | `Tnp` | Speed lead–lag denominator time constant | 0.0 | $D_{\omega}$ | [p.u.] | `db1` | Type 1 speed deadband threshold | 0.0 | $D_2$ | [p.u.] | `db2` | Unsupported mechanical backlash deadband | 0.0 | Nonzero values warn and are ignored $H_{\mathrm{dam}}$ | [p.u.] | `Hdam` | Configured dam head | 1.0 | Lower bound on effective head @@ -46,24 +48,22 @@ Real-valued parameters accept real or integer JSON values. All-zero `Gv` and ### Parameter Validation -Real-valued parameters, `Known` initial values, power bases, and base-conversion -ratios must be finite. The bases and ratios must also be positive. Invalid -HYGOV parameter sets are rejected by the following checks: +A valid HYGOV parameter set must satisfy the following conditions: ```math \begin{aligned} T^\mathrm{rate} &> 0 \\ - T_r, T_f, T_g, T_w, T_{\mathrm{np}} + T_\mathrm{r}, T_\mathrm{f}, T_\mathrm{g}, T_\mathrm{w}, T_{\mathrm{np}} &\ge 0 \\ R_{\mathrm{temp}} - &\ne 0 \\ - T_n + &> 0 \\ + T_\mathrm{n} &\ge 0 \\ V_{\mathrm{elm}} &\ge 0 \\ G^{\min} &< G^{\max} \\ - A_t + A_\mathrm{t} &> 0 \\ D_{\mathrm{turb}} &\ge 0 \\ @@ -79,11 +79,14 @@ HYGOV parameter sets are rejected by the following checks: \quad k\in\{0,\ldots,4\} \\ G_V^{(0)} \le G^{\min} &< G^{\max} \le G_V^{(5)} \\ - P_{\mathrm{m}}(G_V^{(5)}) - P_{\mathrm{m}}(G_V^{(0)}) + P_\mathrm{m}(G_V^{(5)}) - P_\mathrm{m}(G_V^{(0)}) &> \epsilon_{\mathrm{init}} \end{aligned} ``` +Real-valued parameters, `Known` initial values, power bases, and base-conversion +ratios must be finite. The bases and ratios must also be positive. + The final condition uses the steady mechanical power and tolerance defined under [Internal Initialization](#internal-initialization). @@ -95,29 +98,27 @@ raised to that floor in place, so every equation below uses the raised value: ```math \begin{aligned} T_x - &\leftarrow \max\!\left(T_x,\epsilon_T\right), + &\leftarrow \max\!(T_x,\epsilon_T), \quad x\in\{r,f,g,w,\mathrm{np}\} \\ k_{\mathrm{base}} - &= \dfrac{S^\mathrm{sys}}{10^6 T^\mathrm{rate}} \\ - k_n - &= \dfrac{T_n}{T_{\mathrm{np}}} \\ + &= \dfrac{S^\mathrm{sys}}{10^6\,T^\mathrm{rate}} \\ + k_\mathrm{n} + &= \dfrac{T_\mathrm{n}}{T_{\mathrm{np}}} \\ N_{\mathrm{GV}}(x) &= P_{\mathrm{GV}}^{(0)} + \sum_{k\in\{0,\ldots,4\}} - \text{linseg}\!\left( + \text{linseg}\!( x;\, G_V^{(k)},\, G_V^{(k+1)},\, P_{\mathrm{GV}}^{(k+1)} - P_{\mathrm{GV}}^{(k)} - \right) + ) \end{aligned} ``` -Multiplying by $k_\mathrm{base}$ converts system base to component base. - -CommonMath defines the [`linseg`](../../../../CommonMath.md#linseg) helper -used by $N_{\mathrm{GV}}$. +Multiplying by $k_\mathrm{base}$ converts system base to component base; +$S^\mathrm{sys}$ is the system power base in VA. ## Model Ports @@ -128,9 +129,8 @@ Name | Port | Init | Description `paux` | Input | Known | Auxiliary power input `pmech` | Output | Known | Mechanical power output -`Known` ports hold their initial values before `initialize()` and are preserved -by it. `Unknown` inputs are resolved during initialization and written to -attached signal storage, or retained as constant inputs when unattached. The +`Known` values are seeded before initialization and preserved. `Unknown` inputs +are initialized in attached signal storage or held constant when unattached. The `pmech` output must be assigned. The signal inputs are optional. Unattached `speed` and `paux` inputs default to zero. @@ -140,25 +140,25 @@ attached signal storage, or retained as constant inputs when unattached. The #### Differential -Symbol | Units | Description | Note -------------------------|--------|-------------------------------------|------ -$x_n$ | [p.u.] | Speed lead-lag denominator state | Not circled in Fig. 1. Realizes the `Tn`/`Tnp` block -$x_f$ | [p.u.] | Governor error filter output | State 1 in Fig. 1 -$c$ | [p.u.] | Desired-gate position | State 2 in Fig. 1 -$g$ | [p.u.] | Gate position | State 3 in Fig. 1 -$q$ | [p.u.] | Turbine flow | State 4 in Fig. 1 +Symbol | Units | Description | Note +-------|--------|----------------------------------|----------------------------------------------------- +$x_\mathrm{n}$ | [p.u.] | Speed lead–lag denominator state | Not circled in Fig. 1. Realizes the `Tn`/`Tnp` block +$x_\mathrm{f}$ | [p.u.] | Governor error filter output | State 1 in Fig. 1 +$c$ | [p.u.] | Desired-gate position | State 2 in Fig. 1 +$g$ | [p.u.] | Gate position | State 3 in Fig. 1 +$q$ | [p.u.] | Turbine flow | State 4 in Fig. 1 #### Algebraic -Symbol | Units | Description | Note -------------------------|----------|---------------------------------------------|------ -$\omega_{\mathrm{db}}$ | [p.u.] | Type 1 deadbanded speed deviation | -$e_f$ | [p.u.] | Governor error into the filter | Reference path less conditioned speed and permanent-droop feedback -$f_c$ | [p.u./s] | Desired-gate derivative target | Before rate and position limits -$r_c$ | [p.u./s] | Rate-limited desired-gate derivative target | Limited by $\pm V_{\mathrm{elm}}$ -$P_{\mathrm{GV}}$ | [p.u.] | Nonlinear gate-to-power curve output | $N_{\mathrm{GV}}(g)$ -$H$ | [p.u.] | Turbine head | Implicit water-column head -$P_{\mathrm{m}}$ | [p.u.] | Mechanical power to generator | System base +Symbol | Units | Description | Note +-----------------------|----------|---------------------------------------------|------------------------------------------------------------------- +$\omega_{\mathrm{db}}$ | [p.u.] | Type 1 deadbanded speed deviation | +$e_f$ | [p.u.] | Governor error into the filter | Reference path less conditioned speed and permanent-droop feedback +$f_c$ | [p.u./s] | Desired-gate derivative target | Before rate and position limits +$r_c$ | [p.u./s] | Rate-limited desired-gate derivative target | Limited by $\pm V_{\mathrm{elm}}$ +$P_{\mathrm{GV}}$ | [p.u.] | Nonlinear gate-to-power curve output | $N_{\mathrm{GV}}(g)$ +$H$ | [p.u.] | Turbine head | Implicit water-column head +$P_\mathrm{m}$ | [p.u.] | Mechanical power to generator | System base ### External Variables @@ -168,15 +168,19 @@ None. #### Algebraic -Symbol | Units | Init | Description | Note -------------------|--------|---------|-----------------------------|------ -$\omega$ | [p.u.] | Known | Machine speed deviation | Optional signal port `speed`. Defaults to zero -$P^\mathrm{ref}$ | [p.u.] | Unknown | Active-power/load reference | Optional signal port `pref`, system base -$P^\mathrm{aux}$ | [p.u.] | Known | Auxiliary power input | Optional signal port `paux`, system base, defaults to zero +Symbol | Units | Description | Note +-----------------|--------|-----------------------------|----------------------------------------------------------- +$\omega$ | [p.u.] | Machine speed deviation | Optional signal port `speed`. Defaults to zero +$P^\mathrm{ref}$ | [p.u.] | Active-power/load reference | Optional signal port `pref`, system base +$P^\mathrm{aux}$ | [p.u.] | Auxiliary power input | Optional signal port `paux`, system base, defaults to zero ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband1`](../../../../CommonMath.md#type-i-deadband), [`linseg`](../../../../CommonMath.md#linear-segment). + +### Internal Equations + +#### Differential The effective desired-gate response limits $G_{\mathrm{resp}}^{\min}$ and $G_{\mathrm{resp}}^{\max}$ and the effective @@ -187,52 +191,49 @@ dam head $H_{\mathrm{dam}}^{\mathrm{eff}}$ are resolved during initialization. 0 &= -\dot{x}_n + \dfrac{1}{T_{\mathrm{np}}} - \left(\omega_{\mathrm{db}} - x_n\right) \\ + (\omega_{\mathrm{db}} - x_\mathrm{n}) \\ 0 &= -\dot{x}_f - + \dfrac{1}{T_f} - \left(e_f - x_f\right) \\ + + \dfrac{1}{T_\mathrm{f}} + (e_f - x_\mathrm{f}) \\ 0 &= -\dot{c} + \text{antiwindup} - \left(c, r_c;\, G_{\mathrm{resp}}^{\min}, - G_{\mathrm{resp}}^{\max}\right) \\ + (c, r_c;\, G_{\mathrm{resp}}^{\min}, + G_{\mathrm{resp}}^{\max}) \\ 0 &= -\dot{g} - + \dfrac{1}{T_g} - \left(c - g\right) \\ + + \dfrac{1}{T_\mathrm{g}} + (c - g) \\ 0 &= -\dot{q} - + \dfrac{1}{T_w} - \left(H_{\mathrm{dam}}^{\mathrm{eff}} - H\right) + + \dfrac{1}{T_\mathrm{w}} + (H_{\mathrm{dam}}^{\mathrm{eff}} - H) \end{aligned} ``` -CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} 0 &= -\omega_{\mathrm{db}} + \text{deadband1} - \left(\omega;\, -D_{\omega}, D_{\omega}\right) \\ + (\omega;\, -D_{\omega}, D_{\omega}) \\ 0 &= -e_f - + k_{\mathrm{base}}\left(P^\mathrm{ref} + P^\mathrm{aux}\right) - - x_n - - k_n\left(\omega_{\mathrm{db}} - x_n\right) + + k_{\mathrm{base}}(P^\mathrm{ref} + P^\mathrm{aux}) + - x_\mathrm{n} + - k_\mathrm{n}(\omega_{\mathrm{db}} - x_\mathrm{n}) - R_{\mathrm{perm}}c \\ 0 &= -R_{\mathrm{temp}}f_c - + \dfrac{x_f}{T_r} - + \dfrac{e_f - x_f}{T_f} \\ + + \dfrac{x_\mathrm{f}}{T_\mathrm{r}} + + \dfrac{e_f - x_\mathrm{f}}{T_\mathrm{f}} \\ 0 &= -r_c + \text{clamp} - \left(f_c;\, -V_{\mathrm{elm}}, V_{\mathrm{elm}}\right) \\ + (f_c;\, -V_{\mathrm{elm}}, V_{\mathrm{elm}}) \\ 0 &= -P_{\mathrm{GV}} + N_{\mathrm{GV}}(g) \\ @@ -240,14 +241,15 @@ target and smooth approximation. -q^2 + H P_{\mathrm{GV}}^2 \\ 0 &= - -k_{\mathrm{base}}P_{\mathrm{m}} - + A_t H\left(q - q_{\mathrm{NL}}\right) + -k_{\mathrm{base}}P_\mathrm{m} + + A_\mathrm{t} H(q - q_{\mathrm{NL}}) - D_{\mathrm{turb}}\omega g \end{aligned} ``` -CommonMath defines helper targets and smooth approximations for -[deadband1 and clamp](../../../../CommonMath.md#derived-functions). +### External Equations + +None. ## Initialization @@ -257,14 +259,14 @@ CommonMath defines helper targets and smooth approximations for \begin{aligned} \omega &\leftarrow \text{machine speed deviation} \\ - P_{\mathrm{m}} + P_\mathrm{m} &\leftarrow \text{machine mechanical power on system base} \\ P^\mathrm{aux} &\leftarrow \text{auxiliary power input on system base} \end{aligned} ``` -Initialization never replaces the system-base value held in $P_{\mathrm{m}}$. +Initialization never replaces the system-base value held in $P_\mathrm{m}$. ### Internal Initialization @@ -275,7 +277,9 @@ derivatives are set to zero. Initialization first solves the gate at the configured dam head over the full $[G_V^{(0)},G_V^{(5)}]$ gate curve. If that gate lies outside the configured $[G^{\min},G^{\max}]$ interval, the corresponding response limit is expanded -to include it. The configured parameters are unchanged. +to include it. The configured parameters are unchanged. This matches +PowerWorld's default `Modify Limits and Run` treatment of initial limit +violations. If the required mechanical power exceeds the value at $G_V^{(5)}$, the gate is pinned there and an effective dam head @@ -291,12 +295,12 @@ simulation. &\leftarrow H_{\mathrm{dam}}^{\mathrm{eff}} \\ g &\leftarrow \text{gate in } [G_V^{(0)},G_V^{(5)}] \text{ satisfying} \\ - &\qquad k_{\mathrm{base}}P_{\mathrm{m}} - = A_t H\left(\sqrt{H}\,N_{\mathrm{GV}}(g) - q_{\mathrm{NL}}\right) \\ + &\qquad k_{\mathrm{base}}P_\mathrm{m} + = A_\mathrm{t} H\left(\sqrt{H}\,N_{\mathrm{GV}}(g) - q_{\mathrm{NL}}\right) \\ G_{\mathrm{resp}}^{\min} - &\leftarrow \min\!\left(G^{\min},g\right) \\ + &\leftarrow \min\!(G^{\min},g) \\ G_{\mathrm{resp}}^{\max} - &\leftarrow \max\!\left(G^{\max},g\right) \\ + &\leftarrow \max\!(G^{\max},g) \\ P_{\mathrm{GV}} &\leftarrow N_{\mathrm{GV}}(g) \\ q @@ -304,10 +308,10 @@ simulation. c &\leftarrow g \\ \omega_{\mathrm{db}} - &\leftarrow \text{deadband1}\!\left(\omega;\, -D_{\omega}, D_{\omega}\right) \\ - x_n + &\leftarrow \text{deadband1}\!(\omega;\, -D_{\omega}, D_{\omega}) \\ + x_\mathrm{n} &\leftarrow \omega_{\mathrm{db}} \\ - x_f + x_\mathrm{f} &\leftarrow 0 \\ e_f &\leftarrow 0 \\ @@ -338,42 +342,23 @@ unchanged. \left[ e_f - k_{\mathrm{base}}P^\mathrm{aux} - + x_n - + k_n\left(\omega_{\mathrm{db}} - x_n\right) + + x_\mathrm{n} + + k_\mathrm{n}(\omega_{\mathrm{db}} - x_\mathrm{n}) + R_{\mathrm{perm}}c \right] \end{aligned} ``` -## Monitorable Outputs - -Output | Units | Description | Note ----------------|--------|------------------------------|------ -`pmech` | [p.u.] | Mechanical-power output | $P_{\mathrm{m}}$ (system base) -`filter` | [p.u.] | Governor error filter output | $x_f$ (component base) -`desiredgate` | [p.u.] | Desired-gate position | $c$ (component base) -`gate` | [p.u.] | Gate position | $g$ (component base) -`flow` | [p.u.] | Turbine flow | $q$ (component base) -`head` | [p.u.] | Turbine head | $H$ (component base) - -## Testing - -- `validation()` checks construction, monitor creation, parameter validation, - signal configuration, and minimum time-constant handling. -- `initializationAndSignals()` checks initialization, base conversion, - signal publication, monitor output, and unattached-reference latching. -- `initializationDomain()` checks effective-limit and effective-head - initialization, rejection atomicity, and initialization boundaries. -- `initializationExactness()` checks that initialized steady residuals rest - at machine rounding across the gate curve. -- `residualEquations()` checks every model residual against a fixed - numerical answer key. -- `governorControl()` checks the speed deadband, the desired-gate velocity - limit, and the gate-position anti-windup. -- `turbineDynamics()` checks the gate-power curve, the water column, turbine - damping, and initialization through the nonlinear curve. -- `jacobian()` compares the dependency-tracking and Enzyme Jacobians across - the gate curve when Enzyme support is enabled. +## Monitors + +Monitor | Units | Description | Note +--------------|--------|------------------------------|----------------------- +`pmech` | [p.u.] | Mechanical-power output | $P_\mathrm{m}$ (system base) +`filter` | [p.u.] | Governor error filter output | $x_\mathrm{f}$ (component base) +`desiredgate` | [p.u.] | Desired-gate position | $c$ (component base) +`gate` | [p.u.] | Gate position | $g$ (component base) +`flow` | [p.u.] | Turbine flow | $q$ (component base) +`head` | [p.u.] | Turbine head | $H$ (component base) ## Appendix A: Backlash @@ -384,13 +369,13 @@ Input $u$, output $y$, half-play $b$, with $|u - y| \le b$. \dot{y} &= \begin{cases} - \dot{u} & |u - y| = b \text{ and } \dot{u}\left(u - y\right) > 0 \\ + \dot{u} & |u - y| = b \text{ and } \dot{u}(u - y) > 0 \\ 0 & \text{otherwise} \end{cases} \end{aligned} ``` -which can be written in terms of our smooth functions as +which can be written in terms of our smooth functions as ```math \begin{aligned} @@ -401,9 +386,9 @@ which can be written in terms of our smooth functions as \end{aligned} ``` -CommonMath defines the [`ramp`](GridKit/CommonMath.md#-ramp), -[`above`](GridKit/CommonMath.md#above), and -[`below`](GridKit/CommonMath.md#below) targets and smooth approximations. This is deferred until we permit non Hessenberg forms. Once permitted we should define: +CommonMath defines the [`ramp`](../../../../CommonMath.md#ramp), +[`above`](../../../../CommonMath.md#above), and +[`below`](../../../../CommonMath.md#below) targets and smooth approximations. This is deferred until we permit non Hessenberg forms. Once permitted we should define: ```math \begin{aligned} diff --git a/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md b/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md index e2bfc8a6e..b7ef050e0 100644 --- a/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md @@ -1,57 +1,51 @@ -# **IEEE Type 1 Speed-Governor Model (IEEEG1)** +# IEEEG1 IEEEG1 is a steam turbine-governor model with speed deadband, a governor -lead-lag, rate- and position-limited governor output, optional nonlinear +lead–lag, rate- and position-limited governor output, optional nonlinear governor gain, turbine bowl and reheat stages, and separate high-pressure and low-pressure mechanical-power outputs. -Notes: +## Notes + - Input and output powers are on the turbine-rating base when `Trate > 0`; otherwise the connected machine MVA base is used. - The dashed `dbL/dbH` speed deadband block is only for IEEEG1D. IEEEG1 uses the Type 1 no-offset `db1` block documented with CommonMath `deadband1`. -- Source governor-response settings may modify $U_o$, $U_c$, $P^{\max}$, and - $P^{\min}$ before the equations are evaluated. -- PSSE IEEEG1 source data may omit `db1`, `db2`, nonlinear-gain points, and - turbine rating; those omitted features must be documented as inactive rather - than silently dropped. ## Block Diagram -Standard model of the IEEEG1 Governor. - ![](../../../../../docs/Figures/PhasorDynamics/IEEEG1_diagram.png) Figure 1: Governor IEEEG1 model. Figure courtesy of [PowerWorld](https://www.powerworld.com/WebHelp/) ## Model Parameters -Symbol | Units | JSON | Description | Typical Value | Note ---------------------------------|----------|------------|----------------------------------------------|---------------|------ -$K$ | [p.u.] | `K` | Governor speed-control gain | 20.0 | Block name: `K` -$T_1$ | [sec] | `T1` | Governor lead-lag denominator time constant | 0.0 | Block name: `T1` -$T_2$ | [sec] | `T2` | Governor lead-lag numerator time constant | 0.0 | Block name: `T2` -$T_3$ | [sec] | `T3` | Governor output servo time constant | 0.1 | Block name: `T3` -$U_o$ | [p.u./s] | `Uo` | Maximum opening rate | 0.1 | Source label: `UO` -$U_c$ | [p.u./s] | `Uc` | Maximum closing rate | -0.1 | Source label: `UC` -$P^{\max}$ | [p.u.] | `Pmax` | Maximum governor output | 1.0 | Block name: `PMAX` -$P^{\min}$ | [p.u.] | `Pmin` | Minimum governor output | 0.0 | Block name: `PMIN` -$T_4$ | [sec] | `T4` | Turbine bowl time constant | 0.3 | State 3 in Fig. 1 -$K_1$ | [p.u.] | `K1` | High-pressure fraction from turbine bowl | 0.2 | Top output branch -$K_2$ | [p.u.] | `K2` | Low-pressure fraction from turbine bowl | 0.0 | Bottom output branch -$T_5$ | [sec] | `T5` | Reheater time constant | 5.0 | State 4 in Fig. 1 -$K_3$ | [p.u.] | `K3` | High-pressure fraction from reheater | 0.3 | Top output branch -$K_4$ | [p.u.] | `K4` | Low-pressure fraction from reheater | 0.0 | Bottom output branch -$T_6$ | [sec] | `T6` | Crossover time constant | 0.5 | State 5 in Fig. 1 -$K_5$ | [p.u.] | `K5` | High-pressure fraction from crossover | 0.5 | Top output branch -$K_6$ | [p.u.] | `K6` | Low-pressure fraction from crossover | 0.0 | Bottom output branch -$T_7$ | [sec] | `T7` | Double-reheat time constant | 0.5 | State 6 in Fig. 1 -$K_7$ | [p.u.] | `K7` | High-pressure fraction from double reheat | 0.0 | Top output branch -$K_8$ | [p.u.] | `K8` | Low-pressure fraction from double reheat | 0.0 | Bottom output branch -$D_{\omega}$ | [p.u.] | `db1` | Type 1 speed deadband threshold | 0.0 | Block name: `db1`; uses CommonMath `deadband1` -$\epsilon$ | [p.u.] | `Eps` | Nonlinear gain smoothing/curve tolerance | 0.0 | Source nonlinear gain setting -$D_{\mathrm{gv}}$ | [p.u.] | `db2` | Governor-output backlash/deadband width | 0.0 | Block name: `db2`; nonzero support must be explicit -$P^{\mathrm{rate}}$ | [MW] | `Trate` | Optional turbine-rating power base | 0.0 | `Trate > 0` defines the governor base +Symbol | Units | JSON | Description | Typical Value | Note +--------------------|----------|---------|---------------------------------------------|---------------|-------------------------------------- +$K$ | [p.u.] | `K` | Governor speed-control gain | 20.0 | +$T_1$ | [s] | `T1` | Governor lead–lag denominator time constant | 0.0 | +$T_2$ | [s] | `T2` | Governor lead–lag numerator time constant | 0.0 | +$T_3$ | [s] | `T3` | Governor output servo time constant | 0.1 | +$U_\mathrm{o}$ | [p.u./s] | `Uo` | Maximum opening rate | 0.1 | Source label: `UO` +$U_\mathrm{c}$ | [p.u./s] | `Uc` | Maximum closing rate | -0.1 | Source label: `UC` +$P^{\max}$ | [p.u.] | `Pmax` | Maximum governor output | 1.0 | Source label: `PMAX` +$P^{\min}$ | [p.u.] | `Pmin` | Minimum governor output | 0.0 | Source label: `PMIN` +$T_4$ | [s] | `T4` | Turbine bowl time constant | 0.3 | State 3 in Fig. 1 +$K_1$ | [p.u.] | `K1` | High-pressure fraction from turbine bowl | 0.2 | Top output branch +$K_2$ | [p.u.] | `K2` | Low-pressure fraction from turbine bowl | 0.0 | Bottom output branch +$T_5$ | [s] | `T5` | Reheater time constant | 5.0 | State 4 in Fig. 1 +$K_3$ | [p.u.] | `K3` | High-pressure fraction from reheater | 0.3 | Top output branch +$K_4$ | [p.u.] | `K4` | Low-pressure fraction from reheater | 0.0 | Bottom output branch +$T_6$ | [s] | `T6` | Crossover time constant | 0.5 | State 5 in Fig. 1 +$K_5$ | [p.u.] | `K5` | High-pressure fraction from crossover | 0.5 | Top output branch +$K_6$ | [p.u.] | `K6` | Low-pressure fraction from crossover | 0.0 | Bottom output branch +$T_7$ | [s] | `T7` | Double-reheat time constant | 0.5 | State 6 in Fig. 1 +$K_7$ | [p.u.] | `K7` | High-pressure fraction from double reheat | 0.0 | Top output branch +$K_8$ | [p.u.] | `K8` | Low-pressure fraction from double reheat | 0.0 | Bottom output branch +$D_{\omega}$ | [p.u.] | `db1` | Type 1 speed deadband threshold | 0.0 | uses CommonMath `deadband1` +$\epsilon$ | [p.u.] | `Eps` | Nonlinear gain smoothing/curve tolerance | 0.0 | Source nonlinear gain setting +$D_{\mathrm{gv}}$ | [p.u.] | `db2` | Governor-output backlash/deadband width | 0.0 | nonzero support must be explicit +$P^{\mathrm{rate}}$ | [MW] | `Trate` | Optional turbine-rating power base | 0.0 | `Trate > 0` defines the governor base The optional nonlinear governor gain curve is represented by source points: @@ -62,15 +56,13 @@ $P_{\mathrm{GV}}^{(k)}$ | [p.u.] | `Pgv1`-`Pgv6` | Governor-output curve ### Parameter Validation -Invalid IEEEG1 parameter sets are rejected by the following checks. If source -governor-response settings adjust limits, apply these checks to the effective -values used by the equations. +A valid IEEEG1 parameter set must satisfy the following conditions: ```math \begin{aligned} &T_1,T_2,T_3,T_4,T_5,T_6,T_7 \ge 0,\quad T_3>0 \\ &T_1 > 0\quad\text{or}\quad(T_1 = 0\ \text{and}\ T_2 = 0) \\ - &U_c < 0 < U_o,\quad P^{\min}\le P^{\max} \\ + &U_\mathrm{c} < 0 < U_\mathrm{o},\quad P^{\min}\le P^{\max} \\ &D_{\omega}\ge 0,\quad D_{\mathrm{gv}}\ge 0,\quad P^{\mathrm{rate}}\ge 0 \\ &G_V^{(1)} < G_V^{(2)} < \cdots < G_V^{(6)} \\ &0 \le P_{\mathrm{GV}}^{(1)} \le P_{\mathrm{GV}}^{(2)} \le \cdots \le P_{\mathrm{GV}}^{(6)} @@ -93,17 +85,24 @@ The governor component base and nonlinear governor-output curve are: &= P_{\mathrm{GV}}^{(1)} + \sum_{k=1}^{5} - \text{linseg}\!\left( + \text{linseg}\!( x;\, G_V^{(k)},\, G_V^{(k+1)},\, P_{\mathrm{GV}}^{(k+1)} - P_{\mathrm{GV}}^{(k)} - \right) + ) \end{aligned} ``` -CommonMath defines the [linear segment](../../../../CommonMath.md#derived-functions) -helper used by $N_{\mathrm{GV}}$. +## Model Ports + +Name | Port | Init | Description +-------------|--------|------|------------ +`speed` | Input | TBD | Machine speed deviation +`pref` | Input | TBD | Governor reference +`paux` | Input | TBD | Auxiliary power input +`pmech_hp` | Output | TBD | High-pressure mechanical-power output +`pmech_lp` | Output | TBD | Low-pressure mechanical-power output ## Model Variables @@ -111,26 +110,26 @@ helper used by $N_{\mathrm{GV}}$. #### Differential -Symbol | Units | Description | Note -------------------------|--------|-------------------------------------|------ -$P_{\mathrm{GV}}$ | [p.u.] | Governor output | State 1 in Fig. 1 -$x_{\mathrm{ll}}$ | [p.u.] | Governor lead-lag state | State 2 in Fig. 1 -$x_4$ | [p.u.] | Turbine bowl state | State 3 in Fig. 1; denominator $T_4$ -$x_5$ | [p.u.] | Reheater state | State 4 in Fig. 1; denominator $T_5$ -$x_6$ | [p.u.] | Crossover state | State 5 in Fig. 1; denominator $T_6$ -$x_7$ | [p.u.] | Double-reheat state | State 6 in Fig. 1; denominator $T_7$ +Symbol | Units | Description | Note +------------------|--------|-------------------------|------------------------------------- +$P_{\mathrm{GV}}$ | [p.u.] | Governor output | State 1 in Fig. 1 +$x_{\mathrm{LL}}$ | [p.u.] | Governor lead–lag state | State 2 in Fig. 1 +$x_4$ | [p.u.] | Turbine bowl state | State 3 in Fig. 1; denominator $T_4$ +$x_5$ | [p.u.] | Reheater state | State 4 in Fig. 1; denominator $T_5$ +$x_6$ | [p.u.] | Crossover state | State 5 in Fig. 1; denominator $T_6$ +$x_7$ | [p.u.] | Double-reheat state | State 6 in Fig. 1; denominator $T_7$ #### Algebraic -Symbol | Units | Description | Note ---------------------------------|----------|-------------------------------------|------ -$\omega_{\mathrm{db}}$ | [p.u.] | Deadbanded speed deviation | Defined by CommonMath `deadband1` -$y_{\omega}$ | [p.u.] | Lead-lag-conditioned speed signal | Output of $K(1+sT_2)/(1+sT_1)$ -$e_G$ | [p.u.] | Governor command error | Sum of references minus speed and output feedback -$r_G$ | [p.u./s] | Rate-limited governor derivative target | Limited by $U_c$ and $U_o$ -$P_{\mathrm{GV}}^{\mathrm{nl}}$ | [p.u.] | Nonlinear governor gain output | Output of `db2`/curve branch -$P_m^{\mathrm{HP}}$ | [p.u.] | High-pressure mechanical-power output | Source label: `PMECH_HP` -$P_m^{\mathrm{LP}}$ | [p.u.] | Low-pressure mechanical-power output | Source label: `PMECH_LP` +Symbol | Units | Description | Note +--------------------------------|----------|-----------------------------------------|-------------------------------------------------- +$\omega_{\mathrm{db}}$ | [p.u.] | Deadbanded speed deviation | Defined by CommonMath `deadband1` +$y_{\omega}$ | [p.u.] | Lead–lag-conditioned speed signal | Output of $K(1+sT_2)/(1+sT_1)$ +$e_G$ | [p.u.] | Governor command error | Sum of references minus speed and output feedback +$r_G$ | [p.u./s] | Rate-limited governor derivative target | Limited by $U_\mathrm{c}$ and $U_\mathrm{o}$ +$P_{\mathrm{GV}}^{\mathrm{nl}}$ | [p.u.] | Nonlinear governor gain output | Output of `db2`/curve branch +$P_\mathrm{m}^{\mathrm{HP}}$ | [p.u.] | High-pressure mechanical-power output | Source label: `PMECH_HP` +$P_\mathrm{m}^{\mathrm{LP}}$ | [p.u.] | Low-pressure mechanical-power output | Source label: `PMECH_LP` ### External Variables @@ -148,19 +147,23 @@ $P_{\mathrm{aux}}$ | [p.u.] | Auxiliary power input | Sour ## Model Equations -### Differential Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband1`](../../../../CommonMath.md#type-i-deadband), [`deadband2`](../../../../CommonMath.md#type-ii-deadband), [`linseg`](../../../../CommonMath.md#linear-segment). + +### Internal Equations + +#### Differential ```math \begin{aligned} - 0 &= -T_1\dot x_{\mathrm{ll}} - x_{\mathrm{ll}} + K\omega_{\mathrm{db}} \\ + 0 &= -T_1\dot x_{\mathrm{LL}} - x_{\mathrm{LL}} + K\omega_{\mathrm{db}} \\ 0 &= -\dot P_{\mathrm{GV}} - + \text{antiwindup}\!\left( + + \text{antiwindup}\!( P_{\mathrm{GV}}, - r_G, + r_G; P^{\min}, P^{\max} - \right) \\ + ) \\ 0 &= -T_4\dot x_4 - x_4 + P_{\mathrm{GV}}^{\mathrm{nl}} \\ 0 &= -T_5\dot x_5 - x_5 + x_4 \\ 0 &= -T_6\dot x_6 - x_6 + x_5 \\ @@ -168,78 +171,76 @@ $P_{\mathrm{aux}}$ | [p.u.] | Auxiliary power input | Sour \end{aligned} ``` -CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations +#### Algebraic ```math \begin{aligned} - 0 &= -\omega_{\mathrm{db}} + \text{deadband1}(\omega,\ -D_{\omega},\ D_{\omega}) \\ + 0 &= -\omega_{\mathrm{db}} + \text{deadband1}(\omega;\ -D_{\omega},\ D_{\omega}) \\ 0 &= -y_{\omega} + \begin{cases} K\omega_{\mathrm{db}}, & T_1 = T_2 = 0 \\ - x_{\mathrm{ll}} + \dfrac{T_2}{T_1}\left(K\omega_{\mathrm{db}}-x_{\mathrm{ll}}\right), & T_1 > 0 + x_{\mathrm{LL}} + \dfrac{T_2}{T_1}(K\omega_{\mathrm{db}}-x_{\mathrm{LL}}), & T_1 > 0 \end{cases} \\ 0 &= -e_G + P_{\mathrm{ref}} + P_{\mathrm{aux}} - y_{\omega} - P_{\mathrm{GV}} \\ - 0 &= -r_G + \text{clamp}\!\left(\dfrac{e_G}{T_3}, U_c, U_o\right) \\ - 0 &= -P_{\mathrm{GV}}^{\mathrm{nl}} + N_{\mathrm{GV}}\!\left(\text{deadband2}(P_{\mathrm{GV}}, -D_{\mathrm{gv}}, D_{\mathrm{gv}})\right) \\ - 0 &= -P_m^{\mathrm{HP}} + K_1x_4 + K_3x_5 + K_5x_6 + K_7x_7 \\ - 0 &= -P_m^{\mathrm{LP}} + K_2x_4 + K_4x_5 + K_6x_6 + K_8x_7 + 0 &= -r_G + \text{clamp}\!\left(\dfrac{e_G}{T_3}; U_\mathrm{c}, U_\mathrm{o}\right) \\ + 0 &= -P_{\mathrm{GV}}^{\mathrm{nl}} + N_{\mathrm{GV}}\!(\text{deadband2}(P_{\mathrm{GV}}; -D_{\mathrm{gv}}, D_{\mathrm{gv}})) \\ + 0 &= -P_\mathrm{m}^{\mathrm{HP}} + K_1x_4 + K_3x_5 + K_5x_6 + K_7x_7 \\ + 0 &= -P_\mathrm{m}^{\mathrm{LP}} + K_2x_4 + K_4x_5 + K_6x_6 + K_8x_7 \end{aligned} ``` -CommonMath defines helper targets and smooth approximations for -[deadband1, deadband2, clamp, and linseg](../../../../CommonMath.md#derived-functions). -When $T_1=T_2=0$, the governor lead-lag block is bypassed so +When $T_1=T_2=0$, the governor lead–lag block is bypassed so $y_{\omega}=K\omega_{\mathrm{db}}$. +### External Equations + +None. + ## Initialization -Initialization is performed by evaluating the steady-state residuals in -dependency order. Let subscript $0$ denote initial values and set all internal -derivatives to zero. For a standard power-flow start: +For a power-flow start, require $\omega=0$ and initialize all internal derivatives to zero: ```math \begin{aligned} - \omega_0 &= 0 \\ - P_{\mathrm{aux},0} &= 0 \\ - \omega_{\mathrm{db},0} &= \text{deadband1}(0,\ -D_{\omega},\ D_{\omega}) \\ - x_{\mathrm{ll},0} &= K\omega_{\mathrm{db},0} \\ - y_{\omega,0} &= x_{\mathrm{ll},0} + P_{\mathrm{aux}} &\leftarrow 0,\quad \text{if omitted} \\ + \omega_{\mathrm{db}} &\leftarrow \text{deadband1}(0;\ -D_{\omega},\ D_{\omega}) \\ + x_{\mathrm{LL}} &\leftarrow K\omega_{\mathrm{db}} \\ + y_{\omega} &\leftarrow x_{\mathrm{LL}} \end{aligned} ``` -Given initialized high- and low-pressure mechanical powers, solve the turbine -chain by choosing $P_{\mathrm{GV},0}$ so that the turbine fractions reproduce -the connected machine operating point: +Solve for $P_{\mathrm{GV}}$ and $P_{\mathrm{GV}}^{\mathrm{nl}}$ using the supplied +high- and low-pressure mechanical powers: + +```math +\begin{aligned} + 0 &= -P_{\mathrm{GV}}^{\mathrm{nl}} + + N_{\mathrm{GV}}\!(\text{deadband2}(P_{\mathrm{GV}}; -D_{\mathrm{gv}}, D_{\mathrm{gv}})) \\ + 0 &= -P_{\mathrm{m}}^{\mathrm{HP}} + (K_1+K_3+K_5+K_7)P_{\mathrm{GV}}^{\mathrm{nl}} \\ + 0 &= -P_{\mathrm{m}}^{\mathrm{LP}} + (K_2+K_4+K_6+K_8)P_{\mathrm{GV}}^{\mathrm{nl}} +\end{aligned} +``` ```math \begin{aligned} - P_{\mathrm{GV},0}^{\mathrm{nl}} - &= N_{\mathrm{GV}}\!\left(\text{deadband2}(P_{\mathrm{GV},0}, -D_{\mathrm{gv}}, D_{\mathrm{gv}})\right) \\ - x_{4,0}=x_{5,0}=x_{6,0}=x_{7,0} &= P_{\mathrm{GV},0}^{\mathrm{nl}} \\ - P_{m,0}^{\mathrm{HP}} &= (K_1+K_3+K_5+K_7)P_{\mathrm{GV},0}^{\mathrm{nl}} \\ - P_{m,0}^{\mathrm{LP}} &= (K_2+K_4+K_6+K_8)P_{\mathrm{GV},0}^{\mathrm{nl}} \\ - P_{\mathrm{ref},0} &= P_{\mathrm{GV},0} + y_{\omega,0} - P_{\mathrm{aux},0} + x_4,x_5,x_6,x_7 &\leftarrow P_{\mathrm{GV}}^{\mathrm{nl}} \\ + P_{\mathrm{ref}} &\leftarrow P_{\mathrm{GV}} + y_{\omega} - P_{\mathrm{aux}} \end{aligned} ``` -This closed-form start requires the effective governor output to lie inside +Initialization requires the effective governor output to lie inside $P^{\min}$ and $P^{\max}$ and the opening/closing rate limits to be inactive. -Starts where governor response limits fix the limits to the initial condition -must document those effective limits before applying the residuals. - -## Model Outputs - -Output | Units | Description | Note -----------------|--------|-------------------------------------|------ -`pmech_hp` | [p.u.] | High-pressure mechanical-power output | $P_m^{\mathrm{HP}}$ -`pmech_lp` | [p.u.] | Low-pressure mechanical-power output | $P_m^{\mathrm{LP}}$ -`pgv` | [p.u.] | Governor output | State 1 -`leadlag` | [p.u.] | Governor lead-lag state | State 2 -`bowl` | [p.u.] | Turbine bowl state | State 3 -`reheater` | [p.u.] | Reheater state | State 4 -`crossover` | [p.u.] | Crossover state | State 5 -`double_reheat` | [p.u.] | Double-reheat state | State 6 + +## Monitors + +Monitor | Units | Description | Note +----------------|--------|---------------------------------------|-------------------- +`pmech_hp` | [p.u.] | High-pressure mechanical-power output | $P_\mathrm{m}^{\mathrm{HP}}$ +`pmech_lp` | [p.u.] | Low-pressure mechanical-power output | $P_\mathrm{m}^{\mathrm{LP}}$ +`pgv` | [p.u.] | Governor output | State 1 +`leadlag` | [p.u.] | Governor lead–lag state | State 2 +`bowl` | [p.u.] | Turbine bowl state | State 3 +`reheater` | [p.u.] | Reheater state | State 4 +`crossover` | [p.u.] | Crossover state | State 5 +`double_reheat` | [p.u.] | Double-reheat state | State 6 diff --git a/GridKit/Model/PhasorDynamics/Governor/README.md b/GridKit/Model/PhasorDynamics/Governor/README.md index 95a1b2361..126113696 100644 --- a/GridKit/Model/PhasorDynamics/Governor/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/README.md @@ -1,15 +1,11 @@ -# Governor Model +# Governor Models -## Introduction - -A governor models the control system that regulates the output power of a machine. +Governors regulate machine mechanical power. ## Types -There are a few standard Governor models - -- Turbine Governor (See [TGOV1](Tgov1/README.md)) -- Gas Turbine Governor (See [GASTPTI](GASTPTI/README.md)) -- Hydro Turbine Governor (See [HYGOV](HYGOV/README.md)) -- IEEE Type G1 Turbine Governor (See [IEEEG1](IEEEG1/README.md)) -- General Governor (See [GGOV1](GGOV1/README.md)) +- [GASTPTI](GASTPTI/README.md): Gas turbine-governor +- [GGOV1](GGOV1/README.md): General governor-turbine +- [HYGOV](HYGOV/README.md): Hydro turbine-governor +- [IEEEG1](IEEEG1/README.md): IEEE Type 1 speed-governor +- [TGOV1](Tgov1/README.md): Steam turbine-governor diff --git a/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md b/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md index f18a5d2e5..a9680d004 100644 --- a/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md @@ -1,8 +1,8 @@ -# **Steam Turbine-Governor Model (TGOV1)** +# TGOV1 -## Block Diagram +Steam turbine-governor model. -Standard model of the stream turbine +## Block Diagram ![](../../../../../docs/Figures/TGOV1.JPG) @@ -10,21 +10,24 @@ Figure 1: Governor TGOV1 model. Figure courtesy of [PowerWorld](https://www.powe ## Model Parameters -Symbol | Units | Description | Typical Value | Note -------------|--------|-----------------------------------|---------------| ------ -$T_{\mathrm{rate}}$ | [MVA] | Governor component power base | 100.0 | -$R$ | [p.u.] | Permanent droop | 0.05 | -$T_1$ | [sec] | Steam-bowl time constant | 0.5 | -$T_2$ | [sec] | Turbine numerator time constant | 2.5 | -$T_3$ | [sec] | Reheater time constant | 7.5 | -$P_v^{\max}$ | [p.u.] | Maximum valve position | 1 | -$P_v^{\min}$ | [p.u.] | Minimum valve position | 0 | -$D_t$ | [p.u.] | Turbine damping coefficient | 0 | +Symbol | Units | JSON | Description | Typical Value | Note +--------------------|--------|---------|---------------------------------|---------------|----- +$T_{\mathrm{rate}}$ | [MVA] | `Trate` | Governor component power base | 100.0 | +$R$ | [p.u.] | `R` | Permanent droop | 0.05 | +$T_1$ | [s] | `T1` | Steam-bowl time constant | 0.5 | +$T_2$ | [s] | `T2` | Turbine numerator time constant | 2.5 | +$T_3$ | [s] | `T3` | Reheater time constant | 7.5 | +$P_\mathrm{v}^{\max}$ | [p.u.] | `Pvmax` | Maximum valve position | 1 | +$P_\mathrm{v}^{\min}$ | [p.u.] | `Pvmin` | Minimum valve position | 0 | +$D_\mathrm{t}$ | [p.u.] | `Dt` | Turbine damping coefficient | 0 | ### Parameter Validation -The component and system power bases must be positive, $R$ must be nonzero, -and $P_v^{\min}\le P_v^{\max}$. +A valid TGOV1 parameter set must satisfy the following conditions: + +```math +T_\mathrm{rate},S_\mathrm{sys}>0,\qquad R\ne0,\qquad P_\mathrm{v}^{\min}\le P_\mathrm{v}^{\max} +``` Set $T_{\mathrm{rate}}$ equal to the connected machine MVA base. A zero component power base is not supported. @@ -37,7 +40,7 @@ raised to that floor in place, so every equation below uses the raised value: ```math \begin{aligned} T_x - &\leftarrow \max\!\left(T_x,\epsilon_T\right), + &\leftarrow \max\!(T_x,\epsilon_T), \quad x\in\{1,3\} \end{aligned} ``` @@ -56,16 +59,16 @@ Name | Port | Init | Description #### Differential -Symbol | Units | Description | Note -----------|--------|-----------------------------------|------- -$P_t$ | [p.u.] | Turbine-block output | Component base -$P_v$ | [p.u.] | Valve position | Component base +Symbol | Units | Description | Note +-------|--------|----------------------|--------------- +$P_\mathrm{v}$ | [p.u.] | Valve position | Component base +$P_\mathrm{t}$ | [p.u.] | Turbine-block output | Component base #### Algebraic Symbol | Units | Description | Note ----------------|--------|-----------------------------------|------- -$P_m$ | [p.u.] | Mechanical-power output | System base; read by the machine model +$P_\mathrm{m}$ | [p.u.] | Mechanical-power output | System base; read by the machine model ### External Variables @@ -83,55 +86,53 @@ $P_\mathrm{ref}$ | [p.u.] | Governor reference | Component base; o ## Model Equations +Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup). + For readability, define: ```math -g_v=-P_v+\dfrac{P_\mathrm{ref}-\omega}{R}. +g_v=-P_\mathrm{v}+\dfrac{P_\mathrm{ref}-\omega}{R} ``` -### Differential Equations +### Internal Equations -The TGOV1 differential equations, as derived from the model diagram, are +#### Differential ```math \begin{aligned} - 0 &= -\dot P_v + 0 &= -\dot P_\mathrm{v} + \dfrac{1}{T_1}\text{antiwindup} - \left(P_v,g_v;P_v^{\min},P_v^{\max}\right) \\ - 0 &= -\dot P_t-\dfrac{P_t-P_v-T_2\dot P_v}{T_3}. + (P_\mathrm{v},g_v;P_\mathrm{v}^{\min},P_\mathrm{v}^{\max}) \\ + 0 &= -\dot P_\mathrm{t}-\dfrac{P_\mathrm{t}-P_\mathrm{v}-T_2\dot P_\mathrm{v}}{T_3} \end{aligned} ``` -CommonMath defines the [Antiwindup](../../../../CommonMath.md#antiwindup) -target and smooth approximation. - -### Algebraic Equations - -The mechanical-power output is given by +#### Algebraic ```math -0=-\dfrac{S_\mathrm{sys}}{T_\mathrm{rate}}P_m - +P_t-D_t\omega. +0=-\dfrac{S_\mathrm{sys}}{T_\mathrm{rate}}P_\mathrm{m} + +P_\mathrm{t}-D_\mathrm{t}\omega ``` +### External Equations + +None. + ## Initialization -TGOV1 preserves the machine-provided $P_{m,0}$ and initializes the steady -state in dependency order: +The machine provides $P_\mathrm{m}$ on system base: ```math \begin{aligned} - P_{m,0}^{\mathrm{TGOV1}} - &\leftarrow \dfrac{S_\mathrm{sys}}{T_\mathrm{rate}}P_{m,0} \\ - P_{v,0} - &\leftarrow P_{m,0}^{\mathrm{TGOV1}}+D_t\omega_0 \\ - P_{t,0} - &\leftarrow P_{v,0} \\ - P_{\mathrm{ref},0} - &\leftarrow \omega_0+RP_{v,0} \\ - \dot P_{v,0},\dot P_{t,0} - &\leftarrow 0. +P_\mathrm{v} &\leftarrow \dfrac{S_\mathrm{sys}}{T_\mathrm{rate}}P_\mathrm{m}+D_\mathrm{t}\omega \\ +P_\mathrm{t} &\leftarrow P_\mathrm{v} \\ +P_\mathrm{ref} &\leftarrow \omega+RP_\mathrm{v} \\ +\dot P_\mathrm{v},\dot P_\mathrm{t} &\leftarrow 0 \end{aligned} ``` -Initialization rejects $P_{v,0}$ outside the configured valve limits. +Initialization rejects $P_\mathrm{v}$ outside the configured valve limits. + +## Monitors + +None. diff --git a/GridKit/Model/PhasorDynamics/INPUT_FORMAT.md b/GridKit/Model/PhasorDynamics/INPUT_FORMAT.md index fe3909180..336761b4f 100644 --- a/GridKit/Model/PhasorDynamics/INPUT_FORMAT.md +++ b/GridKit/Model/PhasorDynamics/INPUT_FORMAT.md @@ -16,7 +16,7 @@ also be encoded as [MessagePack](https://msgpack.org). implementation. - Flexible to handle various kinds of power system dynamics models - including phasor dynamics (PD), electromechanical transients (EMT) + including phasor dynamics (PD), electromagnetic transients (EMT) and hybrid models of the two. - Conformity, as much as possible, to the style and formulations of diff --git a/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md b/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md index ec5a8eb38..9a6eddfae 100644 --- a/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md +++ b/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md @@ -5,10 +5,10 @@ adds their current contribution to the connected bus residual. ## Model Parameters -Symbol | Units | JSON | Description --------|--------|------|------------ -$R$ | [p.u.] | `R` | Load resistance -$X$ | [p.u.] | `X` | Load reactance +Symbol | Units | JSON | Description | Typical Value | Note +-------|--------|------|-----------------|---------------|----- +$R$ | [p.u.] | `R` | Load resistance | | +$X$ | [p.u.] | `X` | Load reactance | | ### Parameter Validation @@ -18,11 +18,17 @@ None. ```math \begin{aligned} -G &= \frac{R}{R^2 + X^2} \\ -B &= -\frac{X}{R^2 + X^2} +G &= \dfrac{R}{R^2 + X^2} \\ +B &= -\dfrac{X}{R^2 + X^2} \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +------|------|-------|------------ +`bus` | Bus | Known | Connected bus that owns terminal voltage variables and current-balance residuals + ## Model Variables ### Internal Variables @@ -51,19 +57,15 @@ Symbol | Units | Description | Note $V_r$ | [p.u.] | Terminal voltage, real component | Owned by connected bus $V_i$ | [p.u.] | Terminal voltage, imaginary component | Owned by connected bus -## Wiring - -Port | Type | Description -------|------|------------ -`bus` | Bus | Connected bus that owns terminal voltage variables and current-balance residuals - ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential None. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -72,15 +74,23 @@ None. \end{aligned} ``` +### External Equations + +```math +\begin{aligned} +I_r^{\mathrm{bus}} &\leftarrow I_r^{\mathrm{bus}} + I_r \\ +I_i^{\mathrm{bus}} &\leftarrow I_i^{\mathrm{bus}} + I_i +\end{aligned} +``` + ## Initialization -Initialization solves the algebraic current states from the connected bus -voltage. Let $V_{r0}$ and $V_{i0}$ be the initialized bus voltage components. +The initial bus voltage determines the terminal currents: ```math \begin{aligned} -I_r &= -(G V_{r0} - B V_{i0}) \\ -I_i &= -(B V_{r0} + G V_{i0}) +I_r &\leftarrow -G V_r + B V_i \\ +I_i &\leftarrow -B V_r - G V_i \end{aligned} ``` @@ -88,7 +98,7 @@ The derivative vector entries initialize to zero. ## Monitors -Name | Units | Description | Note ------|--------|----------------------------------------------|------ +Monitor | Units | Description | Note +--------|--------|----------------------------------------------|------ `p` | [p.u.] | Active power at the connected bus terminal | Positive for injection into the connected bus `q` | [p.u.] | Reactive power at the connected bus terminal | Positive for injection into the connected bus diff --git a/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md b/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md index 948f8807d..ee406c9ca 100644 --- a/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md +++ b/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md @@ -6,12 +6,12 @@ contribution to the connected bus residual. ## Model Parameters -Symbol | Units | JSON | Description | Typical Value -----------------|--------|----------|--------------------------------|-------------- -$P_\text{nom}$ | [p.u.] | `Pnom` | Nominal consumed real power | 0.0 -$Q_\text{nom}$ | [p.u.] | `Qnom` | Nominal consumed reactive power | 0.0 -$\alpha_I$ | [-] | `alphaI` | Constant current load fraction | 0.0 -$\alpha_P$ | [-] | `alphaP` | Constant power load fraction | 0.0 +Symbol | Units | JSON | Description | Typical Value | Note +-----------------|--------|----------|---------------------------------|---------------|----- +$P_\mathrm{nom}$ | [p.u.] | `Pnom` | Nominal consumed real power | 0.0 | +$Q_\mathrm{nom}$ | [p.u.] | `Qnom` | Nominal consumed reactive power | 0.0 | +$\alpha_I$ | [-] | `alphaI` | Constant current load fraction | 0.0 | +$\alpha_P$ | [-] | `alphaP` | Constant power load fraction | 0.0 | ### Parameter Validation @@ -19,16 +19,22 @@ None. ### Model Derived Parameters -$V_\text{nom}$ is the initial voltage magnitude of the respective bus. +$V_\mathrm{nom}$ is the initial voltage magnitude of the respective bus. ```math \begin{aligned} -G &= \frac{P_\text{nom}}{V_\text{nom}^2} \\ -B &= \frac{Q_\text{nom}}{V_\text{nom}^2} \\ +G &= \dfrac{P_\mathrm{nom}}{V_\mathrm{nom}^2} \\ +B &= -\dfrac{Q_\mathrm{nom}}{V_\mathrm{nom}^2} \\ \alpha_Z &= 1 - \alpha_I - \alpha_P \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +------|------|-------|------------ +`bus` | Bus | Known | Connected bus that owns terminal voltage variables and current-balance residuals + ## Model Variables ### Internal Variables @@ -57,45 +63,50 @@ Symbol | Units | Description | Note $V_r$ | [p.u.] | Terminal voltage, real component | Owned by connected bus $V_i$ | [p.u.] | Terminal voltage, imaginary component | Owned by connected bus -## Wiring - -Port | Type | Description -------|------|------------ -`bus` | Bus | Connected bus that owns terminal voltage variables and current-balance residuals - ## Model Equations Let $V = \sqrt{V_r^2 + V_i^2}$. -### Differential Equations +### Internal Equations + +#### Differential None. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} -0 &= I_r + (G V_r + B V_i) +0 &= I_r + (G V_r - B V_i) \left[ \alpha_Z -+ \alpha_I \frac{V_\text{nom}}{V} -+ \alpha_P \frac{V_\text{nom}^2}{V^2} ++ \alpha_I \dfrac{V_\mathrm{nom}}{V} ++ \alpha_P \dfrac{V_\mathrm{nom}^2}{V^2} \right] \\ -0 &= I_i + (G V_i - B V_r) +0 &= I_i + (G V_i + B V_r) \left[ \alpha_Z -+ \alpha_I \frac{V_\text{nom}}{V} -+ \alpha_P \frac{V_\text{nom}^2}{V^2} ++ \alpha_I \dfrac{V_\mathrm{nom}}{V} ++ \alpha_P \dfrac{V_\mathrm{nom}^2}{V^2} \right] \end{aligned} ``` +### External Equations + +```math +\begin{aligned} +I_r^{\mathrm{bus}} &\leftarrow I_r^{\mathrm{bus}} + I_r \\ +I_i^{\mathrm{bus}} &\leftarrow I_i^{\mathrm{bus}} + I_i +\end{aligned} +``` + ## Initialization ```math \begin{aligned} - I_r &\leftarrow -G V_{r} - B V_{i} \\ - I_i &\leftarrow -G V_{i} + B V_{r} + I_r &\leftarrow -G V_r + B V_i \\ + I_i &\leftarrow -G V_i - B V_r \end{aligned} ``` @@ -103,8 +114,8 @@ The derivative vector entries initialize to zero. ## Monitors -Name | Units | Description | Note ------|--------|----------------------------------------------|------ +Monitor | Units | Description | Note +--------|--------|----------------------------------------------|------ `ir` | [p.u.] | Terminal current, real component | Added to connected bus residual `ii` | [p.u.] | Terminal current, imaginary component | Added to connected bus residual `im` | [p.u.] | Terminal current magnitude | diff --git a/GridKit/Model/PhasorDynamics/Load/README.md b/GridKit/Model/PhasorDynamics/Load/README.md index c60bac5f0..7be383dc0 100644 --- a/GridKit/Model/PhasorDynamics/Load/README.md +++ b/GridKit/Model/PhasorDynamics/Load/README.md @@ -1,13 +1,8 @@ # Load Models -## Introduction - -Load models represent power consumed by devices connected to the phasor dynamics -network. +Loads represent power consumed by devices connected to the network. ## Types -The GridKit load documentation includes: - -- Constant impedance load model (See [LoadZ](LoadZ/README.md)) -- ZIP load model (See [LoadZIP](LoadZIP/README.md)) +- [LoadZ](LoadZ/README.md): Constant impedance +- [LoadZIP](LoadZIP/README.md): Constant impedance, current, and power fractions diff --git a/GridKit/Model/PhasorDynamics/README.md b/GridKit/Model/PhasorDynamics/README.md index 237d024f1..b94075bae 100644 --- a/GridKit/Model/PhasorDynamics/README.md +++ b/GridKit/Model/PhasorDynamics/README.md @@ -1,7 +1,7 @@ # Phasor dynamics This directory contains an implementation of a system model using phasor -dynamics. +dynamics. ## Modeling checklist @@ -12,7 +12,7 @@ files: - `MyModel.hpp`: Component model declaration. - `MyModelData.hpp`: Definitions of model data including model parameters, model connection ports and model outputs (monitored - variables). + variables). - `MyModelDependencyTracking.cpp`: Compilation unit for Jacobian evaluation using dependency tracking data type (a.k.a tapeless automatic differentiation). @@ -27,26 +27,41 @@ compilation and testing. We recommend developers follow these steps when adding new component models: 1. Create a subdirectory within appropriate model family directory. 2. Create a README file in markdown format that contains all information - needed to implement the model. This should include: - 1. List of model parameters in a table format. - 2. List of _derived_ model parameters with mathematical expression - describing how they are obtained from instantiation parameters. - 3. Model internal variables. Use separate tables for differential and - algebraic variables. - 4. Model external variables (always algebraic in phasor dynamics). - 5. Model differential and algebraic equations (in separate subsections). - 6. Model initialization procedure with equations in order in which - initialization computations are performed. - 7. List of model outputs with equations for computing those outputs - where applicable. + needed to implement the model. Model READMEs use the following section + order. + 1. Model title and a one- or two-sentence purpose + 2. `Notes` (optional) + 3. `Block Diagram` (optional) + 4. `Model Parameters` + - `Parameter Validation` + - `Model Derived Parameters` + 5. `Model Ports` + 6. `Model Variables` + - `Internal Variables` + - `Differential` + - `Algebraic` + - `External Variables` + - `Differential` + - `Algebraic` + 7. `Model Equations` + - `Internal Equations` + - `Differential` + - `Algebraic` + - `External Equations` + 8. `Initialization` + - `Input Initialization` (when applicable) + - `Internal Initialization` (when applicable) + - `Output Initialization` (when applicable) + 9. `Monitors` + 10. `Testing` (optional) 3. Create all six `MyModel*.*pp` implementation files and `CMakeLists.txt` file, which specifies build requirements (files to compile, files to include, libraries to link and location to install to). Ensure the code builds correctly. - You may want to start with a "dummy" implementation first to make sure the build and installation works correctly before proceeding to the - implementation. -4. Create unit tests in `tests/UnitTesting/PhasorDynamics` directory. The + implementation. +4. Create unit tests in `tests/UnitTests/PhasorDynamics` directory. The implementation consists of `MyModelTests.hpp` with implementation of individual unit tests, the test driver in `runMyModelTests.cpp`, and `CMakeLists.txt` with build and installation configuration of tests. Unit @@ -64,14 +79,14 @@ We recommend developers follow these steps when adding new component models: 5. Once model is tested, add it to the system composer. This requires following steps: 1. Add header file `MyModel.hpp` to `ComponentLibrary.hpp`, so that `MyModel` declaration is visible to the `SystemModel` class. - 2. Modify `SystemModelJsonParser.hpp` so that `MyModel` is recognized by the + 2. Modify `SystemModelDataJSONParser.hpp` so that `MyModel` is recognized by the parser. 3. Modify `SystemModelData.hpp` so that `MyModelData` is visible to the system model. 4. Modify `SystemModel.hpp` so that `MyModel` components can be connected by the system composer. 5. Recommended: If applicable, add a smoke test to - `tests/UnitTesting/PhasorDynamics/SystemSingleComponentTests.hpp` for the + `tests/UnitTests/PhasorDynamics/SystemSingleComponentTests.hpp` for the basic construction of `MyModel` through `SystemModel`. 6. Recommended: Create an example in `examples/PhasorDynamics` using the new component. diff --git a/GridKit/Model/PhasorDynamics/SignalNode/README.md b/GridKit/Model/PhasorDynamics/SignalNode/README.md index 49cb97a1e..7d001acb2 100644 --- a/GridKit/Model/PhasorDynamics/SignalNode/README.md +++ b/GridKit/Model/PhasorDynamics/SignalNode/README.md @@ -1,4 +1,4 @@ -# Signal Node +# SignalNode Signal nodes provide scalar connection points between phasor-dynamics components. Components attach external inputs to signal nodes and assign @@ -10,6 +10,64 @@ without owning the producing model. ## Model Parameters -Symbol | Description --------|------------ -`signal_id` | Unique identifier for the signal node +Symbol | Units | JSON | Description | Typical Value | Note +------------|-------|-------------|---------------------------------------|---------------|----- +`signal_id` | [-] | `signal_id` | Unique identifier for the signal node | | + +### Parameter Validation + +None. + +### Model Derived Parameters + +None. + +## Model Ports + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Internal Equations + +#### Differential + +None. + +#### Algebraic + +None. + +### External Equations + +None. + +## Initialization + +None. + +## Monitors + +None. diff --git a/GridKit/Model/PhasorDynamics/SignalSource/README.md b/GridKit/Model/PhasorDynamics/SignalSource/README.md index 91c47356d..21cf83f1f 100644 --- a/GridKit/Model/PhasorDynamics/SignalSource/README.md +++ b/GridKit/Model/PhasorDynamics/SignalSource/README.md @@ -1,20 +1,72 @@ -# Constant signal source +# SignalSource -This component emits a constant complex value on two output ports (real and -imaginary). +Zero-state component that publishes constant real and imaginary scalar values +on two output signals. ## Model Parameters -The complex-value parameter is intentionally ambiguous, because it may be -applied in different contexts (for different input variables). +Symbol | Units | JSON | Description | Typical Value | Note +-------|-------------|------|---------------------------------|---------------|----- +$S_r$ | unspecified | `Sr` | Constant real output value | 0.0 | +$S_i$ | unspecified | `Si` | Constant imaginary output value | 0.0 | -Symbol | Units | Description | Note -------------|---------|---------------------------------| ------ -$Sr$ | unspecified | Real component | -$Si$ | unspecified | Imaginary component | +### Parameter Validation -## Output ports -- `sr` ($S_r$) -- `si` ($S_i$) +None. -Constant parameters are made available to signal nodes. +### Model Derived Parameters + +None. + +## Model Ports + +Name | Port | Init | Description +-----|--------|-------|----------------------------------- +`sr` | Output | Known | Constant real component $S_r$ +`si` | Output | Known | Constant imaginary component $S_i$ + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +None. + +### External Variables + +#### Differential + +None. + +#### Algebraic + +None. + +## Model Equations + +### Internal Equations + +#### Differential + +None. + +#### Algebraic + +None. + +### External Equations + +None. + +## Initialization + +None. + +## Monitors + +None. diff --git a/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md b/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md index e5765ba1a..c023a495d 100644 --- a/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md +++ b/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md @@ -1,6 +1,6 @@ -# **IEEE Stabilizer Model (IEEEST)** +# IEEEST -Standard IEEE power system stabilizer: 4th-order notch filter, two lead–lag +Standard IEEE power system stabilizer: notch filter of order up to four, two lead–lag blocks, washout, and output limiter. ## Block Diagram @@ -11,29 +11,37 @@ Figure 1: Stabilizer IEEEST model. Figure courtesy of [PowerWorld](https://www.p ## Model Parameters -Symbol | Units | Description | Typical Value -------------|--------|--------------------------------------|-------------- -$A_1$ | [s] | Notch denominator coefficient | 1.013 -$A_2$ | [s²] | Notch denominator coefficient | 0.013 -$A_3$ | [s] | Notch denominator coefficient | 0.0 -$A_4$ | [s²] | Notch denominator coefficient | 0.0 -$A_5$ | [s] | Notch numerator coefficient | 1.013 -$A_6$ | [s²] | Notch numerator coefficient | 0.113 -$T_1$ | [s] | Lead–lag 1 numerator time constant | 0.0 -$T_2$ | [s] | Lead–lag 1 denominator time constant | 0.02 -$T_3$ | [s] | Lead–lag 2 numerator time constant | 0.0 -$T_4$ | [s] | Lead–lag 2 denominator time constant | 0.0 -$T_5$ | [s] | Washout numerator time constant | 1.65 -$T_6$ | [s] | Washout denominator time constant | 1.65 -$K_s$ | [p.u.] | Stabilizer gain | 3.0 -$L_s^{\min}$ | [p.u.] | Minimum stabilizer output limit | -0.1 -$L_s^{\max}$ | [p.u.] | Maximum stabilizer output limit | 0.1 - -The IEEE 421.5 IEEEST also defines a cutout window ($V_{cl}$, $V_{cu}$) and an -input delay ($T_{delay}$). These parameters are accepted for input-format +Symbol | Units | JSON | Description | Typical Value | Note +-------------|--------|---------|--------------------------------------|---------------|----- +$A_1$ | [s] | `A1` | Notch denominator coefficient | 1.013 | +$A_2$ | [s²] | `A2` | Notch denominator coefficient | 0.013 | +$A_3$ | [s] | `A3` | Notch denominator coefficient | 0.0 | +$A_4$ | [s²] | `A4` | Notch denominator coefficient | 0.0 | +$A_5$ | [s] | `A5` | Notch numerator coefficient | 1.013 | +$A_6$ | [s²] | `A6` | Notch numerator coefficient | 0.113 | +$T_1$ | [s] | `T1` | Lead–lag 1 numerator time constant | 0.0 | +$T_2$ | [s] | `T2` | Lead–lag 1 denominator time constant | 0.02 | +$T_3$ | [s] | `T3` | Lead–lag 2 numerator time constant | 0.0 | +$T_4$ | [s] | `T4` | Lead–lag 2 denominator time constant | 0.0 | +$T_5$ | [s] | `T5` | Washout numerator time constant | 1.65 | +$T_6$ | [s] | `T6` | Washout denominator time constant | 1.65 | +$K_\mathrm{s}$ | [p.u.] | `Ks` | Stabilizer gain | 3.0 | +$L_\mathrm{s}^{\min}$ | [p.u.] | `Lsmin` | Minimum stabilizer output limit | -0.1 | +$L_\mathrm{s}^{\max}$ | [p.u.] | `Lsmax` | Maximum stabilizer output limit | 0.1 | + +The IEEE 421.5 IEEEST also defines a cutout window ($V_\mathrm{cl}$, $V_\mathrm{cu}$) and an +input delay ($T_\mathrm{delay}$). These parameters are accepted for input-format compatibility but are not modeled here. -### Derived Parameters +### Parameter Validation + +A valid IEEEST parameter set must satisfy the following conditions: + +```math +a_2=a_3=a_4=0 \quad\Longrightarrow\quad a_1=0 +``` + +### Model Derived Parameters ```math \begin{aligned} @@ -45,70 +53,125 @@ a_4 &= A_2 A_4 \end{aligned} ``` +The notch order is + +```math +n = \begin{cases} +4 & a_4\ne0 \\ +3 & a_4=0,\ a_3\ne0 \\ +2 & a_4=a_3=0,\ a_2\ne0 \\ +0 & a_4=a_3=a_2=a_1=0 +\end{cases} +``` + +## Model Ports + +Name | Port | Init | Description +---------|--------|-------|--------------------------------- +`input` | Input | Known | Required stabilizer input signal +`output` | Output | Known | Limited stabilizer output signal + ## Model Variables ### Internal Variables #### Differential -Symbol | Units | Description -----------------------|--------|------------ -$x_1, x_2, x_3, x_4$ | [-] | Notch filter states -$x_5$ | [-] | Lead–lag 1 state -$x_6$ | [-] | Lead–lag 2 state -$x_7$ | [-] | Washout state +Symbol | Units | Description | Note +-------|-----------|--------------------|------------------------ +$x_1$ | [p.u.] | Notch filter state | Held at zero when $n=0$ +$x_2$ | [p.u./s] | Notch filter state | Held at zero when $n=0$ +$x_3$ | [p.u./s²] | Notch filter state | Held at zero when $n<3$ +$x_4$ | [p.u./s³] | Notch filter state | Held at zero when $n<4$ +$x_5$ | [p.u.] | Lead–lag 1 state | Algebraic when $T_2=0$ +$x_6$ | [p.u.] | Lead–lag 2 state | Algebraic when $T_4=0$ +$x_7$ | [p.u.] | Washout state | Algebraic when $T_6=0$ #### Algebraic -Symbol | Units | Description ------------|--------|------------ -$v_4$ | [p.u.] | Notch filter output -$v_5$ | [p.u.] | Lead–lag 1 output -$v_6$ | [p.u.] | Lead–lag 2 output -$v_7$ | [p.u.] | Unlimited stabilizer signal -$V_{ss}$ | [p.u.] | Limited stabilizer signal (model output) +Symbol | Units | Description | Note +------------------|--------|------------------------------------------|----- +$v_4$ | [p.u.] | Notch filter output | +$v_5$ | [p.u.] | Lead–lag 1 output | +$v_6$ | [p.u.] | Lead–lag 2 output | +$v_7$ | [p.u.] | Unlimited stabilizer signal | +$V_{\mathrm{ss}}$ | [p.u.] | Limited stabilizer signal (model output) | ### External Variables +#### Differential + +None. + #### Algebraic -Symbol | Units | Description --------|--------|------------ -$u$ | [p.u.] | Stabilizer input signal +Symbol | Units | Description | Note +-------|--------|-------------------------|----- +$u$ | [p.u.] | Stabilizer input signal | ## Model Equations -### Differential Equations +Smooth functions: [`clamp`](../../../../CommonMath.md#clamp). + +### Internal Equations + +#### Differential ```math \begin{aligned} -0 &= -\dot{x}_1 + x_2 \\ -0 &= -\dot{x}_2 + x_3 \\ -0 &= -\dot{x}_3 + x_4 \\ -0 &= -\dot{x}_4 - \dfrac{a_0}{a_4}x_1 - \dfrac{a_1}{a_4}x_2 - \dfrac{a_2}{a_4}x_3 - \dfrac{a_3}{a_4}x_4 + \dfrac{1}{a_4}u \\ -0 &= -T_2 \dot{x}_5 - x_5 + v_4 \\ -0 &= -T_4 \dot{x}_6 - x_6 + v_5 \\ -0 &= -T_6 \dot{x}_7 - x_7 + v_6 +0 &= -\dot{x}_k+x_{k+1}, && 1\le k0 \\ +0 &= -\dot{x}_k, && n0 \\ +u & n=0 +\end{cases} \\ +0 &= \begin{cases} +-T_2(v_5-x_5)+T_1(v_4-x_5) & T_2\ne0 \\ +-v_5+v_4 & T_2=0 +\end{cases} \\ +0 &= \begin{cases} +-T_4(v_6-x_6)+T_3(v_5-x_6) & T_4\ne0 \\ +-v_6+v_5 & T_4=0 +\end{cases} \\ +0 &= \begin{cases} +-T_6v_7+K_\mathrm{s}T_5(v_6-x_7) & T_6\ne0 \\ +-v_7+K_\mathrm{s}v_6 & T_6=0 +\end{cases} \\ +0 &= -V_{\mathrm{ss}}+\text{clamp}(v_7;L_\mathrm{s}^{\min},L_\mathrm{s}^{\max}) \end{aligned} ``` -The output limiter uses GridKit's smooth -[Clamp](../../../../CommonMath.md#derived-functions). +### External Equations + +None. ## Initialization -All states and their derivatives initialize to zero. The stabilizer comes -online at rest and produces signal only in response to deviations in the input -$u$. +The initial input determines the steady state; all derivatives initialize to zero. + +```math +\begin{aligned} +x_1 &\leftarrow \begin{cases}u & n>0 \\ 0 & n=0\end{cases} \\ +x_2,x_3,x_4 &\leftarrow 0 \\ +x_5,x_6,x_7,v_4,v_5,v_6 &\leftarrow u \\ +v_7 &\leftarrow \begin{cases}0 & T_6\ne0 \\ K_\mathrm{s}u & T_6=0\end{cases} \\ +V_{\mathrm{ss}} &\leftarrow \text{clamp}(v_7;L_\mathrm{s}^{\min},L_\mathrm{s}^{\max}) +\end{aligned} +``` + +## Monitors + +Monitor | Units | Description | Note +--------|--------|---------------------------|-------------------------------- +`vss` | [p.u.] | Limited stabilizer signal | $V_{\mathrm{ss}}$; model output diff --git a/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md b/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md index 6f3ba0cc1..a5ccf249a 100644 --- a/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md +++ b/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md @@ -1,12 +1,8 @@ # PSS1A -> [!NOTE] -> This is not yet implemented - -> [!NOTE] -> The Parameters, variables, and equations need to be formatted and verified - this is WIP. - +Specification draft; not implemented. The equations and initialization remain unverified. +## Block Diagram ![](../../../../../docs/Figures/PSS1A.JPG) @@ -14,24 +10,38 @@ Figure 1: Power system stabilizer PSS1A model. Figure courtesy of [PowerWorld](h ## Model Parameters +Symbol | Units | JSON | Description | Typical Value | Note +-------|-------|------|-------------|---------------|----- +$I_{\mathrm{cs}}$ | [-] | TBD | Stabilizer input code | 2 | +$A_1$ | [s] | TBD | Notch denominator coefficient | 0 | +$A_2$ | [s²] | TBD | Notch denominator coefficient | 0 | +$T_1$ | [s] | TBD | Lead–lag 1 numerator time constant | 0.25 | +$T_2$ | [s] | TBD | Lead–lag 1 denominator time constant | 0.03 | +$T_3$ | [s] | TBD | Lead–lag 2 numerator time constant | 0.25 | +$T_4$ | [s] | TBD | Lead–lag 2 denominator time constant | 0.03 | +$T_5$ | [s] | TBD | Washout numerator time constant | 20 | +$T_6$ | [s] | TBD | Transducer time constant | 0.02 | +$K_\mathrm{s}$ | [p.u.] | TBD | Stabilizer gain | 10 | +$L_\mathrm{s}^{\max}$ | [p.u.] | TBD | Maximum stabilizer output | 0.1 | +$L_\mathrm{s}^{\min}$ | [p.u.] | TBD | Minimum stabilizer output | -0.1 | +$V_\mathrm{cu}$ | [p.u.] | TBD | Upper cutout threshold | 0 | +$V_\mathrm{cl}$ | [p.u.] | TBD | Lower cutout threshold | 0 | + +### Parameter Validation -- $I_{cs}$ - stabilizer input code, (2) -- $A_{1}$ - notch filter parameters, (0) -- $A_{2}$ - notch filter parameters, (0) -- $T_{1}$ - lead/lag time constant, sec (0.25) -- $T_{2}$ - lead/lag time constant, sec (0.03) -- $T_{3}$ - lead/lag time constant, sec (0.25) -- $T_{4}$ - lead/lag time constant, sec (0.03) -- $T_{5}$ - washout numerator time constant, sec (20) -- $T_{6}$ - washout denomirator time constant/transducer time constant, sec (0.02) -- $K_{S}$ - stabilizer gains, (10) -- $L_{smax}$ - maximum stabilizer output, pu (0.1) -- $L_{smin}$ - minimum stabilizer output, pu (-0.1) -- $V_{cu}$ - stabilizer input cutoff threshold, pu (0) -- $V_{cl}$ - stabilizer input cutoff threshold, pu (0) +TBD. +### Model Derived Parameters +TBD. +## Model Ports + +Name | Port | Init | Description +---------|--------|------|------------------------------------------ +`input` | Input | TBD | Stabilizer input $u$ selected by $I_{\mathrm{cs}}$ +`vct` | Input | TBD | Cutout signal $V_{\mathrm{ct}}$ +`output` | Output | TBD | Limited stabilizer output $V_{\mathrm{ss}}$ ## Model Variables @@ -48,12 +58,10 @@ These were the variables listed in the old documentation. #### Differential -TBD - +TBD. #### Algebraic -TBD - +TBD. ### External Variables #### Differential @@ -62,13 +70,16 @@ None. #### Algebraic -Symbol | Units | Description | Note ------- | ----- | ----------- | ---- -$u$ | [p.u.] | Stabilizer input signal | -$V_{ct}$ | [p.u.] | Cutout signal (compared to $V_{cl},V_{cu}$) | from the block diagram +Symbol | Units | Description | Note +---------|--------|---------------------------------------------|----------------------- +$u$ | [p.u.] | Stabilizer input signal | +$V_{\mathrm{ct}}$ | [p.u.] | Cutout signal (compared to $V_\mathrm{cl},V_\mathrm{cu}$) | from the block diagram + +## Model Equations +### Internal Equations -### Differential Equations +#### Differential ```math \begin{aligned} @@ -77,21 +88,32 @@ $V_{ct}$ | [p.u.] | Cutout signal (compared to $V_{cl},V_{cu}$) | from the block \dfrac{d^{2}V_{3}}{dt^{2}}+\dfrac{A_{1}}{A_{2}}\dfrac{dV_{3}}{dt}&=\dfrac{1}{A_{2}}(V_{2}-1) \\ \dfrac{dx_{2}}{dt}&=\dfrac{1}{T_{2}}(V_{3}-V_{4}) \\ \dfrac{dx_{3}}{dt}&=\dfrac{1}{T_{4}}(V_{4}-V_{5}) - \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} -V_{2} &= x_{1} + K_{S} V_{1} \\ +V_{2} &= x_{1} + K_\mathrm{s} V_{1} \\ V_{4}&=x_{2}+\dfrac{T_{1}}{T_{2}}V_{3} \\ V_{5}&=x_{3}+\dfrac{T_{3}}{T_{4}}V_{4} \\ -V_{llout} &= \begin{cases} - L_{SMAX} &\text{if } V_{5}>V_{SMAX} \\ - L_{SMIN} &\text{if } V_{5}L_\mathrm{s}^{\max} \\ + L_\mathrm{s}^{\min} &\text{if } V_{5}S_A \\ - 0 &\text{if } \psi''\leq S_A - \end{cases} -\end{aligned} +```math +k_\mathrm{sat}=S_Bq(\psi-S_A) ``` + +Here $\psi=\psi''$ for GENROU and $\psi=E'_q$ for GENSAL. Each model defines +its saturation fit. diff --git a/docs/Figures/EMT/Propagation/diagram.png b/docs/Figures/EMT/Propagation/diagram.png index 3af078f49..ecaa1b43b 100644 Binary files a/docs/Figures/EMT/Propagation/diagram.png and b/docs/Figures/EMT/Propagation/diagram.png differ diff --git a/docs/Figures/EMT/Propagation/diagram.tex b/docs/Figures/EMT/Propagation/diagram.tex index 248735b93..6c6e4662c 100644 --- a/docs/Figures/EMT/Propagation/diagram.tex +++ b/docs/Figures/EMT/Propagation/diagram.tex @@ -4,44 +4,47 @@ \begin{document} \begin{tikzpicture}[emt diagram] -% Three-block current propagation: fitted input map -> modal delays -> fitted output map +% Per-mode current propagation: fitted minimum-phase-shift factor -> modal delay, +% summed over modes \node[block, minimum width=2.1cm] (D2) {$\exp(-s\tau_2)$}; \node[block, minimum width=2.1cm, above=0.6cm of D2] (D1) {$\exp(-s\tau_1)$}; -\node[block, minimum width=2.1cm, below=1.3cm of D2] (DN) {$\exp(-s\tau_M)$}; -\node at ($(D2)!0.5!(DN)$) {$\vdots$}; +\node[block, minimum width=2.1cm, below=1.3cm of D2] (DM) {$\exp(-s\tau_M)$}; +\node at ($(D2)!0.5!(DM)$) {$\vdots$}; -\node[block, minimum width=2.6cm, left=1.5cm of D2] - (Gin) {$\mathbf{G}^{\mathrm{in}}(s)$}; -\node[block, minimum width=2.7cm, right=1.5cm of D2] - (Gout) {$\mathbf{G}^{\mathrm{out}}(s)$}; +\node[block, left=0.75cm of D2] (H2) {$\mathbf{H}^{\mathrm{mps}}_2(s)$}; +\node[block, left=0.75cm of D1] (H1) {$\mathbf{H}^{\mathrm{mps}}_1(s)$}; +\node[block, left=0.75cm of DM] (HM) {$\mathbf{H}^{\mathrm{mps}}_M(s)$}; +\node at ($(H2)!0.5!(HM)$) {$\vdots$}; + +\foreach \m in {1, 2, M} + \draw[->, line] (H\m.east) -- (D\m.west); % Fan-out from a single internal point -\coordinate (split) at ($(Gin.east)!0.5!(D2.west)$); -\draw[line] (Gin.east) -- (split); -\draw[->, line] (split) -- (D2.west); -\foreach \b in {D1, DN} +\coordinate (split) at ($(H2.west)+(-1.05, 0)$); +\draw[->, line] (split) -- (H2.west); +\foreach \b in {H1, HM} \draw[->, line] (split) |- (\b.west); -% Fan-in to the fitted output map -\coordinate (join) at ($(D2.east)!0.5!(Gout.west)$); -\draw[line] (D2.east) -- (join); -\foreach \b in {D1, DN} - \draw[line] (\b.east) -| (join); -\draw[->, line] (join) -- (Gout.west); +% Fan-in to summation +\node[sum, right=0.75cm of D2] (S) {$\Sigma$}; +\draw[->, line] (D2.east) -- (S); +\foreach \b/\a in {D1/north, DM/south} + \draw[->, line] (\b.east) -| (S.\a); + +% Input node (owned externally) +\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) + at ($(split)+(-1.5, 0)$) {}; +\draw[line] ($(uin)+(-0.8, 0)$) -- (split); % Output node (owned by this model) with port arrow out -\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of Gout] (yout) {}; -\draw[line] (Gout.east) -- (yout); +\node[signal, label={[sig]above:$\mathbf{y}$}, right=0.55cm of S] + (yout) {}; +\draw[line] (S.east) -- (yout); \draw[->, line] (yout) -- ++(1.55, 0); -% Input node (owned externally) with port arrow into this model -\node[signal, label={[sig]above:$\mathbf{u}$}] (uin) - at ($(Gin.west)+(-1.5, 0)$) {}; -\draw[->, line] ($(uin)+(-0.8, 0)$) -- (Gin.west); - -% Model enclosure: fixed padding around model-owned blocks and output variable +% Model enclosure: fixed padding around model-owned paths and output variable \begin{scope}[on background layer] - \node[operator enclosure, fit=(Gin)(D1)(D2)(DN)(Gout)(yout)] {}; + \node[operator enclosure, fit=(split)(H1)(H2)(HM)(D1)(D2)(DM)(S)(yout)] {}; \end{scope} \end{tikzpicture} diff --git a/docs/GridKit/Model/PhasorDynamics/Controller/README.md b/docs/GridKit/Model/PhasorDynamics/Controller/README.md index 3962c8eb4..63abf851f 100644 --- a/docs/GridKit/Model/PhasorDynamics/Controller/README.md +++ b/docs/GridKit/Model/PhasorDynamics/Controller/README.md @@ -5,6 +5,7 @@ :titlesonly: :hidden: +REECA REECB REPCA ``` diff --git a/docs/GridKit/Model/PhasorDynamics/Controller/REECA/README.md b/docs/GridKit/Model/PhasorDynamics/Controller/REECA/README.md new file mode 100644 index 000000000..461329bc9 --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/Controller/REECA/README.md @@ -0,0 +1,6 @@ +# REECA + +```{include} ../../../../../../GridKit/Model/PhasorDynamics/Controller/REECA/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/PhasorDynamics/Converter/README.md b/docs/GridKit/Model/PhasorDynamics/Converter/README.md index fa56e8dd8..fa9c79fd5 100644 --- a/docs/GridKit/Model/PhasorDynamics/Converter/README.md +++ b/docs/GridKit/Model/PhasorDynamics/Converter/README.md @@ -7,7 +7,6 @@ REGCA REGCB -REECA ``` ```{include} ../../../../../GridKit/Model/PhasorDynamics/Converter/README.md diff --git a/docs/GridKit/Model/PhasorDynamics/Converter/REECA/README.md b/docs/GridKit/Model/PhasorDynamics/Converter/REECA/README.md deleted file mode 100644 index e84371269..000000000 --- a/docs/GridKit/Model/PhasorDynamics/Converter/REECA/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# REECA - -```{include} ../../../../../../GridKit/Model/PhasorDynamics/Converter/REECA/README.md -:start-line: 1 -:relative-images: -``` diff --git a/docs/GridKit/Model/PhasorDynamics/Exciter/README.md b/docs/GridKit/Model/PhasorDynamics/Exciter/README.md index 143bad900..62e391600 100644 --- a/docs/GridKit/Model/PhasorDynamics/Exciter/README.md +++ b/docs/GridKit/Model/PhasorDynamics/Exciter/README.md @@ -6,15 +6,15 @@ :hidden: ESAC6A -IEEET1 -EXDC1 ESDC1A ESDC2A -EXAC1 ESST4B -SCRX +EXAC1 EXAC2 +EXDC1 EXPIC1 +IEEET1 +SCRX SEXS-PTI ``` diff --git a/docs/GridKit/Model/PhasorDynamics/Governor/README.md b/docs/GridKit/Model/PhasorDynamics/Governor/README.md index 0a0e046bd..1ccc82d69 100644 --- a/docs/GridKit/Model/PhasorDynamics/Governor/README.md +++ b/docs/GridKit/Model/PhasorDynamics/Governor/README.md @@ -5,11 +5,11 @@ :titlesonly: :hidden: -TGOV1 GASTPTI +GGOV1 HYGOV IEEEG1 -GGOV1 +TGOV1 ``` ```{include} ../../../../../GridKit/Model/PhasorDynamics/Governor/README.md diff --git a/docs/GridKit/Model/PhasorDynamics/README.md b/docs/GridKit/Model/PhasorDynamics/README.md index e867035a4..fcc984f7c 100644 --- a/docs/GridKit/Model/PhasorDynamics/README.md +++ b/docs/GridKit/Model/PhasorDynamics/README.md @@ -16,6 +16,7 @@ Exciter Governor Load SignalNode +SignalSource Stabilizer SynchronousMachine ``` diff --git a/docs/GridKit/Model/PhasorDynamics/SignalSource/README.md b/docs/GridKit/Model/PhasorDynamics/SignalSource/README.md new file mode 100644 index 000000000..c48bfeaf1 --- /dev/null +++ b/docs/GridKit/Model/PhasorDynamics/SignalSource/README.md @@ -0,0 +1,6 @@ +# SignalSource + +```{include} ../../../../../GridKit/Model/PhasorDynamics/SignalSource/README.md +:start-line: 1 +:relative-images: +``` diff --git a/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md b/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md similarity index 100% rename from docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROUwS/README.md rename to docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md diff --git a/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md b/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md similarity index 100% rename from docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSALwS/README.md rename to docs/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md diff --git a/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md b/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md index eedbbe0de..850d977ab 100644 --- a/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md +++ b/docs/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md @@ -6,8 +6,8 @@ :hidden: GenClassical -GENROU -GENSAL +GENROU +GENSAL ``` ```{include} ../../../../../GridKit/Model/PhasorDynamics/SynchronousMachine/README.md