From 559b60440bd69e5bf40013dddc7abd8112599d2c Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 13:11:39 -0500 Subject: [PATCH 1/8] propgation impl --- .../EMT/Operators/Shift/Propagation/README.md | 30 +++------- docs/Figures/EMT/Propagation/diagram.tex | 55 ++++++++++--------- 2 files changed, 36 insertions(+), 49 deletions(-) diff --git a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md index 2fad25be4..7ef365dfd 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=0}^M \mathbf{H}^\mathrm{mps}_\text{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/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} From faf75bedb13a164bf1ccaff8569098d687da9703 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 13:17:07 -0500 Subject: [PATCH 2/8] rendered diagram --- docs/Figures/EMT/Propagation/diagram.png | Bin 80574 -> 96006 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/Figures/EMT/Propagation/diagram.png b/docs/Figures/EMT/Propagation/diagram.png index 3af078f49bcb35a10d249c46fc6d1d1e3312a333..ecaa1b43b99139c09a0c7c2792f40573056c80c1 100644 GIT binary patch literal 96006 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 K8Z%{y?|%VEScMe; literal 80574 zcmeFa2~^JQ`Zj!?;&dnMQ;!J|11XoT{|fh4vNC=o%`)Sf2(yf z(YiRD-{(}tc;)V+Plo4GT-p~LEefYOs<|kcX5&)cui}g2JPO%&?)0GBrEuk?^zlU( zuk3txlp{%+W!re4{Aq33Mvk$y>9HrhQl-ylDGG~*NzXravOdT4+sJo&=N(fSZKs+B zzch&5EiupApg=D4$3w<{KK;)>Qz$YU77G3S%)_sj+`!C3hUb4?`k&SKX$_SBv5o(6 zhyUNX1K%A=L;t?m_Z>rHW%uQmvx?hvPglOYxcF_06(9HGWBESGQ-^PDJmgnc6tzI+$AG zo;XBD*=sXrRa(0xzG;o@)^F0VOFWa+*!PqTi!&3$u7NXUW1 zw(m1+J5Qwq2{+suNcu<_9W2^fVsrNFRF}{@tj@D)bBSRgEy2JF@mR%3zm$l=7OVLs zG3n`I@lQ{gnkse1X-sImd-o2@c3QvVWJrM0uM>Z^E2YXOCsf3u?upUc&!0cz3XdJTf9B`f^~dPM zvq?G*Hu*}|rI=QgmX=CS6hD0UaB6Dm!w2pAFXYxX&MSzw?fmdAM8fVv+@UEa-k%Hf zRy|w4KF4MJL%i;EM9bmKvt2>Lrp=tRYA=5-HHG4!9j{##cc`MGVjwkF+@davRpRW3 zo5Ze7zlFqRgA|>^InJZ<>@GIng@lELmo8lzZNFCI!or^yN#PjQ(b4&iU4vmhe8^?` zT&_*i{^w3n8n$R8RASfAu{jv&EHYXqyHMXBXf3WXz1G2s~>+|FNg7lEDE#mrcImN zrY1TQb6p2o-wip|a{Rm|O8P!!zt@W>%r@g)smqrxy~cXh);3-*y?o=ZcZfCM{+~S3 zj=k1n_v?EL=wZhzyK2%0uG-xa&^@v8=iA+#ulLSAUN$z=na`e}pPiv6c=y)=aIoWI z?r6ro_hFZonhMGDX8P?l5%Stoi~5|cbtkbvzxGwee6RhiEp4xsOS8BgjNX6xS9rh9 zy+Yr;$YFYNIG`5A5_WiAaq%e=mc>y2Wz}Zte11c1=2NKi{t(JUl4>cL?`~lKYk*5 zzj#v!g2kVIPmxvl+YBij{=famzu=_+Wy*El#Y}=MY;0^28w20|x?f5GGj{%&|68L^ zf;9b=`p0kWe>3;jbv*yX7f?9z$}0Ud{a&Tb3M=@3y+V<>{a@p5 ze}CiuCGJG#=FsdIa*WqrLl*hkwQDE-He&j)my53pAYV^2x23m*KK&J?MQE066{~euM(00f z4ZmN`KNuwp#a;QNxp~5VzGI$dW@aR?i%RDimeEi~Z*I6kN6fe2+&y+%5@D_@A;s$T z4-@!H`}Hb&^0MX2QcgGI z^uLG2{7HiTVfwm$8}_&_ejW9DwejcM|Fy>aPkxJP=SD}49C>?7fEtVV4H<5_UCb z^6$xcFL@~zwE5Uy_kE?tJ{gDA+EyJ#ktj?zz7qx7V(bcV(l0S5HqW71K3eo%tw-i}XbAE6L#+>*j(RCo3MJ zmQ%UA{T&VH;F-=Hs9sF9cTxz7@+?)k7CDP}WNGb#Ie(6u!p-@kufx#;2= z^R&j4D*dfA(Fc=F%KSK$@G-I{m6~eIe}2X%+i5swuw3bWVybzq_{s7Ocdy@icUQ!~ zuGaRV?9sO35Zz~|HlgYrjui?c7YMnECqAk&fMa+=?XDP=q&$KFGvM--~@x_$b7lrST%uL*+Y$^nxBkomIX$ zBh5F}>RiXoF8ss0;}0eo9zXs-okuxD+_t4KV1DE5J6ny5Cx`2$$HrO$4W_zM>u1(J z@P}7D&n>U25)M#__ zo111YFFtb~?Jr}BQVse1_~?b5ikXhn4`PKtWcQ!--X?X4NO?r{30uc*<*q zPRNx)UckVpLB~yw; zI#G0cUotB*vl!f8a_#BQ$tQ2#zI`w`8;)%B_SV-wJ{If&H+mQu+0xu>GA|3UYQb{0 zji1f27^sSdJRV=Ud^xQ($n^ZHt5=sulBneF#d+`XV|6A

JGVoK~#%JWqs%uFB|} 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 From b3c5f3ee75c5bfd147a0990b2947da21fafc3a68 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 16:05:37 -0500 Subject: [PATCH 3/8] spelling and reference errors --- .../Model/EMT/Operators/Shift/Propagation/README.md | 2 +- .../Model/PhasorDynamics/Controller/REECB/README.md | 10 ++++++---- .../Model/PhasorDynamics/Controller/REPCA/README.md | 7 ++++--- .../Model/PhasorDynamics/Converter/REECA/README.md | 7 +++++-- .../Model/PhasorDynamics/Converter/REGCA/README.md | 6 ++++-- .../Model/PhasorDynamics/Exciter/ESAC6A/README.md | 4 ++-- .../Model/PhasorDynamics/Exciter/ESDC1A/README.md | 10 +++++----- .../Model/PhasorDynamics/Exciter/ESDC2A/README.md | 4 ++-- .../Model/PhasorDynamics/Exciter/ESST4B/README.md | 3 ++- .../Model/PhasorDynamics/Exciter/EXAC1/README.md | 2 +- .../Model/PhasorDynamics/Exciter/EXAC2/README.md | 5 +++-- .../Model/PhasorDynamics/Exciter/EXDC1/README.md | 2 +- .../Model/PhasorDynamics/Exciter/EXPIC1/README.md | 4 ++-- .../Model/PhasorDynamics/Exciter/IEEET1/README.md | 2 +- .../Model/PhasorDynamics/Governor/GASTPTI/README.md | 4 ++-- .../Model/PhasorDynamics/Governor/GGOV1/README.md | 4 ++-- .../Model/PhasorDynamics/Governor/HYGOV/README.md | 5 +++-- .../Model/PhasorDynamics/Governor/IEEEG1/README.md | 7 +++++-- GridKit/Model/PhasorDynamics/INPUT_FORMAT.md | 2 +- GridKit/Model/PhasorDynamics/README.md | 6 +++--- .../PhasorDynamics/Stabilizer/IEEEST/README.md | 2 +- .../SynchronousMachine/GENROU/README.md | 13 ++++++++----- .../SynchronousMachine/GENSAL/README.md | 9 ++++++--- .../PhasorDynamics/SynchronousMachine/README.md | 8 ++++---- 24 files changed, 74 insertions(+), 54 deletions(-) diff --git a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md index 7ef365dfd..374d203ca 100644 --- a/GridKit/Model/EMT/Operators/Shift/Propagation/README.md +++ b/GridKit/Model/EMT/Operators/Shift/Propagation/README.md @@ -7,7 +7,7 @@ delay per mode, and a fitted output factor while preserving the input units. ```math \begin{aligned} \mathbf{H}(s) - &= \sum_{m=0}^M \mathbf{H}^\mathrm{mps}_\text{m}(s) e^{-s\tau_m} + &= \sum_{m=1}^M \mathbf{H}^\mathrm{mps}_m(s) e^{-s\tau_m} \end{aligned} ``` diff --git a/GridKit/Model/PhasorDynamics/Controller/REECB/README.md b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md index 0dcf468b8..0d26657ba 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 @@ -408,7 +410,7 @@ For $\ell<0 Date: Thu, 27 Aug 2026 16:30:24 -0500 Subject: [PATCH 4/8] small consistancy --- GridKit/Model/PhasorDynamics/Branch/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Branch/README.md b/GridKit/Model/PhasorDynamics/Branch/README.md index 97256c5aa..8fcd5ce86 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} @@ -169,8 +169,8 @@ 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. +evaluated from the connected bus voltages. Parameter verification enforces the +conditions in [Parameter Validation](#parameter-validation). ## Model Outputs From e5698a9c9a156eb91854b900924992bf660d41f0 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 20:09:51 -0500 Subject: [PATCH 5/8] README consistnancy and minor correctiions --- GridKit/Model/PhasorDynamics/Branch/README.md | 23 ++++- GridKit/Model/PhasorDynamics/Bus/README.md | 95 +++++++++++++++++-- .../Model/PhasorDynamics/BusFault/README.md | 52 +++++++++- .../BusToSignalAdapter/README.md | 83 +++++++++++++--- .../PhasorDynamics/Controller/REECB/README.md | 4 +- .../PhasorDynamics/Controller/REPCA/README.md | 4 +- .../PhasorDynamics/Converter/REECA/README.md | 28 +++++- .../PhasorDynamics/Converter/REGCA/README.md | 14 +-- .../PhasorDynamics/Converter/REGCB/README.md | 89 +++++------------ .../PhasorDynamics/Exciter/ESAC6A/README.md | 26 ++++- .../PhasorDynamics/Exciter/ESDC1A/README.md | 16 +++- .../PhasorDynamics/Exciter/ESDC2A/README.md | 25 ++++- .../PhasorDynamics/Exciter/ESST4B/README.md | 30 +++++- .../PhasorDynamics/Exciter/EXAC1/README.md | 27 +++++- .../PhasorDynamics/Exciter/EXAC2/README.md | 27 +++++- .../PhasorDynamics/Exciter/EXPIC1/README.md | 30 +++++- .../PhasorDynamics/Exciter/IEEET1/README.md | 28 +++++- .../PhasorDynamics/Exciter/SCRX/README.md | 26 ++++- .../PhasorDynamics/Exciter/SEXS-PTI/README.md | 24 ++++- .../PhasorDynamics/Governor/GASTPTI/README.md | 4 +- .../PhasorDynamics/Governor/GGOV1/README.md | 26 ++++- .../PhasorDynamics/Governor/HYGOV/README.md | 14 ++- .../PhasorDynamics/Governor/IEEEG1/README.md | 24 ++++- .../PhasorDynamics/Governor/Tgov1/README.md | 14 ++- .../Model/PhasorDynamics/Load/LoadZ/README.md | 31 ++++-- .../PhasorDynamics/Load/LoadZIP/README.md | 31 ++++-- GridKit/Model/PhasorDynamics/README.md | 39 +++++--- .../Model/PhasorDynamics/SignalNode/README.md | 52 ++++++++++ .../PhasorDynamics/SignalSource/README.md | 55 ++++++++++- .../Stabilizer/IEEEST/README.md | 29 +++++- .../PhasorDynamics/Stabilizer/PSS1A/README.md | 26 ++++- .../SynchronousMachine/GENROU/README.md | 64 +++++++++---- .../SynchronousMachine/GENSAL/README.md | 83 +++++++++++----- .../SynchronousMachine/GenClassical/README.md | 61 ++++++++---- 34 files changed, 942 insertions(+), 262 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Branch/README.md b/GridKit/Model/PhasorDynamics/Branch/README.md index 8fcd5ce86..44ccf758e 100644 --- a/GridKit/Model/PhasorDynamics/Branch/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/README.md @@ -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}$. @@ -172,10 +185,10 @@ parameter values. Initial terminal current and power monitor values are evaluated from the connected bus voltages. 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..5569f9e52 100644 --- a/GridKit/Model/PhasorDynamics/BusFault/README.md +++ b/GridKit/Model/PhasorDynamics/BusFault/README.md @@ -8,7 +8,7 @@ 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. +$U$ | [unitless] | Binary status, $U \in \{0, 1\}$ | Set by user to put fault on or off. ### 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 | Fault-state control ## 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..3e9bdbd15 100644 --- a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md +++ b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md @@ -1,20 +1,77 @@ # 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 + +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` + +### External Variables + +#### Differential + +None. + +#### Algebraic + +Symbol | Units | Description | Note +-------|--------|---------------------------------------|----- +$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 0d26657ba..5b325dd3b 100644 --- a/GridKit/Model/PhasorDynamics/Controller/REECB/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/REECB/README.md @@ -362,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) diff --git a/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md b/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md index dbffc77f3..ab33ac4ea 100644 --- a/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md @@ -315,9 +315,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 diff --git a/GridKit/Model/PhasorDynamics/Converter/REECA/README.md b/GridKit/Model/PhasorDynamics/Converter/REECA/README.md index 1e6d62cde..704d78f26 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REECA/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REECA/README.md @@ -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: @@ -293,6 +309,10 @@ CommonMath defines the helper targets and smooth approximations for [clamp](../../../../CommonMath.md#clamp), [deadband2](../../../../CommonMath.md#type-ii-deadband), and [outside](../../../../CommonMath.md#outside). +### External Equations + +None. + ## Initialization Initialization is performed by evaluating the steady-state residuals in dependency order. Let subscript $0$ denote initial values and set all internal derivatives to zero. If optional signals are not connected, use steady-state constants: @@ -392,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 4e351c29d..d5b3d8dd9 100644 --- a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md +++ b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md @@ -167,7 +167,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 +194,7 @@ the sign that enables the corresponding limit. ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -222,7 +224,7 @@ CommonMath defines the [`ramp`](../../../../CommonMath.md#ramp), [`clamp`](../../../../CommonMath.md#clamp), and [`linseg`](../../../../CommonMath.md#linear-segment) functions used above. -## Network Interface +### External Equations ```math \begin{aligned} @@ -320,10 +322,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 520571fe3..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} @@ -178,6 +192,10 @@ 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 073b98586..719bc4bd7 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md @@ -222,14 +222,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 +273,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} @@ -312,6 +314,10 @@ CommonMath defines helper targets and smooth approximations for [max](../../../../CommonMath.md#maximum), the [ramp](../../../../CommonMath.md#ramp) $\rho$, and the [quadratic ramp](../../../../CommonMath.md#quadratic-ramp) $q$. +### External Equations + +None. + ## Initialization ### Input Initialization @@ -404,9 +410,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$ diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESDC2A/README.md index 269293cf9..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} @@ -190,6 +203,10 @@ CommonMath defines the helper targets and smooth approximations for [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 15c8cc6a5..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} @@ -183,6 +201,10 @@ 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 @@ -225,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 1e2cb224b..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} @@ -174,6 +189,10 @@ $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 f043017ac..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} @@ -176,6 +191,10 @@ and [clamp](../../../../CommonMath.md#clamp), and the primitive 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 @@ -225,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/EXPIC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXPIC1/README.md index f57e1ad42..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} @@ -201,6 +219,10 @@ 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 94f0e9411..345f19909 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md @@ -135,6 +135,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 @@ -162,6 +171,12 @@ $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 | @@ -175,7 +190,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 +218,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 @@ -216,6 +233,9 @@ The algebraic equations of the exciter. Here $q$ is GridKit's [Quadratic Ramp](../../../../CommonMath.md#quadratic-ramp). +### External Equations + +None. ## Initialization @@ -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..8d2139fc4 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md @@ -23,6 +23,14 @@ 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. +## 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 @@ -58,7 +66,9 @@ $V_{UEL}$ | [p.u.] | Under-excitation limiter signal | Consta ## Model Equations -### Differential Equations +### Internal Equations + +#### Differential The SEXS-PTI differential equations, as derived from the model diagram. Define the pre-limit derivative of $E_{fd}$ @@ -84,7 +94,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 +102,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 @@ -107,3 +121,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 9aa19911b..d0b0f3e38 100644 --- a/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/GASTPTI/README.md @@ -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 diff --git a/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md b/GridKit/Model/PhasorDynamics/Governor/GGOV1/README.md index 28eddd586..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} @@ -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} @@ -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 76212a1ee..81ad10366 100644 --- a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md @@ -176,7 +176,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 +213,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} @@ -250,6 +252,10 @@ CommonMath defines helper targets and smooth approximations for [deadband1](../../../../CommonMath.md#type-i-deadband) and [clamp](../../../../CommonMath.md#clamp). +### External Equations + +None. + ## Initialization ### Input Initialization @@ -346,9 +352,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) diff --git a/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md b/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md index 7d2257bf2..db382bda9 100644 --- a/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md +++ b/GridKit/Model/PhasorDynamics/Governor/IEEEG1/README.md @@ -105,6 +105,16 @@ The governor component base and nonlinear governor-output curve are: 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} @@ -198,6 +210,10 @@ CommonMath defines helper targets and smooth approximations for 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 @@ -234,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/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 d49d969d3..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 diff --git a/GridKit/Model/PhasorDynamics/SignalNode/README.md b/GridKit/Model/PhasorDynamics/SignalNode/README.md index c05d85a0d..47c3ff342 100644 --- a/GridKit/Model/PhasorDynamics/SignalNode/README.md +++ b/GridKit/Model/PhasorDynamics/SignalNode/README.md @@ -13,3 +13,55 @@ 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 + +Symbol | Units | Description | Note +-------|-------------|---------------------|----- +$s$ | unspecified | Linked signal value | Owned by the producing component + +## 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..0ee7df466 100644 --- a/GridKit/Model/PhasorDynamics/SignalSource/README.md +++ b/GridKit/Model/PhasorDynamics/SignalSource/README.md @@ -13,8 +13,55 @@ Symbol | Units | Description | Note $Sr$ | unspecified | Real component | $Si$ | unspecified | Imaginary component | -## Output ports -- `sr` ($S_r$) -- `si` ($S_i$) +## Model Ports -Constant parameters are made available to signal nodes. +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 1d02f6f6b..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} @@ -107,8 +120,18 @@ $u$ | [p.u.] | Stabilizer input signal The output limiter uses GridKit's smooth [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 2f81e9b27..565294fd9 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md @@ -61,6 +61,15 @@ 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 @@ -83,8 +92,8 @@ $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 +$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 $\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 | @@ -101,12 +110,14 @@ 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} @@ -129,7 +140,8 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Owned by \end{aligned} ``` -### Algebraic Equations +#### Algebraic + 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. ``` math \begin{aligned} @@ -150,6 +162,24 @@ Note that for implementation purposes, some of these equations may be simplified CommonMath defines the primitive [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 The power-flow solution gives $V_r$, $V_i$, $I_r$, and $I_i$. At synchronous @@ -181,14 +211,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 e7a7185b8..2006b15e7 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md @@ -59,6 +59,15 @@ 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 @@ -83,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 @@ -96,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} \\ @@ -118,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}\\ @@ -136,6 +149,24 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Ow CommonMath defines the primitive [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 Using the power-flow solution, initial currents are calculated from active and @@ -161,23 +192,23 @@ steady-state GENSAL equations. \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..5692e3eb2 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 | Exciter signal +`governor_signal` | Input | N/A | Governor signal +
## 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,17 @@ 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 +$P_m$ | [p.u.] | mechanical power input | Stored setpoint +$E_p$ | [p.u.] | internal transient-emf magnitude | Stored setpoint
## Model Equations -### Differential Equations +### Internal Equations + +#### Differential ```math \begin{aligned} @@ -83,7 +93,7 @@ $E_p$ | [p.u.] | field winding voltage | owned by exciter, constant if \end{aligned} ``` -### Algebraic Equations +#### Algebraic ```math \begin{aligned} @@ -96,6 +106,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 +192,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$ From 3af2e94952f6a6411dc548cad13d2cc477be0082 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 20:27:47 -0500 Subject: [PATCH 6/8] EXDC1 and a few adjustments and cleanup --- .../BusToSignalAdapter/README.md | 13 +- .../PhasorDynamics/Exciter/EXDC1/README.md | 314 +++++++++++++----- .../Model/PhasorDynamics/SignalNode/README.md | 4 +- .../PhasorDynamics/SignalSource/README.md | 23 +- 4 files changed, 252 insertions(+), 102 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md index 3e9bdbd15..4b37211d9 100644 --- a/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md +++ b/GridKit/Model/PhasorDynamics/BusToSignalAdapter/README.md @@ -26,10 +26,7 @@ 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` +None. ### External Variables @@ -39,9 +36,11 @@ None. #### Algebraic -Symbol | Units | Description | Note --------|--------|---------------------------------------|----- -$I_r$ | [p.u.] | Real current contribution to the bus | Read from the optional `ir` input +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 diff --git a/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md b/GridKit/Model/PhasorDynamics/Exciter/EXDC1/README.md index 9d842f9b1..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 [PowerWorld](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/SignalNode/README.md b/GridKit/Model/PhasorDynamics/SignalNode/README.md index 47c3ff342..f76b07658 100644 --- a/GridKit/Model/PhasorDynamics/SignalNode/README.md +++ b/GridKit/Model/PhasorDynamics/SignalNode/README.md @@ -38,9 +38,7 @@ None. #### Algebraic -Symbol | Units | Description | Note --------|-------------|---------------------|----- -$s$ | unspecified | Linked signal value | Owned by the producing component +None. ## Model Equations diff --git a/GridKit/Model/PhasorDynamics/SignalSource/README.md b/GridKit/Model/PhasorDynamics/SignalSource/README.md index 0ee7df466..c0e8a7941 100644 --- a/GridKit/Model/PhasorDynamics/SignalSource/README.md +++ b/GridKit/Model/PhasorDynamics/SignalSource/README.md @@ -1,17 +1,22 @@ -# 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 + +None. + +### Model Derived Parameters + +None. ## Model Ports From 98b9f7a467feca1bf6273ffaab00343cd0fd16de Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 20:35:58 -0500 Subject: [PATCH 7/8] ordering for gensal/rou models --- .../SynchronousMachine/GENROU/README.md | 31 +++++++++---------- .../SynchronousMachine/GENSAL/README.md | 2 +- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md index 565294fd9..3b221d714 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENROU/README.md @@ -80,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 | 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 $\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 @@ -124,6 +124,12 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Machine-b \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}} @@ -131,27 +137,20 @@ $E_{fd}$ | [p.u.] | Field winding voltage from the excitation system | Machine-b (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 -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. ``` 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) \\ diff --git a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md index 2006b15e7..247b81e44 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GENSAL/README.md @@ -187,7 +187,7 @@ 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} ``` From bf6ab4869dd7d73fe8853f5e0c232121748670e5 Mon Sep 17 00:00:00 2001 From: lukelowry Date: Thu, 27 Aug 2026 21:20:47 -0500 Subject: [PATCH 8/8] misc adjustments --- GridKit/Model/PhasorDynamics/Branch/README.md | 4 +-- .../Model/PhasorDynamics/BusFault/README.md | 12 ++++---- .../PhasorDynamics/Controller/REPCA/README.md | 1 + .../PhasorDynamics/Converter/REGCA/README.md | 2 ++ .../PhasorDynamics/Exciter/ESDC1A/README.md | 2 -- .../PhasorDynamics/Exciter/IEEET1/README.md | 8 +++--- .../PhasorDynamics/Exciter/SEXS-PTI/README.md | 28 +++++++++++++++++-- .../PhasorDynamics/Governor/HYGOV/README.md | 13 +++++---- .../SynchronousMachine/GenClassical/README.md | 10 ++++--- 9 files changed, 54 insertions(+), 26 deletions(-) diff --git a/GridKit/Model/PhasorDynamics/Branch/README.md b/GridKit/Model/PhasorDynamics/Branch/README.md index 44ccf758e..8e9697781 100644 --- a/GridKit/Model/PhasorDynamics/Branch/README.md +++ b/GridKit/Model/PhasorDynamics/Branch/README.md @@ -181,8 +181,8 @@ 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 enforces the +parameter values. Terminal current and power monitor values are evaluated +from the connected bus voltages when read. Parameter verification enforces the conditions in [Parameter Validation](#parameter-validation). ## Monitors diff --git a/GridKit/Model/PhasorDynamics/BusFault/README.md b/GridKit/Model/PhasorDynamics/BusFault/README.md index 5569f9e52..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, $U \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 @@ -23,7 +23,7 @@ $U$ | [unitless] | Binary status, $U \in \{0, 1\}$ | Set by user to put fau Name | Port | Init | Description -----------------|-------|-------|------------ `bus` | Bus | Known | Required bus where the fault is applied -`control_signal` | Input | N/A | Fault-state control +`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 diff --git a/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md b/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md index ab33ac4ea..67760dbf4 100644 --- a/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md +++ b/GridKit/Model/PhasorDynamics/Controller/REPCA/README.md @@ -70,6 +70,7 @@ All real parameters must be finite. Invalid parameter sets are rejected by: ```math \begin{aligned} S^\mathrm{base} &> 0 \\ + T_\mathrm{fltr}, T_\mathrm{ft}, T_\mathrm{fv}, T_\mathrm{p}, T_\mathrm{lag} &\ge 0 \\ D_\mathrm{bd1} &\le 0 \le D_\mathrm{bd2} \\ e^{\min} &\le 0 \le e^{\max} \\ Q^{\min} &\le Q^{\max} \\ diff --git a/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md b/GridKit/Model/PhasorDynamics/Converter/REGCA/README.md index d5b3d8dd9..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 diff --git a/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md b/GridKit/Model/PhasorDynamics/Exciter/ESDC1A/README.md index 719bc4bd7..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} diff --git a/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md b/GridKit/Model/PhasorDynamics/Exciter/IEEET1/README.md index 345f19909..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} @@ -154,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 | @@ -181,7 +183,7 @@ 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 @@ -239,8 +241,6 @@ 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 diff --git a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md index 8d2139fc4..7aed72c29 100644 --- a/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md +++ b/GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/README.md @@ -23,6 +23,24 @@ 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 @@ -58,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 @@ -66,6 +85,12 @@ $V_{UEL}$ | [p.u.] | Under-excitation limiter signal | Consta ## Model Equations +Define the compensated terminal voltage magnitude for readability: + +```math +E_C = \sqrt{V_r^2+V_i^2}. +``` + ### Internal Equations #### Differential @@ -113,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} diff --git a/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md b/GridKit/Model/PhasorDynamics/Governor/HYGOV/README.md index 81ad10366..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,7 +114,8 @@ 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#linear-segment) helper used by $N_{\mathrm{GV}}$. @@ -408,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/SynchronousMachine/GenClassical/README.md b/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md index 5692e3eb2..ff15dc0a9 100644 --- a/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md +++ b/GridKit/Model/PhasorDynamics/SynchronousMachine/GenClassical/README.md @@ -29,8 +29,8 @@ $S_\mathrm{mach}$ | [MVA] | machine power base | Name | Port | Init | Description ------------------|-------|-------|------------ `bus` | Bus | Known | Terminal bus voltage and current-balance residuals -`exciter_signal` | Input | N/A | Exciter signal -`governor_signal` | Input | N/A | Governor signal +`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
@@ -74,8 +74,10 @@ 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 | Stored setpoint -$E_p$ | [p.u.] | internal transient-emf magnitude | Stored setpoint + +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.