Polish + Prepare IEEEST for release

GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/Ieeest.hpp

@@ -35,28 +35,40 @@ namespace GridKit
       /// Internal variables of a `Ieeest`
       enum class IeeestInternalVariables : size_t
       {
-        X1,  ///< Notch filter state 1
-        X2,  ///< Notch filter state 2
-        X3,  ///< Notch filter state 3
-        X4,  ///< Notch filter state 4
-        X5,  ///< Lead-lag 1 state
-        X6,  ///< Lead-lag 2 state
-        X7,  ///< Washout state
-        V4,  ///< Notch filter output
-        V5,  ///< Lead-lag 1 output
-        V6,  ///< Lead-lag 2 output
-        V7,  ///< Unlimited stabilizer signal
-        VSS, ///< Limited stabilizer signal (model output)
+        X1,  ///< \f$x_1\f$ Notch filter signal state [p.u.], differential for \f$n\ge1\f$
+        X2,  ///< \f$x_2\f$ First derivative of the filtered signal [p.u./sec], differential for \f$n\ge2\f$
+        X3,  ///< \f$x_3\f$ Second derivative of the filtered signal [p.u./sec^2], differential for \f$n\ge3\f$
+        X4,  ///< \f$x_4\f$ Third derivative of the filtered signal [p.u./sec^3], differential for \f$n=4\f$
+        X5,  ///< \f$x_5\f$ Lead-lag 1 state [p.u.]
+        X6,  ///< \f$x_6\f$ Lead-lag 2 state [p.u.]
+        X7,  ///< \f$x_7\f$ Washout state [p.u.]
+        V4,  ///< \f$v_4\f$ Notch filter output [p.u.]
+        V5,  ///< \f$v_5\f$ Lead-lag 1 output [p.u.]
+        V6,  ///< \f$v_6\f$ Lead-lag 2 output [p.u.]
+        V7,  ///< \f$v_7\f$ Unlimited stabilizer signal [p.u.]
+        VSS, ///< \f$V_{ss}\f$ Limited stabilizer signal, the model output [p.u.]
         MAXIMUM,
       };
 
       /// External variables of a `Ieeest`
       enum class IeeestExternalVariables : size_t
       {
-        U, ///< Stabilizer input signal
+        U, ///< \f$u\f$ Stabilizer input signal [p.u.]
         MAXIMUM,
       };
 
