Fix/pre v3.6 ds fixes

docs/user_manual/tex/dae_model_equations.tex

@@ -43,6 +43,8 @@ \section{Introduction}
 The document assumes the bus voltage is expressed in cartesian form, i.e. $\bar{V} = V_R + iV_I$, where
 $V_R$ and $V_I$ are the real and imaginary components of the complex bus voltage $V$.
 
+\textbf{Note:} This document covers the GENCLS, GENROU, and GENSAL generator models, the EXDC1 and ESST1A exciter models, and the WSIEG1 turbine governor model. Additional models implemented in GridPACK (including REGCA1/REGCB1/REGCC1, GDFORM, SEXS, ESST4B, IEEET1, REECA1, REPCA1, TGOV1, GAST, HYGOV, WSHYGP, PSSSIM, and dynamic load models) are documented in their respective source files and PSS/E model references.
+
 \section{Generator models}
 The inputs and outputs for the generator models are given below. These inputs/outputs representing
 the coupling with the bus and the generator controls such as exciters, turbine-governors.
@@ -105,7 +107,7 @@ \subsubsection{Equations}
 &\frac{1}{\omega_s}\frac{d{\delta}}{dt}={\Delta\omega}&\\
 &\frac{1}{2H}\frac{d{\Delta\omega}}{dt} = \frac{\Pm-D*{\Delta\omega}}{1+{\Delta\omega}}-T_{elec}&\\
 &T^{'}_{do}\frac{dE^{'}_q}{dt}= \Efd - L_{ad}\Ifd&\\
-\nonumber  &T^{'}_{qo}\frac{dE^{'}_d}{dt}= (X_q - X^{'}_q)\left( I_q -\frac{X^{'}_q - X^{''}_q}{(X^{'}_q - X_l)^2}(E^{'}_d +(X^{'}_q - X_l)I_q - \psi^{'}_q)\right) -&\\ &\qquad E^{'}_d + \frac{X_q - X_l}{X_d - X_l}\psi^{''}_q\frac{Sat(\sqrt{\psi^{''}_d + \psi^{''2}_q})}{\sqrt{\psi^{''}_d + \psi^{''2}_q}}
+\nonumber  &T^{'}_{qo}\frac{dE^{'}_d}{dt}= (X_q - X^{'}_q)\left( I_q -\frac{X^{'}_q - X^{''}_q}{(X^{'}_q - X_l)^2}(E^{'}_d +(X^{'}_q - X_l)I_q - \psi^{'}_q)\right) -&\\ &\qquad E^{'}_d + \frac{X_q - X_l}{X_d - X_l}\psi^{''}_q\frac{Sat(\sqrt{\psi^{''2}_d + \psi^{''2}_q})}{\sqrt{\psi^{''2}_d + \psi^{''2}_q}}
 &\\
 &T^{''}_{do}\frac{d\psi^{'}_d}{dt} = E^{'}_q   - \psi^{'}_d  - (X^{'}_{d}-X_{l})I_d&\\
 &{T^{''}_{qo}}\frac{d\psi^{'}_q}{dt} = E^{'}_d - \psi^{'}_q  + (X^{'}_q-X_{l})I_q&
@@ -121,7 +123,7 @@ \subsubsection{Outputs}
 	\item Field current
 \begin{flalign*}
 L_{ad}\Ifd = &E^{'}_q + (X_d-X^{'}_{d})\left(I_d + \dfrac{X^{'}_d - X^{"}_d}{(X^{'}_d-X_{l})^2}\left(E^{'}_q - \psi^{'}_d - (X^{'}_d - X_l)I_d\right)\right) + \\ 
-&\psi^{''}_d\frac{Sat(\sqrt{\psi^{''}_d + \psi^{''2}_q})}{\sqrt{\psi^{''}_d + \psi^{''2}_q}}
+&\psi^{''}_d\frac{Sat(\sqrt{\psi^{''2}_d + \psi^{''2}_q})}{\sqrt{\psi^{''2}_d + \psi^{''2}_q}}
  %L_{ad}\Ifd = E^{'}_q + f_{sat}(E^{'}_q) +(X_d-X^{'}_{d})\left[ \dfrac{X_d - X^{"}_d}{X_d-X_{l}^2}\left(E^{'}_q - \psi^{'}_d - I_d(X^{'}_d - X_l)\right) + I_d\right]
  % L_{ad}\Ifd=E^{'}_q+(X_d-X_{d})*(I_d+T_{empD})&\\
 \end{flalign*}
@@ -360,7 +362,7 @@ \subsubsection{Equations}
  Here, the intermediate variables used in the calculations are as follows:
 \begin{align*}
  &\begin{cases}
-    y_{LL} = x_{LL} + \dfrac{T_2}{T_1}K\dw,&\text{if}~~T_1 > 0 \& T_2 >  \\
+    y_{LL} = x_{LL} + \dfrac{T_2}{T_1}K\dw,&\text{if}~~T_1 > 0 \& T_2 > 0 \\
     y_{LL} = x_{LL},&\text{if}~~T_1 = T_2 = 0
   \end{cases}& \\
 &u_{GV} = \max(\min(\dfrac{1}{T_3}\left(P_{ref} - x_{GV} - y_{LL}\right),U_o),U_c)&

docs/user_manual/tex/ds_mod.tex

@@ -9,6 +9,9 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
   GENCLS
   GENSAL
   GENROU
+  REGCA1, REGCB1, REGCC1 (grid-following IBR)
+  GDFORM (grid-forming IBR)
+  EPRIA1
 \end{Verbatim}
 }
 
@@ -19,6 +22,10 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
 \begin{Verbatim}[fontseries=b]
   EXDC1
   ESST1A
+  ESST4B
+  IEEET1
+  SEXS
+  REECA1 (IBR electrical control)
 \end{Verbatim}
 }
 
@@ -29,6 +36,38 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
 \begin{Verbatim}[fontseries=b]
   WSIEG1
   WSHYGP
+  TGOV1
+  GAST
+  HYGOV
+\end{Verbatim}
+}
+
+Power System Stabilizers:
+
+{
+\color{red}
+\begin{Verbatim}[fontseries=b]
+  PSSSIM
+\end{Verbatim}
+}
+
+Plant Controllers (IBR):
+
+{
+\color{red}
+\begin{Verbatim}[fontseries=b]
+  REPCA1 (REPCTA1)
+\end{Verbatim}
+}
+
+IBR Mechanical Models:
+
+{
+\color{red}
+\begin{Verbatim}[fontseries=b]
+  WTARA1
+  WTDTA1
+  WTTQA1
 \end{Verbatim}
 }
 
