diff --git a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md index 2fad25be4..374d203ca 100644 --- a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md +++ b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -4,6 +4,13 @@ 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) e^{-s\tau_m} +\end{aligned} +``` + ## Block Diagram ![Propagation operator block diagram](../../../../../../docs/Figures/EMT/Propagation/diagram.png) @@ -51,29 +58,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 diff --git a/GridKit/Model/PhasorDynamics/Branch/README.md b/GridKit/Model/PhasorDynamics/Branch/README.md index 97256c5aa..8e9697781 100644 --- a/GridKit/Model/PhasorDynamics/Branch/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/README.md @@ -28,7 +28,7 @@ $\theta$ | [rad] | `phase` | Phase-shift angle ### 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} @@ -111,6 +111,13 @@ The magnetizing and line shunts are added outside the transformation: 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 @@ -140,11 +147,17 @@ $V_{i2}$ | [p.u.] | Terminal voltage, imaginary component, bus 2 | Owned by ## 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,14 +181,14 @@ 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. +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). -## Model Outputs +## Monitors -Output | Units | Description | Note --------|--------|----------------------------------------------|------ +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 | diff --git a/GridKit/Model/PhasorDynamics/Bus/README.md b/GridKit/Model/PhasorDynamics/Bus/README.md index f86c89934..666815551 100644 --- a/GridKit/Model/PhasorDynamics/Bus/README.md +++ b/GridKit/Model/PhasorDynamics/Bus/README.md @@ -1,4 +1,4 @@ -# 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 @@ -10,7 +10,7 @@ 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. -## Sign Convention +## Notes Current entering the bus has positive sign, and current exiting the bus has negative sign. @@ -22,9 +22,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 | Note +------------------|-------|------|---------------------|------- +$V_\mathrm{base}$ | [kV] | `kv` | Nominal bus voltage | Unused -Symbol | Units | JSON | Description ---------------------|-------|------|------------ -$V_\mathrm{base}$ | [kV] | `kv` | Nominal bus voltage +### Parameter Validation + +None. + +### Model Derived Parameters + +None. + +## Model Ports + +None. + +## Model Variables + +### Internal Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description +-------|--------|------------ +$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{E}$ denote the set of components connected to the bus. + +```math +\begin{aligned} +0 &= \sum_{e \in \mathcal{E}} I_{r,e} \\ +0 &= \sum_{e \in \mathcal{E}} I_{i,e} +\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 + +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..455699c3d 100644 --- a/GridKit/Model/PhasorDynamics/BusFault/README.md +++ b/GridKit/Model/PhasorDynamics/BusFault/README.md @@ -4,11 +4,11 @@ Represents an impedance fault at a bus. This device can exist in two states, on ## 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 | 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()`. ### Model Derived Parameters ``` math @@ -18,12 +18,19 @@ $U$ | [unitless] | Binary status $$\in \{0, 1\}$$ | Set by user to put fau \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 @@ -37,9 +44,11 @@ $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 @@ -48,13 +57,50 @@ $V_i$ | [p.u.] | Terminal voltage, imaginary component | owned by bus obj ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential + None. -### Algebraic Equations +#### Algebraic + ``` math \begin{aligned} 0 &= -I_{r} + U (-G V_{r} + B V_{i}) \\ 0 &= -I_{i} + U (-B V_{r} - G V_{i}) \end{aligned} ``` + +### 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 + +For the initial fault status $U_0$, the algebraic fault currents are initialized +from the connected-bus voltage: + +```math +\begin{aligned} +I_{r,0} &= U_0\left(-G V_{r,0}+B V_{i,0}\right) \\ +I_{i,0} &= U_0\left(-B V_{r,0}-G V_{i,0}\right). +\end{aligned} +``` + +The derivative-vector entries are initialized 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..4b37211d9 100644 --- a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md +++ b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md @@ -1,20 +1,76 @@ # Bus-to-Signal Adapter -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. +## Model Ports -## Output Ports -- `vr` ($V_r$) -- `vi` ($V_i$) +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 -Voltages read from the bus are made available to signal nodes. +## 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/REECB/README.md b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md index 0dcf468b8..5b325dd3b 100644 --- a/GridKit/Model/PhasorDynamics/Controller/REECB/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md @@ -225,9 +225,11 @@ $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}$. -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`. +CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup), +[`max`](../../../../CommonMath.md#maximum), [`inside`](../../../../CommonMath.md#inside), +[`above`](../../../../CommonMath.md#above), [`deadband2`](../../../../CommonMath.md#type-ii-deadband), +and [`clamp`](../../../../CommonMath.md#clamp) functions used in these equations. +[Appendix B](#appendix-b-aslew) defines `aslew`. ### External Equations @@ -360,9 +362,9 @@ 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) @@ -408,7 +410,7 @@ For $\ell<0 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} \\ @@ -227,8 +228,9 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines the [derived limiter functions](../../../../CommonMath.md#derived-functions) -used above; Appendix A defines `droop`. +CommonMath defines the [`above`](../../../../CommonMath.md#above), +[`deadband2`](../../../../CommonMath.md#type-ii-deadband), and +[`clamp`](../../../../CommonMath.md#clamp) functions used above; Appendix A defines `droop`. ### External Equations @@ -314,9 +316,9 @@ Initialization is atomic; candidates are validated before state or signal writes \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 @@ -349,7 +351,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/REECA/README.md b/GridKit/Model/PhasorDynamics/Converter/REECA/README.md index d2a7c743f..704d78f26 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REECA/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REECA/README.md @@ -112,7 +112,7 @@ The off-mode flag complements are: \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: +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} @@ -137,6 +137,20 @@ The VDL functions use GridKit's smooth [Linear Segment](../../../../CommonMath.m \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 @@ -207,7 +221,9 @@ For readability, define: \end{aligned} ``` -### Differential Equations +### Internal Equations + +#### Differential 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. @@ -251,7 +267,7 @@ The state-equation residuals use compact limiter notation where applicable. The CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic The algebraic targets use CommonMath helper notation where applicable: @@ -288,7 +304,14 @@ The algebraic targets use CommonMath helper notation where applicable: 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). +CommonMath defines the helper targets and smooth approximations for +[min](../../../../CommonMath.md#minimum), [max](../../../../CommonMath.md#maximum), +[clamp](../../../../CommonMath.md#clamp), [deadband2](../../../../CommonMath.md#type-ii-deadband), +and [outside](../../../../CommonMath.md#outside). + +### External Equations + +None. ## Initialization @@ -389,9 +412,9 @@ 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 +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `iqcmd` | [p.u.] | Reactive-current command output | Converter base `ipcmd` | [p.u.] | Active-current command output | Converter base diff --git a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md index 269d122cb..525e12838 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md @@ -68,6 +68,8 @@ every other condition is a configuration error. &\ge 0 \\ I_{L1} &\ge 0 \\ + K_L + &> 0 \\ s_L &\in \{0,1\} \\ 0 @@ -167,7 +169,9 @@ f_\mathrm{p}^{\lim} = \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 sign that enables the corresponding limit. @@ -192,7 +196,7 @@ the sign that enables the corresponding limit. ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -217,10 +221,12 @@ the sign that enables the corresponding limit. \end{aligned} ``` -CommonMath defines the [primitives](../../../../CommonMath.md#primitives) and -[derived functions](../../../../CommonMath.md#derived-functions) used above. +CommonMath defines the [`ramp`](../../../../CommonMath.md#ramp), +[`max`](../../../../CommonMath.md#maximum), [`min`](../../../../CommonMath.md#minimum), +[`clamp`](../../../../CommonMath.md#clamp), and +[`linseg`](../../../../CommonMath.md#linear-segment) functions used above. -## Network Interface +### External Equations ```math \begin{aligned} @@ -318,10 +324,10 @@ The remaining algebraic quantities are then initialized as follows: \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 diff --git a/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md b/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md index 32f86f38d..cc8595788 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REGCB/README.md @@ -1,9 +1,7 @@ # **Renewable Energy Generator/Converter Model (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 @@ -13,22 +11,21 @@ Standard model diagram for the REGCB converter interface. 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..20938fc27 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESAC6A/README.md @@ -81,6 +81,18 @@ 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 @@ -130,7 +142,9 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -142,7 +156,7 @@ $\omega$ | [p.u.] | Machine speed deviation \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -172,12 +186,16 @@ $\omega$ | [p.u.] | Machine speed deviation \end{aligned} ``` -CommonMath defines helper targets for [clamp](../../../../CommonMath.md#derived-functions) -and the primitive [quadratic ramp](../../../../CommonMath.md#primitives) $q$. +CommonMath defines helper targets for [clamp](../../../../CommonMath.md#clamp) +and the primitive [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $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. +### External Equations + +None. + ## Initialization The machine initializes $E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ first. For a @@ -218,9 +236,9 @@ $V_{E,0}\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 +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `ve` | [p.u.] | Exciter alternator voltage state | $V_E$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md index ff7cae735..45ecae23e 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md @@ -58,8 +58,6 @@ 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}} &\in \{0,1,2,3\} \end{aligned} @@ -222,14 +220,16 @@ $V_{\mathrm{UEL}}$ | [p.u.] | Known | Under-excitation limite ## Model Equations +### Internal Equations + +#### Differential + Define the pre-limit exciter field-voltage rate: ```math f_E = \dfrac{V_R-V_{\mathrm{FE}}}{T_E}. ``` -### Differential Equations - ```math \begin{aligned} 0 &= @@ -271,7 +271,7 @@ f_E = \dfrac{V_R-V_{\mathrm{FE}}}{T_E}. 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} @@ -309,8 +309,12 @@ of [Appendix A](#appendix-a-awmin). ``` 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$. +[max](../../../../CommonMath.md#maximum), the [ramp](../../../../CommonMath.md#ramp) +$\rho$, and the [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $q$. + +### External Equations + +None. ## Initialization @@ -338,7 +342,7 @@ Initialization never replaces the seeded value held in $E_{\mathrm{fd}}$. 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 +[ramp](../../../../CommonMath.md#ramp) $\rho^{-1}$ when the UEL input is routed through the gate: ```math @@ -404,9 +408,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$ @@ -460,6 +464,6 @@ The model evaluates this rule with the following smooth approximation: \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..05074bdb7 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md @@ -104,6 +104,17 @@ 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 @@ -147,7 +158,9 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -168,7 +181,7 @@ $\omega$ | [p.u.] | Machine speed deviation CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -186,10 +199,14 @@ target and smooth approximation. ``` 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$. +[max](../../../../CommonMath.md#maximum) and the primitives +[ramp](../../../../CommonMath.md#ramp) and [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $\rho$ and $q$. When $T_B=T_C=0$, the lead-lag block is bypassed so $V_{\mathrm{ll}}=e_V$. +### External Equations + +None. + ## Initialization The machine initializes $E_{\mathrm{fd}}$ first. For a standard unsaturated @@ -218,9 +235,9 @@ $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 and active high-value-gate starts 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}}$ `vc` | [p.u.] | Sensed compensated voltage | $V_C$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md index 27ae8e018..599140de5 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESST4B/README.md @@ -71,6 +71,22 @@ The potential-source coefficient is resolved into real scalar components: 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_{\mathrm{r}}$ +`vi` | Input | TBD | Terminal-voltage imaginary component $V_{\mathrm{i}}$ +`ir` | Input | TBD | Terminal-current real component $I_{\mathrm{r}}$ +`ii` | Input | TBD | Terminal-current imaginary component $I_{\mathrm{i}}$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables @@ -124,7 +140,9 @@ $I_{\mathrm{fd}}$ | [p.u.] | Machine field current ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -152,7 +170,7 @@ $I_{\mathrm{fd}}$ | [p.u.] | Machine field current CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -179,9 +197,14 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines helper targets for [min and clamp](../../../../CommonMath.md#derived-functions). +CommonMath defines helper targets for [min](../../../../CommonMath.md#minimum) +and [clamp](../../../../CommonMath.md#clamp). 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 @@ -224,9 +247,9 @@ $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..368e0fa1f 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC1/README.md @@ -87,6 +87,19 @@ 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 @@ -133,7 +146,9 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -154,7 +169,7 @@ $\omega$ | [p.u.] | Machine speed deviation CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -169,11 +184,15 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines the primitive [quadratic ramp](../../../../CommonMath.md#primitives) +CommonMath defines the primitive [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $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$. +### External Equations + +None. + ## Initialization The machine initializes $E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ first. For a @@ -212,9 +231,9 @@ This standard start requires $1+s_{\mathrm{spd}}\omega_0\ne 0$, $V_{E,0}\ne 0$, and $V_R^{\min}\le V_{R,0}\le V_R^{\max}$. Saturated regulator starts are outside these closed-form equations. -## Model Outputs +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `ve` | [p.u.] | Exciter alternator voltage state | $V_E$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md index f957d31ff..01be6a2a6 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXAC2/README.md @@ -80,6 +80,19 @@ 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 @@ -130,7 +143,9 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -151,7 +166,7 @@ $\omega$ | [p.u.] | Machine speed deviation CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -170,11 +185,16 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines helper targets for [min and clamp](../../../../CommonMath.md#derived-functions) -and the primitive [quadratic ramp](../../../../CommonMath.md#primitives) $q$. +CommonMath defines helper targets for [min](../../../../CommonMath.md#minimum) +and [clamp](../../../../CommonMath.md#clamp), and the primitive +[quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $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$. +### External Equations + +None. + ## Initialization The machine initializes $E_{\mathrm{fd}}$ and $I_{\mathrm{fd}}$ first. For a @@ -224,9 +244,9 @@ 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 +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ----------------|--------|-------------------------------------|------ `efd` | [p.u.] | Field-voltage output | $E_{\mathrm{fd}}$ `ve` | [p.u.] | Exciter alternator voltage state | $V_E$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md index db6f96886..8ae85b3c2 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md @@ -1,107 +1,255 @@ -# **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 | Description | Typical Value +---------------|--------|----------------------------------------------|-------------- +$T_R$ | [sec] | Voltage transducer time constant | 0.0 +$K_A$ | [p.u.] | Voltage-regulator gain | 40.0 +$T_A$ | [sec] | Voltage-regulator time constant | 0.1 +$T_B$ | [sec] | Input lead–lag denominator time constant | 0.0 +$T_C$ | [sec] | Input lead–lag numerator time constant | 0.0 +$V_R^{\max}$ | [p.u.] | Maximum voltage-regulator output | 1.0 +$V_R^{\min}$ | [p.u.] | Minimum voltage-regulator output | -1.0 +$K_E$ | [p.u.] | Exciter field resistance line slope margin | 0.1 +$T_E$ | [sec] | Exciter time constant | 0.5 +$K_F$ | [p.u.] | Stabilizing feedback gain | 0.05 +$T_{F1}$ | [sec] | Stabilizing feedback time constant | 0.7 +$E_1$ | [p.u.] | First saturation voltage point | 2.8 +$S_E(E_1)$ | [p.u.] | Saturation coefficient at $E_1$ | 0.08 +$E_2$ | [p.u.] | Second saturation voltage point | 3.7 +$S_E(E_2)$ | [p.u.] | Saturation coefficient at $E_2$ | 0.33 + +### Parameter Validation + +All parameters must be finite. Valid parameter sets satisfy + ```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 + +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 +--------------------|--------|-------------------------------------- +$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 +--------------------|--------|--------------------------------------- +$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} + \left( + V_R, -V_R + K_A V_B; + V_R^{\min}, V_R^{\max} + \right) \\ +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} \left(V_R - V_{\mathrm{FE}}\right) +\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 \left(V_B - x_{\mathrm{LL}}\right) + + T_C \left(e_V - x_{\mathrm{LL}}\right) & T_B > 0 + \end{cases} \\ +0 &= -s_e + S_B q\left(E_{\mathrm{fd}}' - S_A\right) \\ +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\left(E_{\mathrm{fd}}' - S_A\right) \\ +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..f5ee4ab9d 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md @@ -88,6 +88,22 @@ components: \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_{\mathrm{r}}$ +`vi` | Input | TBD | Terminal-voltage imaginary component $V_{\mathrm{i}}$ +`ir` | Input | TBD | Terminal-current real component $I_{\mathrm{r}}$ +`ii` | Input | TBD | Terminal-current imaginary component $I_{\mathrm{i}}$ +`ifd` | Input | TBD | Machine field current $I_{\mathrm{fd}}$ +`efd` | Output | TBD | Field-voltage output $E_{\mathrm{fd}}$ + ## Model Variables ### Internal Variables @@ -141,7 +157,9 @@ $I_{\mathrm{fd}}$ | [p.u.] | Machine field current ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -165,7 +183,7 @@ $I_{\mathrm{fd}}$ | [p.u.] | Machine field current CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -195,12 +213,16 @@ target and smooth approximation. \end{aligned} ``` -CommonMath defines helper targets for [clamp](../../../../CommonMath.md#derived-functions) -and the primitive [quadratic ramp](../../../../CommonMath.md#primitives) $q$. +CommonMath defines helper targets for [clamp](../../../../CommonMath.md#clamp) +and the primitive [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $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 @@ -253,9 +275,9 @@ If $T_E=0$, the final exciter residual is algebraic and requires $E_{\mathrm{fd},0}=E_{0,0}$. Starts that bind the PI regulator, cascaded regulator, or exciter limits are outside these closed-form equations. -## Model Outputs +## 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 b5d7d3a6d..1e928dc56 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md @@ -34,6 +34,8 @@ $I_{\mathrm{spdlim}}$ | [binary] | 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. ```math \begin{aligned} @@ -135,6 +137,15 @@ K_E^{\mathrm{eff}} 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 +--------|--------|-------|------------ +`bus` | Bus | Known | Terminal bus voltage +`speed` | Input | Known | Optional machine speed deviation; defaults to zero +`vs` | Input | Known | Optional stabilizer input signal; defaults to zero +`efd` | Output | Known | Field-voltage output seeded by the machine + ## Model Variables ### Internal Variables @@ -145,7 +156,7 @@ Symbol | Units | Description | Note ----------|--------|------------------------------------|------- $V_{ts}$ | [p.u.] | Sensed terminal voltage | $V_R$ | [p.u.] | Voltage regulator | -$E_{fd}'$ | [p.u.] | Field-current pre-speed multiplier | +$E_{fd}'$ | [p.u.] | Field voltage before the speed multiplier | $V_{fx}$ | [p.u.] | Exciter feedback internal state | @@ -162,11 +173,17 @@ $k_\text{sat}$ | [p.u.] | Scaled-quadratic saturation contribution | $E_{fd}'S( ### External Variables +#### Differential + +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 | +$V_\text{ref}$ | [p.u.] | Reference terminal voltage | Set during initialization; constant thereafter $V_{UEL}$ | [p.u.] | Input from under excitation limiter | Constant zero until modeled $V_{OEL}$ | [p.u.] | Input from over excitation limiter | Constant zero until modeled $V_S$ | [p.u.] | Input from stabilizer controller | Optional, defaults to zero @@ -175,7 +192,9 @@ $\omega$ | [p.u.] | Machine speed deviation | Opti ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential For readability, define the pre-limit derivative of $V_R$ and voltage-sensing input: @@ -201,7 +220,7 @@ The IEEET1 differential equations, as derived from the model diagram, are: CommonMath defines the smooth [Anti-Windup](../../../../CommonMath.md#antiwindup) target and approximation. -### Algebraic Equations +#### Algebraic The algebraic equations of the exciter. ```math @@ -214,13 +233,14 @@ The algebraic equations of the exciter. \end{aligned} ``` -Here $q$ is GridKit's [Quadratic Ramp](../../../../CommonMath.md#primitives). +Here $q$ is GridKit's [Quadratic Ramp](../../../../CommonMath.md#quadratic-ramp). + +### External Equations +None. ## Initialization -The implementation first applies $T \leftarrow \max(T, 10^{-3})$ for -$T \in \{T_R, T_A, T_E, T_F\}$. This should be replaced with a structural template change in the future. The machine initializes $E_{fd}$ first. IEEET1 reads that value, along with any attached $\omega$ and $V_S$, and solves the steady-state algebraic chain so all residuals vanish with @@ -246,9 +266,9 @@ with the current input values. All internal derivatives initialize to zero. -## Monitorable Variables +## Monitors -Variable | Units | Description | Note +Monitor | Units | Description | Note ---------|--------|-----------------------------------|------ `efd` | [p.u.] | Field winding voltage | `ksat` | [p.u.] | Scaled-quadratic saturation contribution | $S_B\,q(E_{fd}'-S_A)$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md b/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md index e5eca2ed8..9cfc8b090 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SCRX/README.md @@ -61,6 +61,18 @@ The source multiplier is: 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 ### Internal Variables @@ -100,7 +112,9 @@ $V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -119,7 +133,7 @@ $V_{\mathrm{oel}}$ | [p.u.] | Over-excitation limiter input CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -132,6 +146,10 @@ target and smooth approximation. When $T_B=0$, SCRX bypasses the lead-lag block so $V_{\mathrm{ll}}=e_V$. +### External Equations + +None. + ## Initialization The machine initializes $E_{\mathrm{fd}}$ first. For a standard unsaturated @@ -154,9 +172,9 @@ 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}$. Starts that bind the exciter limit 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}}$ `efd_pre` | [p.u.] | Limited exciter output before source multiplier | $E_{\mathrm{fd}}'$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md index ba79674d6..7aed72c29 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md @@ -23,6 +23,32 @@ 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 $T_A = (T_A/T_B)T_B$ before passing parameters to the model. +All six parameters are required; there are no defaults. + +### Parameter Validation + +Invalid SEXS-PTI parameter sets are rejected by the following checks: + +```math +\begin{aligned} + T_A &\ge 0 \\ + T_B, T_E, K &> 0 \\ + E_{fd}^{\min} &< E_{fd}^{\max} +\end{aligned} +``` + +### Model Derived Parameters + +None. + +## Model Ports + +Name | Port | Init | Description +------|--------|-------|------------ +`bus` | Bus | Known | Terminal bus voltage +`vs` | Input | Known | Optional stabilizer input signal; defaults to zero +`efd` | Output | Known | Required field-voltage output seeded by the machine + ## Model Variables ### Internal Variables @@ -50,7 +76,8 @@ None. Symbol | Units | Description | Note ----------------|--------|----------------------------------------------|----- -$E_C$ | [p.u.] | Compensated machine terminal voltage magnitude | Computed from bus voltage +$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 | Set during initialization $V_S$ | [p.u.] | Stabilizer output | Optional, defaults to zero $V_{OEL}$ | [p.u.] | Over-excitation limiter signal | Constant zero until modeled @@ -58,7 +85,15 @@ $V_{UEL}$ | [p.u.] | Under-excitation limiter signal | Consta ## Model Equations -### Differential Equations +Define the compensated terminal voltage magnitude for readability: + +```math +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}$ @@ -84,7 +119,7 @@ so that $\dot E_{fd}$ can be written in piecewise form compactly. 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 Equations +#### Algebraic ```math \begin{aligned} @@ -92,6 +127,10 @@ In simulation the piecewise form above is replaced with a smooth approximation w \end{aligned} ``` +### External Equations + +None. + ## Initialization The generator initializes the EFD signal first. SEXS-PTI then reads that value @@ -99,7 +138,6 @@ as $E_{fd,0}$ and assumes steady state with $V_S=V_{OEL}=V_{UEL}=0$: ```math \begin{aligned} -E_C &= \sqrt{V_r^2+V_i^2} \\ 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} @@ -107,3 +145,9 @@ V_{ref} &= E_C + V_{tr,0} ``` All derivatives initialize to zero. + +## Monitors + +Monitor | Units | Description | Note +--------|--------|----------------------|------ +`efd` | [p.u.] | Field-voltage output | $E_{fd}$ diff --git a/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md b/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md index f4f7c9110..d0b0f3e38 100644 --- a/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md @@ -155,7 +155,7 @@ $V_{\mathrm{resp}}^{\max}$, and $s^{\mathrm{valve}}$ are defined under ``` CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) -and [`min`](../../../../CommonMath.md#min) targets and smooth approximations. +and [`min`](../../../../CommonMath.md#minimum) targets and smooth approximations. ### External Equations @@ -235,9 +235,9 @@ 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 `xvalve` | [p.u.] | Fuel-valve state | $x_V$; component base @@ -270,4 +270,4 @@ $\mu$, ``` 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..d3d29c55b 100644 --- a/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md @@ -94,6 +94,18 @@ The component base and flag complements are: \end{aligned} ``` +## 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 @@ -150,7 +162,9 @@ $\omega$ | [p.u.] | Machine speed deviation ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -164,7 +178,7 @@ $\omega$ | [p.u.] | Machine speed deviation 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) \\ @@ -177,7 +191,7 @@ $\omega$ | [p.u.] | Machine speed deviation CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -213,7 +227,7 @@ target and smooth approximation. ``` CommonMath defines helper targets and smooth approximations for -[clamp and min](../../../../CommonMath.md#derived-functions). +[clamp](../../../../CommonMath.md#clamp) and [min](../../../../CommonMath.md#minimum). 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 @@ -221,6 +235,10 @@ 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 @@ -276,9 +294,9 @@ 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 +## Monitors -Output | Units | Description | Note +Monitor | Units | Description | Note ---------------- | -------- | ------------------------------------- | ----------------------- `pmech` | [p.u.] | Mechanical-power output | $P_m$ `pelec_meas` | [p.u.] | Measured electrical power | State 1 diff --git a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md index 31330168e..bd92bdc8c 100644 --- a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md @@ -56,7 +56,7 @@ HYGOV parameter sets are rejected by the following checks: T_r, T_f, T_g, T_w, T_{\mathrm{np}} &\ge 0 \\ R_{\mathrm{temp}} - &\ne 0 \\ + &> 0 \\ T_n &\ge 0 \\ V_{\mathrm{elm}} @@ -98,7 +98,7 @@ raised to that floor in place, so every equation below uses the raised value: &\leftarrow \max\!\left(T_x,\epsilon_T\right), \quad x\in\{r,f,g,w,\mathrm{np}\} \\ k_{\mathrm{base}} - &= \dfrac{S^\mathrm{sys}}{T^\mathrm{rate}} \\ + &= \dfrac{S^\mathrm{sys}}{10^6\,T^\mathrm{rate}} \\ k_n &= \dfrac{T_n}{T_{\mathrm{np}}} \\ N_{\mathrm{GV}}(x) @@ -114,9 +114,10 @@ raised to that floor in place, so every equation below uses the raised value: \end{aligned} ``` -Multiplying by $k_\mathrm{base}$ converts system base to component base. +Multiplying by $k_\mathrm{base}$ converts system base to component base; +$S^\mathrm{sys}$ is the system power base in VA. -CommonMath defines the [`linseg`](../../../../CommonMath.md#linseg) helper +CommonMath defines the [`linseg`](../../../../CommonMath.md#linear-segment) helper used by $N_{\mathrm{GV}}$. ## Model Ports @@ -176,7 +177,9 @@ $P^\mathrm{aux}$ | [p.u.] | Known | Auxiliary power input | Optional si ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential The effective desired-gate response limits $G_{\mathrm{resp}}^{\min}$ and $G_{\mathrm{resp}}^{\max}$ and the effective @@ -211,7 +214,7 @@ dam head $H_{\mathrm{dam}}^{\mathrm{eff}}$ are resolved during initialization. CommonMath defines the [`antiwindup`](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -247,7 +250,12 @@ target and smooth approximation. ``` CommonMath defines helper targets and smooth approximations for -[deadband1 and clamp](../../../../CommonMath.md#derived-functions). +[deadband1](../../../../CommonMath.md#type-i-deadband) and +[clamp](../../../../CommonMath.md#clamp). + +### External Equations + +None. ## Initialization @@ -345,9 +353,9 @@ unchanged. \end{aligned} ``` -## Monitorable Outputs +## Monitors -Output | Units | Description | Note +Monitor | 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) @@ -401,9 +409,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..db382bda9 100644 --- a/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md @@ -102,9 +102,19 @@ The governor component base and nonlinear governor-output curve are: \end{aligned} ``` -CommonMath defines the [linear segment](../../../../CommonMath.md#derived-functions) +CommonMath defines the [linear segment](../../../../CommonMath.md#linear-segment) 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 ### Internal Variables @@ -148,7 +158,9 @@ $P_{\mathrm{aux}}$ | [p.u.] | Auxiliary power input | Sour ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -171,7 +183,7 @@ $P_{\mathrm{aux}}$ | [p.u.] | Auxiliary power input | Sour CommonMath defines the [Anti-Windup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -191,10 +203,17 @@ target and smooth approximation. ``` CommonMath defines helper targets and smooth approximations for -[deadband1, deadband2, clamp, and linseg](../../../../CommonMath.md#derived-functions). +[deadband1](../../../../CommonMath.md#type-i-deadband), +[deadband2](../../../../CommonMath.md#type-ii-deadband), +[clamp](../../../../CommonMath.md#clamp), and +[linseg](../../../../CommonMath.md#linear-segment). 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 @@ -231,9 +250,9 @@ $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 +## Monitors -Output | Units | Description | Note +Monitor | 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}}$ diff --git a/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md b/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md index f18a5d2e5..447a352d2 100644 --- a/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/Tgov1/README.md @@ -89,7 +89,9 @@ For readability, define: g_v=-P_v+\dfrac{P_\mathrm{ref}-\omega}{R}. ``` -### Differential Equations +### Internal Equations + +#### Differential The TGOV1 differential equations, as derived from the model diagram, are @@ -105,7 +107,7 @@ The TGOV1 differential equations, as derived from the model diagram, are CommonMath defines the [Antiwindup](../../../../CommonMath.md#antiwindup) target and smooth approximation. -### Algebraic Equations +#### Algebraic The mechanical-power output is given by @@ -114,6 +116,10 @@ The mechanical-power output is given by +P_t-D_t\omega. ``` +### External Equations + +None. + ## Initialization TGOV1 preserves the machine-provided $P_{m,0}$ and initializes the steady @@ -135,3 +141,7 @@ state in dependency order: ``` Initialization rejects $P_{v,0}$ 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..f1d50742a 100644 --- a/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md +++ b/GridKit/Model/PhasorDynamics/Load/LoadZ/README.md @@ -23,6 +23,12 @@ B &= -\frac{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,6 +74,15 @@ 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 @@ -88,7 +99,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..fefd5c173 100644 --- a/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md +++ b/GridKit/Model/PhasorDynamics/Load/LoadZIP/README.md @@ -29,6 +29,12 @@ B &= \frac{Q_\text{nom}}{V_\text{nom}^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 @@ -57,21 +63,17 @@ 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} @@ -90,6 +92,15 @@ 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 ```math @@ -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/README.md b/GridKit/Model/PhasorDynamics/README.md index 237d024f1..24575473a 100644 --- a/GridKit/Model/PhasorDynamics/README.md +++ b/GridKit/Model/PhasorDynamics/README.md @@ -27,18 +27,33 @@ 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 @@ -46,7 +61,7 @@ We recommend developers follow these steps when adding new component models: - 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 +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 c05d85a0d..f76b07658 100644 --- a/GridKit/Model/PhasorDynamics/SignalNode/README.md +++ b/GridKit/Model/PhasorDynamics/SignalNode/README.md @@ -13,3 +13,53 @@ without owning the producing model. Symbol | Description -------|------------ `signal_id` | Unique identifier for the signal node + +## 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..c0e8a7941 100644 --- a/GridKit/Model/PhasorDynamics/SignalSource/README.md +++ b/GridKit/Model/PhasorDynamics/SignalSource/README.md @@ -1,20 +1,72 @@ -# Constant signal source +# ConstantSignalSource -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 | Default +-------|-------------|------|---------------------------------|-------- +$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..a3fcbaf26 100644 --- a/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md +++ b/GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/README.md @@ -33,7 +33,7 @@ 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 compatibility but are not modeled here. -### Derived Parameters +### Model Derived Parameters ```math \begin{aligned} @@ -45,6 +45,13 @@ a_4 &= A_2 A_4 \end{aligned} ``` +## Model Ports + +Name | Port | Init | Description +---------|--------|-------|------------ +`input` | Input | Known | Required stabilizer input signal +`output` | Output | Known | Limited stabilizer output signal + ## Model Variables ### Internal Variables @@ -70,6 +77,10 @@ $V_{ss}$ | [p.u.] | Limited stabilizer signal (model output) ### External Variables +#### Differential + +None. + #### Algebraic Symbol | Units | Description @@ -78,7 +89,9 @@ $u$ | [p.u.] | Stabilizer input signal ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -92,7 +105,7 @@ $u$ | [p.u.] | Stabilizer input signal \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -105,10 +118,20 @@ $u$ | [p.u.] | Stabilizer input signal ``` The output limiter uses GridKit's smooth -[Clamp](../../../../CommonMath.md#derived-functions). +[Clamp](../../../../CommonMath.md#clamp). + +### 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$. + +## Monitors + +Monitor | Units | Description | Note +--------|--------|---------------------------|------ +`vss` | [p.u.] | Limited stabilizer signal | $V_{ss}$; model output diff --git a/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md b/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md index 6f3ba0cc1..119fc525a 100644 --- a/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md +++ b/GridKit/Model/PhasorDynamics/Stabilizer/PSS1A/README.md @@ -31,7 +31,13 @@ Figure 1: Power system stabilizer PSS1A model. Figure courtesy of [PowerWorld](h - $V_{cl}$ - stabilizer input cutoff threshold, pu (0) +## Model Ports +Name | Port | Init | Description +---------|--------|------|------------ +`input` | Input | TBD | Stabilizer input $u$ selected by $I_{cs}$ +`vct` | Input | TBD | Cutout signal $V_{ct}$ +`output` | Output | TBD | Limited stabilizer output $V_{llout}$ ## Model Variables @@ -68,7 +74,11 @@ $u$ | [p.u.] | Stabilizer input signal | $V_{ct}$ | [p.u.] | Cutout signal (compared to $V_{cl},V_{cu}$) | from the block diagram -### Differential Equations +## Model Equations + +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -81,7 +91,7 @@ $V_{ct}$ | [p.u.] | Cutout signal (compared to $V_{cl},V_{cu}$) | from the block \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -95,3 +105,15 @@ V_{llout} &= \begin{cases} \end{cases} \end{aligned} ``` + +### External Equations + +None. + +## Initialization + +TBD. + +## Monitors + +TBD. diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md index 4150b49a9..3b221d714 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md @@ -43,8 +43,9 @@ $S_\mathrm{mach}$ | [MVA] | Machine power base | 100 | \begin{aligned} G &= \dfrac{R_a}{R_a^2+(X_q'')^2} & B &= -\dfrac{X_q''}{R_a^2+(X_q'')^2}\\ - S_A &= \dfrac{1.2\sqrt{S_{10}/S_{12}} +1}{\sqrt{S_{10}/S_{12}} +1} & - S_B &= \dfrac{1.2\sqrt{S_{10}/S_{12}} -1}{\sqrt{S_{10}/S_{12}} -1} \\ + S_A &= \min\left(\dfrac{1.2\sqrt{S_{10}/S_{12}} +1}{\sqrt{S_{10}/S_{12}} +1}, + \dfrac{1.2\sqrt{S_{10}/S_{12}} -1}{\sqrt{S_{10}/S_{12}} -1}\right) & + S_B &= \dfrac{S_{12}}{(S_A-1.2)^2} \\ X_{d1} &= X_d-X_d' & X_{q1} &= X_q-X_q' \\ X_{d2} &= X_d'-X_\ell & X_{q2} &= X_q'-X_\ell\\ X_{d3} &= (X_d'-X_d'')/X_{d2}^2 & X_{q3} &= (X_q'-X_q'')/X_{q2}^2 \\ @@ -56,8 +57,19 @@ $S_\mathrm{mach}$ | [MVA] | Machine power base | 100 | \end{aligned} ``` +When $S_{12}=0$, $S_A=S_B=0$. + System bases are taken from the system at initialization. +## Model Ports + +Name | Port | Init | Description +--------|--------|---------|------------ +`bus` | Bus | Known | Terminal bus voltage and current-balance residuals +`pmech` | Input | Unknown | System-base mechanical-power input; converted to machine base internally and held constant when unconnected +`efd` | Input | Unknown | Machine-base field-voltage input; held constant when unconnected +`speed` | Output | Known | Machine speed-deviation output + ## Model Variables ### Internal Variables @@ -68,25 +80,25 @@ Symbol | Units | Description | Note ----------|--------|-----------------------------------|------- $\delta$ | [rad] | Machine internal rotor angle | $\omega$ | [p.u.] | Machine Speed Deviation | Optionally read by governor or stabilizer component +$E'_q$ | [p.u.] | Quadrature axis transient flux | $\psi'_d$ | [p.u.] | Direct axis subtransient flux | $\psi'_q$ | [p.u.] | Quadrature axis subtransient flux | $E'_d$ | [p.u.] | Direct axis transient flux | -$E'_q$  | [p.u.] | Quadrature axis subtransient flux | #### Algebraic Symbol | Units | Description | Note ------------|--------|--------------------------------- | ------ -$V_d$ | [p.u.] | Machine internal voltage, d-axis | -$V_q$ | [p.u.] | Machine internal voltage, q-axis | -$I_d$ | [p.u.] | Terminal current, d-axis | -$I_q$ | [p.u.] | Terminal current, q-axis | -$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Read by bus and optionally by controllers -$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Read by bus and optionally by controllers $\psi''_q$ | [p.u.] | Total q-axis subtransient flux | $\psi''_d$ | [p.u.] | Total d-axis subtransient flux | $\psi''$   | [p.u.] | Machine total subtransient flux | -$T_{e}$ | [p.u.] | Electrical torque | $k_{sat}$ | [p.u.] | Saturation coefficient | +$V_d$ | [p.u.] | Machine internal voltage, d-axis | +$V_q$ | [p.u.] | Machine internal voltage, q-axis | +$T_e$ | [p.u.] | Electrical torque | +$I_d$ | [p.u.] | Terminal current, d-axis | +$I_q$ | [p.u.] | Terminal current, q-axis | +$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Machine base; converted to system base for the bus and monitors +$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Machine base; converted to system base for the bus and monitors ### External Variables @@ -98,18 +110,26 @@ Symbol | Units | Description | Note ---------|--------|---------------------------------| ------ $V_r$ | [p.u.] | Terminal voltage, real component on network reference frame | owned by bus object $V_i$ | [p.u.] | Terminal voltage, imaginary component on network reference frame | owned by bus object -$P_{m}$ | [p.u.] | Mechanical power from the prime mover | Owned by governor, constant if no governor is connected to the machine -$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by exciter, constant if no exciter is connected to the machine +$P_{m}$ | [p.u.] | Mechanical power from the prime mover | System-base signal; converted to machine base internally and held constant if unconnected +$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Machine-base signal; held constant if unconnected ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ``` math \begin{aligned} \dot\delta &= \omega \cdot 2\pi f_\mathrm{base} \\ \dot\omega &= \dfrac{1}{2H}\left(\dfrac{P_{m}-D\omega}{1+\omega} - T_{elec}\right)\\ + \dot{E}'_{q} &= \dfrac{1}{T'_{d0}} + \left( + E_{fd}-E'_{q}-X_{d1} + (I_{d}+X_{d3}(E'_{q}-\psi'_{d}-X_{d2}I_{d})) + -\psi''_{d}k_{sat} + \right)\\ \dot{\psi}'_{d} &= \dfrac{1}{T''_{d0}}(E'_{q}-\psi'_{d}-X_{d2}I_{d})\\ \dot{\psi}'_{q} &= \dfrac{1}{T''_{q0}}(E'_{d}-\psi'_{q}+X_{q2}I_{q})\\ \dot{E}'_{d} &= \dfrac{1}{T'_{q0}} @@ -117,35 +137,47 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by (I_{q}-X_{q3}(E'_{d}-\psi'_{q}+X_{q2}I_{q})) + X_{qd}\psi''_{q}k_{sat} \right) \\ - \dot{E}'_{q} &= \dfrac{1}{T'_{d0}} - \left( - E_{fd}-E'_{q}-X_{d1} - (I_{d}+X_{d3}(E'_{q}-\psi'_{d}-X_{d2}I_{d})) - -\psi''_{d}k_{sat} - \right)\\ \end{aligned} ``` -### Algebraic Equations -Note that for implementation purposes, some of these equations may be simplified into functions and the internal variables eliminated. Nevertheless, for modeling clarity and conformance to typical practice, the full equations are given here. +#### Algebraic + ``` math \begin{aligned} 0 &= -\psi''_{q} -E'_{d}X_{q5} - \psi'_{q}X_{q4} \\ 0 &= -\psi''_{d} +E'_{q}X_{d5} + \psi'_{d}X_{d4}\\ 0 &= -\psi'' +\sqrt{(\psi''_{d})^2+(\psi''_{q})^2} \\ + 0 &= -k_{sat} + S_B q(\psi''-S_A) \\ 0 &= -V_{d} -\psi''_{q}(1+\omega)\\ 0 &= -V_{q} +\psi''_{d}(1+\omega)\\ 0 &= -T_{elec} +(\psi''_{d} - I_dX_d'')I_q-(\psi''_{q} - I_qX_d'')I_d \\ - 0 &= -k_{sat} + S_B q(\psi''-S_A) \\ 0 &= -I_d + I_r \sin(\delta) - I_i \cos(\delta) \\ 0 &= -I_q + I_r \cos(\delta) + I_i \sin(\delta) \\ - 0 &= -I_r + G (V_d \sin(\delta) + V_q \cos(\delta) - V_r) - B (V_d \cos(\delta) + V_q \sin(\delta) - V_i) \\ - 0 &= -I_i + B (V_d \sin(\delta) + V_q \cos(\delta) - V_r) + G (V_d \cos(\delta) + V_q \sin(\delta) - V_i) + 0 &= -I_r + G (V_d \sin(\delta) + V_q \cos(\delta) - V_r) - B (-V_d \cos(\delta) + V_q \sin(\delta) - V_i) \\ + 0 &= -I_i + B (V_d \sin(\delta) + V_q \cos(\delta) - V_r) + G (-V_d \cos(\delta) + V_q \sin(\delta) - V_i) \end{aligned} ``` CommonMath defines the primitive -[quadratic ramp](../../../../CommonMath.md#primitives) $q$. +[quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $q$. + +### External Equations + +The machine-base terminal currents are converted to system base and added to +the connected bus residuals. Here $I_r^{\mathrm{mach}}\equiv I_r$ and +$I_i^{\mathrm{mach}}\equiv I_i$ denote the internal machine-base currents, and +$S_\mathrm{sys,VA}$ is the system power base in volt-amperes: + +```math +\begin{aligned} +I_r^{\mathrm{bus}} + &\leftarrow I_r^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_r^{\mathrm{mach}} \\ +I_i^{\mathrm{bus}} + &\leftarrow I_i^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_i^{\mathrm{mach}}. +\end{aligned} +``` ## Initialization @@ -178,14 +210,14 @@ With $\delta$ known, the rotor-frame currents, voltages, flux states, field voltage, and mechanical power follow directly from the steady-state model equations above. -## Model Outputs - -Symbol | Units | Description | Note ------------|--------|-----------------------------------|------ -$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Oriented leaving the machine, system base -$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Oriented leaving the machine, system base -$P$ | [p.u.] | Active power, $V_rI_r+V_iI_i$ | Oriented leaving the machine, system base -$Q$ | [p.u.] | Reactive power, $V_iI_r-V_rI_i$ | Oriented leaving the machine, system base -$\delta$ | [rad] | Machine internal rotor angle | -$\omega$ | [p.u.] | Machine speed deviation | $\omega=0$ at synchronous speed -$\text{speed}$ | [p.u.] | Per-unit machine speed | $1+\omega$ +## Monitors + +Monitor | Units | Description | Note +--------|-------|--------------------------------------------------------------------|------ +`ir` | [p.u.] | Terminal current, real component $I_r$ in the network frame | Oriented leaving the machine; system base +`ii` | [p.u.] | Terminal current, imaginary component $I_i$ in the network frame | Oriented leaving the machine; system base +`p` | [p.u.] | Active power $P=V_rI_r+V_iI_i$ | Oriented leaving the machine; system base +`q` | [p.u.] | Reactive power $Q=V_iI_r-V_rI_i$ | Oriented leaving the machine; system base +`delta` | [rad] | Machine internal rotor angle $\delta$ | +`omega` | [p.u.] | Machine speed deviation $\omega$ | $\omega=0$ at synchronous speed +`speed` | [p.u.] | Per-unit machine speed | $1+\omega$ diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md index ab2c0b4e1..247b81e44 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md @@ -44,8 +44,9 @@ $S_\mathrm{mach}$ | [MVA] | Machine power base | 100 | \begin{aligned} G &= \dfrac{R_a}{R_a^2+(X_d'')^2} & B &= -\dfrac{X_d''}{R_a^2+(X_d'')^2}\\ - S_A &= \dfrac{1.2\sqrt{S_{10}/S_{12}} +1}{\sqrt{S_{10}/S_{12}} +1} & - S_B &= \dfrac{1.2\sqrt{S_{10}/S_{12}} -1}{\sqrt{S_{10}/S_{12}} -1} \\ + S_A &= \min\left(\dfrac{1.2\sqrt{S_{10}/S_{12}} +1}{\sqrt{S_{10}/S_{12}} +1}, + \dfrac{1.2\sqrt{S_{10}/S_{12}} -1}{\sqrt{S_{10}/S_{12}} -1}\right) & + S_B &= \dfrac{S_{12}}{(S_A-1.2)^2} \\ X_{d1} &= X_d-X_d' & X_{q2} &= X_q-X_d'' \\ X_{d2} &= X_d'-X_\ell & X_{d3} &= (X_d'-X_d'')/X_{d2}^2 \\ X_{d4} &= (X_d'-X_d'')/X_{d2} & X_{d5} &= (X_d''-X_\ell)/X_{d2} \\ @@ -54,8 +55,19 @@ $S_\mathrm{mach}$ | [MVA] | Machine power base | 100 | \end{aligned} ``` +When $S_{12}=0$, $S_A=S_B=0$. + System bases are taken from the system at initialization. +## Model Ports + +Name | Port | Init | Description +--------|--------|---------|------------ +`bus` | Bus | Known | Terminal bus voltage and current-balance residuals +`pmech` | Input | Unknown | System-base mechanical-power input; converted to machine base internally and held constant when unconnected +`efd` | Input | Unknown | Machine-base field-voltage input; held constant when unconnected +`speed` | Output | Known | Machine speed-deviation output + ## Model Variables ### Internal Variables @@ -80,8 +92,8 @@ $V_q$ | [p.u.] | Machine internal voltage, q-axis | $T_e$ | [p.u.] | Electrical torque | $I_d$ | [p.u.] | Terminal current, d-axis | $I_q$ | [p.u.] | Terminal current, q-axis | -$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Read by bus and optionally by controllers -$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Read by bus and optionally by controllers +$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Machine base; converted to system base for the bus and monitors +$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Machine base; converted to system base for the bus and monitors ### External Variables @@ -93,12 +105,15 @@ Symbol | Units | Description | No ---------|--------|---------------------------------------------------------| ------ $V_r$ | [p.u.] | Terminal voltage, real component on network reference frame | owned by bus object $V_i$ | [p.u.] | Terminal voltage, imaginary component on network reference frame | owned by bus object -$P_m$ | [p.u.] | Mechanical power from the prime mover | Owned by governor, constant if no governor is connected to the machine -$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by exciter, constant if no exciter is connected to the machine +$P_m$ | [p.u.] | Mechanical power from the prime mover | System-base signal; converted to machine base internally and held constant if unconnected +$E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Machine-base signal; held constant if unconnected ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential + ``` math \begin{aligned} \dot\delta &= \omega \cdot 2\pi f_\mathrm{base} \\ @@ -115,7 +130,8 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Ow \end{aligned} ``` -### Algebraic Equations +#### Algebraic + ``` math \begin{aligned} 0 &= -\psi''_d + E'_qX_{d5}+\psi'_dX_{d4}\\ @@ -131,7 +147,25 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Ow ``` CommonMath defines the primitive -[quadratic ramp](../../../../CommonMath.md#primitives) $q$. +[quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $q$. + +### External Equations + +The machine-base terminal currents are converted to system base and added to +the connected bus residuals. Here $I_r^{\mathrm{mach}}\equiv I_r$ and +$I_i^{\mathrm{mach}}\equiv I_i$ denote the internal machine-base currents, and +$S_\mathrm{sys,VA}$ is the system power base in volt-amperes: + +```math +\begin{aligned} +I_r^{\mathrm{bus}} + &\leftarrow I_r^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_r^{\mathrm{mach}} \\ +I_i^{\mathrm{bus}} + &\leftarrow I_i^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_i^{\mathrm{mach}}. +\end{aligned} +``` ## Initialization @@ -153,28 +187,28 @@ steady-state GENSAL equations. E'_q &= \psi'_d+X_{d2}I_d\\ k_{sat} &= S_B q(E'_q-S_A)\\ T_e &= (\psi''_d-I_dX_d'')I_q-(\psi''_q-I_qX_d'')I_d\\ - P_m &= T_e\\ + P_m &= \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} T_e\\ E_{fd} &= E'_q+X_{d1}(I_d+X_{d3}(E'_q-\psi'_d-X_{d2}I_d))+E'_q k_{sat} \end{aligned} ``` -## Model Outputs - -Symbol | Units | Description | Note ------------|--------|-----------------------------------|------ -$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Oriented leaving the machine, system base -$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Oriented leaving the machine, system base -$P$ | [p.u.] | Active power, $V_rI_r+V_iI_i$ | Oriented leaving the machine, system base -$Q$ | [p.u.] | Reactive power, $V_iI_r-V_rI_i$ | Oriented leaving the machine, system base -$\delta$ | [rad] | Machine internal rotor angle | -$\omega$ | [p.u.] | Machine speed deviation | $\omega=0$ at synchronous speed -$\text{speed}$ | [p.u.] | Per-unit machine speed | $1+\omega$ -$E'_q$ | [p.u.] | Quadrature axis transient flux | Machine base -$\psi'_d$ | [p.u.] | Direct axis transient flux | Machine base -$\psi''_q$ | [p.u.] | Total q-axis subtransient flux | Machine base -$\psi''_d$ | [p.u.] | Total d-axis subtransient flux | Machine base -$V_d$ | [p.u.] | Machine internal voltage, d-axis | Machine base -$V_q$ | [p.u.] | Machine internal voltage, q-axis | Machine base -$T_e$ | [p.u.] | Electrical torque | Machine base -$I_d$ | [p.u.] | Terminal current, d-axis | Machine base -$I_q$ | [p.u.] | Terminal current, q-axis | Machine base +## Monitors + +Monitor | Units | Description | Note +--------|-------|--------------------------------------------------------------------|------ +`ir` | [p.u.] | Terminal current, real component $I_r$ in the network frame | Oriented leaving the machine; system base +`ii` | [p.u.] | Terminal current, imaginary component $I_i$ in the network frame | Oriented leaving the machine; system base +`p` | [p.u.] | Active power $P=V_rI_r+V_iI_i$ | Oriented leaving the machine; system base +`q` | [p.u.] | Reactive power $Q=V_iI_r-V_rI_i$ | Oriented leaving the machine; system base +`delta` | [rad] | Machine internal rotor angle $\delta$ | +`omega` | [p.u.] | Machine speed deviation $\omega$ | $\omega=0$ at synchronous speed +`speed` | [p.u.] | Per-unit machine speed | $1+\omega$ +`Eqp` | [p.u.] | Quadrature-axis transient flux $E'_q$ | Machine base +`psidp` | [p.u.] | Direct-axis transient flux $\psi'_d$ | Machine base +`psiqpp` | [p.u.] | Total q-axis subtransient flux $\psi''_q$ | Machine base +`psidpp` | [p.u.] | Total d-axis subtransient flux $\psi''_d$ | Machine base +`vd` | [p.u.] | Machine internal voltage, d-axis $V_d$ | Machine base +`vq` | [p.u.] | Machine internal voltage, q-axis $V_q$ | Machine base +`te` | [p.u.] | Electrical torque $T_e$ | Machine base +`id` | [p.u.] | Terminal current, d-axis $I_d$ | Machine base +`iq` | [p.u.] | Terminal current, q-axis $I_q$ | Machine base diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md index 7c0dc2006..ff15dc0a9 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md @@ -24,6 +24,14 @@ $S_\mathrm{mach}$ | [MVA] | machine power base | - $f_\mathrm{base} = f_\mathrm{sys} ~~~$ frequency base taken from the system at initialization - $S_\mathrm{mach,VA} = 10^6 S_\mathrm{mach} ~~~$ derived machine base used for machine-base/system-base conversions +## Model Ports + +Name | Port | Init | Description +------------------|-------|-------|------------ +`bus` | Bus | Known | Terminal bus voltage and current-balance residuals +`exciter_signal` | Input | N/A | Accepted by the parser but not wired; $E_p$ is a fixed setpoint +`governor_signal` | Input | N/A | Accepted by the parser but not wired; $P_m$ is a fixed setpoint +
## Model Variables @@ -35,15 +43,15 @@ $S_\mathrm{mach}$ | [MVA] | machine power base | Symbol | Units | Description | Note ------------|---------|---------------------|---------------------- $\delta$ | [rad] | machine power angle | -$\omega$ | [p.u] | machine speed deviation | Optionally read by a governor or a stabilizer component +$\omega$ | [p.u] | machine speed deviation | #### Algebraic Symbol | Units | Description | Note --------|--------|-------------------------------------|------------- $T_{e}$ | [p.u.] | electrical torque | -$I_r$ | [p.u.] | machine real injection current | read by bus -$I_i$ | [p.u.] | machine imaginary injection current | read by bus +$I_r$ | [p.u.] | machine real injection current | Machine base; converted to system base for the bus and monitors +$I_i$ | [p.u.] | machine imaginary injection current | Machine base; converted to system base for the bus and monitors Note: All three can be expressed as a function called by the model equations. We add these as variables as they are needed for outputs. @@ -66,15 +74,19 @@ Symbol | Units | Description | Note -------|---------|-------------------------------|---------------------- $V_r$ | [p.u.] | machine bus real voltage | owned by a bus object $V_i$ | [p.u.] | machine bus imaginary voltage | owned by a bus object -$P_m$ | [p.u.] | mechanical power input | owned by governor, constant if no governor is connected to the machine -$E_p$ | [p.u.] | field winding voltage | owned by exciter, constant if no exciter is connected to the machine + +The mechanical power $P_m$ and internal transient-emf magnitude $E_p$ are +fixed setpoints computed during initialization; they are neither solver +variables nor connected signals.
## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -83,7 +95,7 @@ $E_p$ | [p.u.] | field winding voltage | owned by exciter, constant if \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -96,6 +108,24 @@ As noted earlier, all three algebraic equations can be expressed as functions and substituted directly in the component and bus equations, respectively. We use redundant variables for modeling convenience. +### External Equations + +The machine-base terminal currents are converted to system base and added to +the connected bus residuals. Here $I_r^{\mathrm{mach}}\equiv I_r$ and +$I_i^{\mathrm{mach}}\equiv I_i$ denote the internal machine-base currents, and +$S_\mathrm{sys,VA}$ is the system power base in volt-amperes: + +```math +\begin{aligned} +I_r^{\mathrm{bus}} + &\leftarrow I_r^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_r^{\mathrm{mach}} \\ +I_i^{\mathrm{bus}} + &\leftarrow I_i^{\mathrm{bus}} + + \dfrac{S_\mathrm{mach,VA}}{S_\mathrm{sys,VA}} I_i^{\mathrm{mach}}. +\end{aligned} +``` +
## Initialization @@ -164,13 +194,14 @@ P_{m} &= T_{e} With this, we initialize the machine at a steady state. -## Model Outputs +## Monitors -Symbol | Units | Description | Note ------------|--------|-----------------------------------|------ -$I_r$ | [p.u.] | Terminal current, real component on network reference frame | Oriented leaving the machine, system base -$I_i$ | [p.u.] | Terminal current, imaginary component on network reference frame | Oriented leaving the machine, system base -$P$ | [p.u.] | Active power, $V_rI_r+V_iI_i$ | Oriented leaving the machine, system base -$Q$ | [p.u.] | Reactive power, $V_iI_r-V_rI_i$ | Oriented leaving the machine, system base -$\delta$ | [rad] | Machine internal rotor angle | -$\omega$ | [p.u.] | Machine speed deviation | $\omega=0$ at synchronous speed +Monitor | Units | Description | Note +--------|-------|--------------------------------------------------------------------|------ +`ir` | [p.u.] | Terminal current, real component $I_r$ in the network frame | Oriented leaving the machine; system base +`ii` | [p.u.] | Terminal current, imaginary component $I_i$ in the network frame | Oriented leaving the machine; system base +`p` | [p.u.] | Active power $P=V_rI_r+V_iI_i$ | Oriented leaving the machine; system base +`q` | [p.u.] | Reactive power $Q=V_iI_r-V_rI_i$ | Oriented leaving the machine; system base +`delta` | [rad] | Machine internal rotor angle $\delta$ | +`omega` | [p.u.] | Machine speed deviation $\omega$ | $\omega=0$ at synchronous speed +`speed` | [p.u.] | Per-unit machine speed | $1+\omega$ diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md index e3d4e6d64..1d220907c 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/README.md @@ -33,14 +33,14 @@ To convert to the network base, the following must be performed. \end{aligned} ``` -For example, say the terminal impedence is $Z=0.05$ in per-unit on the -machine's base of $S_{base,machine}=50$ MW, and the system base is -$S_{base,sys}=100$ MW. Then the terminal impedance on the system +For example, say the terminal impedance is $Z=0.05$ in per-unit on the +machine's base of $S_{base,machine}=50$ MVA, and the system base is +$S_{base,sys}=100$ MVA. Then the terminal impedance on the system base is calculated as follows. ``` math \begin{aligned} - Z_{sys} = 0.05\dfrac{100 \text{MW}}{50 \text{MW}} = 0.1 + Z_{sys} = 0.05\dfrac{100 \text{MVA}}{50 \text{MVA}} = 0.1 \end{aligned} ``` 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}