+      /**
+       * @brief IEEE type ST power system stabilizer (IEEEST).
+       *
+       * A selectable-order notch filter, two lead-lag blocks, a washout, and an
+       * output limiter. The notch order \f$n\in\{0,1,2,3,4\}\f$ is the degree of
+       * the expanded denominator derived from \f$A_1,\ldots,A_4\f$.
+       *
+       * @tparam scalar_type Plain real or differentiable scalar type.
+       * @tparam index_type Integer index type.
+       *
+       * @see IeeestData
+       */
       template <typename scalar_type, typename index_type>
       class Ieeest : public Component<scalar_type, index_type>
       {
@@ -139,34 +151,30 @@ namespace GridKit
         RealT Vcu_{0};
         RealT Tdelay_{0};
 
+        /// Expanded notch denominator \f$a_0 + a_1 s + a_2 s^2 + a_3 s^3 + a_4 s^4\f$
         RealT a0_{1};
         RealT a1_{0};
         RealT a2_{0};
         RealT a3_{0};
         RealT a4_{0};
 
-        // Precomputed masks and safe inverse coefficients for branch-free degenerate paths.
-        RealT use_notch_{0};
-        RealT bypass_notch_{1};
-        RealT use_4th_order_{0};
-        RealT use_3rd_order_{0};
-        RealT use_2nd_order_{0};
-        RealT safe_inv_a4_{0};
-        RealT safe_inv_a3_{0};
-        RealT safe_inv_a2_{0};
-        RealT use_T2_block_{1};
-        RealT bypass_T2_block_{0};
-        RealT use_T4_block_{1};
-        RealT bypass_T4_block_{0};
-        RealT use_T6_block_{1};
-        RealT bypass_T6_block_{0};
+        /// Order indicators \f$O_k\f$, one when the notch order is at least \f$k\f$
+        RealT O1_{0};
+        RealT O2_{0};
+        RealT O3_{0};
+
+        // A denominator time constant that is not positive bypasses its block.
+        RealT bypass_T2_{0};
+        RealT bypass_T4_{0};
+        RealT bypass_T6_{0};
 
         ComponentSignals<ScalarT, IdxT, IeeestInternalVariables, IeeestExternalVariables> signals_;
 
         std::unique_ptr<MonitorT> monitor_;
 
         void initializeParameters(const ModelDataT& data);
         void initializeMonitor();
+        void setDerivedParameters();
 
         std::vector<ScalarT> ws_;
         std::vector<IdxT>    ws_indices_;

GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/IeeestData.hpp

@@ -19,65 +19,61 @@ namespace GridKit
        */
       enum class IeeestParameters
       {
-        A1,     ///< Notch filter denominator coefficient
-        A2,     ///< Notch filter denominator coefficient
-        A3,     ///< Notch filter denominator coefficient
-        A4,     ///< Notch filter denominator coefficient
-        A5,     ///< Notch filter numerator coefficient
-        A6,     ///< Notch filter numerator coefficient
-        T1,     ///< Lead-lag 1 numerator time constant
-        T2,     ///< Lead-lag 1 denominator time constant
-        T3,     ///< Lead-lag 2 numerator time constant
-        T4,     ///< Lead-lag 2 denominator time constant
-        T5,     ///< Washout numerator time constant
-        T6,     ///< Washout denominator time constant
-        Ks,     ///< Stabilizer gain
-        Lsmin,  ///< Minimum stabilizer output limit
-        Lsmax,  ///< Maximum stabilizer output limit
-        Vcl,    ///< Lower input cutout threshold (not modeled)
-        Vcu,    ///< Upper input cutout threshold (not modeled)
-        Tdelay, ///< Input time delay (not modeled)
+        A1,     ///< \f$A_1\f$ Notch filter denominator coefficient [sec]
+        A2,     ///< \f$A_2\f$ Notch filter denominator coefficient [sec^2]
+        A3,     ///< \f$A_3\f$ Notch filter denominator coefficient [sec]
+        A4,     ///< \f$A_4\f$ Notch filter denominator coefficient [sec^2]
+        A5,     ///< \f$A_5\f$ Notch filter numerator coefficient [sec]
+        A6,     ///< \f$A_6\f$ Notch filter numerator coefficient [sec^2]
+        T1,     ///< \f$T_1\f$ Lead-lag 1 numerator time constant [sec]
+        T2,     ///< \f$T_2\f$ Lead-lag 1 denominator time constant [sec]
+        T3,     ///< \f$T_3\f$ Lead-lag 2 numerator time constant [sec]
+        T4,     ///< \f$T_4\f$ Lead-lag 2 denominator time constant [sec]
+        T5,     ///< \f$T_5\f$ Washout numerator time constant [sec]
+        T6,     ///< \f$T_6\f$ Washout denominator time constant [sec]
+        Ks,     ///< \f$K_s\f$ Stabilizer gain [p.u.]
+        Lsmin,  ///< \f$L_s^{\min}\f$ Minimum stabilizer output limit [p.u.]
+        Lsmax,  ///< \f$L_s^{\max}\f$ Maximum stabilizer output limit [p.u.]
+        Vcl,    ///< \f$V_{cl}\f$ Lower input cutout threshold [p.u.], accepted and unused
+        Vcu,    ///< \f$V_{cu}\f$ Upper input cutout threshold [p.u.], accepted and unused
+        Tdelay, ///< \f$T_{delay}\f$ Input time delay [sec], accepted and unused
       };
 
-      /**
-       * @brief Bus keys for IEEEST Stabilizer model.
-       */
+      /// Buses for the IEEEST Stabilizer model. The stabilizer has no
+      /// electrical terminal.
       enum class IeeestBuses : size_t
       {
         SIZE
       };
 
-      /**
-       * @brief Signal input keys for IEEEST Stabilizer model.
-       */
+      /// Signal inputs for the IEEEST Stabilizer model.
       enum class IeeestSignalInputs : size_t
       {
-        input, ///< Unique ID of the stabilizer input signal
+        input, ///< \f$u\f$ Required stabilizer input signal ID
         SIZE
       };
 
-      /**
-       * @brief Signal output keys for IEEEST Stabilizer model.
-       */
+      /// Signal outputs for the IEEEST Stabilizer model.
       enum class IeeestSignalOutputs : size_t
       {
-        output, ///< Unique ID of the stabilizer output signal
+        output, ///< \f$V_{ss}\f$ Optional stabilizer output signal ID
         SIZE
       };
 
-      /**
-       * @brief Monitorable variables for IEEEST Stabilizer model.
-       */
+      /// Variables available through the monitor interface.
       enum class IeeestMonitorableVariables
       {
-        vss, ///< Stabilizer output (limited signal)
+        vss, ///< \f$V_{ss}\f$ Stabilizer output after the limiter [p.u.]
       };
 
       /**
-       * @brief Contains modeling data for a IEEEST Stabilizer model.
+       * @brief Model data for the IEEEST Stabilizer: parameter values, the
+       *        input and output signals, and monitored-variable selections.
        *
        * @tparam real_type  Real parameter data type
        * @tparam index_type Integer parameter data type
+       *
+       * @see Ieeest
        */
       template <typename real_type, typename index_type>
       struct IeeestData : public ComponentData<real_type,