@@ -49,6 +88,7 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
 \color{red}
 \begin{Verbatim}[fontseries=b]
   ACMTBLU1
+  CMLDBLU1
   IEEL
   MOTORW
   CIM6BL
@@ -67,6 +107,7 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
     <generatorParameters>IEEE_145.dyr</generatorParameters>
     <simulationTime>30</simulationTime>
     <timeStep>0.005</timeStep>
+    <equilibriumInit>false</equilibriumInit>
     <Events>
       <faultEvent>
         <beginFault> 2.00</beginFault>
@@ -101,7 +142,7 @@ \section{Dynamic Simulation Module using Full Y-Matrix}
 \end{Verbatim}
 }
 
-The input for dynamic simulation module is contained in the \texttt{\textbf{Dynamic\_simulation}} block. Two features are important, the blocks describing faults and the blocks describing monitored generators. Faults are described in the \texttt{\textbf{Event}}s block. The code currently only handles faults on branches. Inside the \texttt{\textbf{Events}} block are individual faults, described by a \texttt{\textbf{faultEvent}} block. Multiple \texttt{\textbf{faultEvent}} blocks can be contained within the \texttt{\textbf{Events }}block. As will be described below, it is possible for the faults to be listed in a separate file. This can be convenient for describing a task-based calculation that may contain a lot of faults. The parameters describing the fault include the time (in seconds) that the fault is initiated, the time that it is terminated, the timestep used while integrating the fault and the indices of the two buses at either end of the fault branch.
+The input for dynamic simulation module is contained in the \texttt{\textbf{Dynamic\_simulation}} block. The optional \texttt{\textbf{equilibriumInit}} parameter, when set to true, runs the simulation to a steady-state equilibrium before applying faults. This can be useful for verifying that the initial conditions are stable. Two features are important, the blocks describing faults and the blocks describing monitored generators. Faults are described in the \texttt{\textbf{Event}}s block. The code currently only handles faults on branches. Inside the \texttt{\textbf{Events}} block are individual faults, described by a \texttt{\textbf{faultEvent}} block. Multiple \texttt{\textbf{faultEvent}} blocks can be contained within the \texttt{\textbf{Events }}block. As will be described below, it is possible for the faults to be listed in a separate file. This can be convenient for describing a task-based calculation that may contain a lot of faults. The parameters describing the fault include the time (in seconds) that the fault is initiated, the time that it is terminated, the timestep used while integrating the fault and the indices of the two buses at either end of the fault branch.
 
 When running a dynamic simulation, it is generally desirable to monitor the behavior of a few generators in the system and this can be done by setting generator watch parameters. The \texttt{\textbf{generatorWatch}} block specifies which generators are to be monitored. Each generator is described within a \texttt{\textbf{generator}} block that contains the index of the bus that the generator is located on and the character string ID of the generator. The results of monitoring the generator are written to the file listed in the \texttt{\textbf{generatorWatchFileName}} field and the frequency for storing generator parameters in this file is set in the \texttt{\textbf{generatorWatchFrequency}} field. This parameter describes the time step interval for writing results (an integer), not the actual time interval.
 

docs/user_manual/tex/se_mod.tex

@@ -25,7 +25,7 @@ \section{State Estimation Module}
         <FromBus>1</FromBus>
         <ToBus>2</ToBus>
         <CKT>BL</CKT>
-        <Values>-0.2040</Value>
+        <Value>-0.2040</Value>
         <Deviation>0.0100</Deviation>
       </Measurement>
       <Measurement>
@@ -44,7 +44,7 @@ \section{State Estimation Module}
 \end{Verbatim}
 }
 
-for the five types of measurements \texttt{\textbf{VM}}, \texttt{\textbf{PIJ}}, \texttt{\textbf{QIJ}}, \texttt{\textbf{PI}}, and \texttt{\textbf{PJ}}. Measurements can appear on any element of the network and multiple measurements are allowed on each element. The state estimation module does not have any error checking ability to determine if there are sufficient measurements to guarantee solvability, if not enough measurements are available then the calculation will simply crash or fail to converge.
+The supported measurement types are: \texttt{\textbf{VM}} (voltage magnitude), \texttt{\textbf{VA}} (voltage angle), \texttt{\textbf{PI}} (bus real power injection), \texttt{\textbf{QI}} (bus reactive power injection), \texttt{\textbf{PJ}} (bus real power injection at receiving end), \texttt{\textbf{QJ}} (bus reactive power injection at receiving end), \texttt{\textbf{PIJ}} (branch real power flow from-to), \texttt{\textbf{QIJ}} (branch reactive power flow from-to), \texttt{\textbf{PJI}} (branch real power flow to-from), and \texttt{\textbf{QJI}} (branch reactive power flow to-from). Measurements can appear on any element of the network and multiple measurements are allowed on each element. The state estimation module does not have any error checking ability to determine if there are sufficient measurements to guarantee solvability, if not enough measurements are available then the calculation will simply crash or fail to converge.
 The state estimation module is represented by the \texttt{\textbf{SEAppModule}} class which is in the \texttt{\textbf{gridpack::state\_estimation}} namespace. The \texttt{\textbf{gridpack.hpp}} file contains a definition for the state estimation network \texttt{\textbf{SENetwork}}. After instantiating an \texttt{\textbf{SEAppModule}} object and a shared pointer to an \texttt{\textbf{SENetwork}}, the state estimation calculation can read in an external network configuration file using the command
 
 {
@@ -79,6 +79,26 @@ \section{State Estimation Module}
 
 The name of the measurement file is in the input deck and a pointer to this file has already been internally cached in the \texttt{\textbf{SEAppModule}} when the network was assigned. The measurement file name is stored in the \texttt{\textbf{measurementList}} field within the \texttt{\textbf{State\_estimation}} block.
 
+The \texttt{\textbf{State\_estimation}} block supports the following optional configuration parameters:
+
+{
+\color{blue}
+\begin{Verbatim}[fontseries=b]
+  <State_estimation>
+    <networkConfiguration>ieee14.raw</networkConfiguration>
+    <measurementList>measurements.xml</measurementList>
+    <tolerance>1.0e-3</tolerance>
+    <maxIteration>20</maxIteration>
+    <dampingFactor>1.0</dampingFactor>
+    <badDataThreshold>3.0</badDataThreshold>
+    <maxBadDataIterations>5</maxBadDataIterations>
+    <diagnosticOutputLevel>basic</diagnosticOutputLevel>
+  </State_estimation>
+\end{Verbatim}
+}
+
+The \texttt{\textbf{tolerance}} parameter sets the convergence threshold (default 1.0e-3). The \texttt{\textbf{maxIteration}} parameter limits the number of Newton-Raphson iterations (default 20). The \texttt{\textbf{dampingFactor}} scales the Newton update step (default 1.0). The \texttt{\textbf{badDataThreshold}} sets the normalized residual threshold for bad data detection (default 3.0), and \texttt{\textbf{maxBadDataIterations}} limits the number of bad data elimination passes (default 5). The \texttt{\textbf{diagnosticOutputLevel}} controls the verbosity of diagnostic output (default ``basic'').
+
 The network object can be initialized and the exchange buffers set up by calling the
 
 {

src/CHANGELOG.md

@@ -34,7 +34,7 @@ functionality appears in the develop branch.
     - Q-limit (QLIM) handling with PV-to-PQ bus switching and island detection
     - RMPCT-based reactive power distribution for multi-generator buses
     - Fixed shunt status check, Qg distribution when QLIM is reached, and
-      flat/warm start (VM/VA)
+      flat/warm start 
     - Switched shunt support
     - ZIP load model with voltage-dependent load representation
     - Added Pinj, Qinj to power flow screen outputs
@@ -49,7 +49,7 @@ functionality appears in the develop branch.
     - Generator ID display in contingency results
     - JSON and CSV export of contingency analysis results
   - Dynamic Simulation Enhancements
-    - GENROU PSS (power system stabilizer) integration
+    - GENROU PSS integration
     - Iterative equilibrium initialization (XML: equilibriumInit, default false)
   - Added build trigger when releasing a new version of GridPACK
 - Changed
@@ -58,16 +58,29 @@ functionality appears in the develop branch.
   - Migrated QLIM parameter to bool type in power flow and CA for consistency
   - Optimized CMake builds
 - Fixed
-  - Fixed PSSSIM washout output divided by Tw, reducing PSS gain by 10x
+  - Fixed GENROU saturation: use scaled quadratic Se=B*(x-A)^2/x per PowerWorld
+    standard, evaluate at air-gap flux magnitude, iterative q-axis saturation
+    in initialization, and corrected LadIfd Se*Psidpp term
+  - Fixed ESST1A regulator limits from Vrmin/Vrmax to Vamin/Vamax (IEEE 421.5)
+  - Fixed ESST1A second lead-lag stage bypassed when TA != 0
+  - Fixed WSIEG1 parser T3 parameter read from wrong field
+  - Fixed WSIEG1 NGV lookup table yin[] index
+  - Fixed REECA1 CurrentLimitLogic VDL1/VDL2 table assignment swapped
+  - Fixed REPCA1 parser FEMIN read from wrong dyr column
+  - Fixed REGCA1 Iq_olim sign inconsistency in display functions
+  - Fixed GENSAL predictor using stale speed deviation for governor
+  - Fixed GENSAL saturation initialization
+  - Fixed ForceSerial off-by-one in math library setElementRange half-open range,
+    causing stale values on multi-process runs with composite load models
+  - Fixed PSSSIM washout output divided by Tw
   - Fixed HYGOV fallback setting R instead of r when parameter missing
   - Fixed Cblock crash when model time constant is zero (e.g., REECA1 with TP=0)
   - Fixed SEXS exciter EMAX default from 0.0 to 999.0
   - Fixed REGCA1 P and Q swapped in output reporting
   - Fixed null pointer crash on unrecognized generator model in dsf_components
   - Fixed REECA1 parser reading TIQ parameter from wrong dyr column
-  - Fixed incomplete REGCA1 data for bus 3433 in 240-bus WECC dyr file
   - Fixed contingency analysis multi-process deadlock in GA one-sided operations
-    during result export (getData must be collective for GA progress)
+    during result export
   - Fixed 3-winding transformer parsing in PSS/E parsers
   - Fixed warm start with qlim=false scenario
   - Fixed incomplete printing of many parallel lines in power flow output