BUG: Internal limit states (#640)

* repca fix

* no floating point comaprison

* two other misc limiter changes

* REGCA HV limit fix

* add stress test that engages many limits

* polishing and remove aux file

Author: lukelowry

CHANGELOG.md

@@ -19,6 +19,11 @@
 - Migrated PhasorDynamics models with real and Boolean parameters to `Model::ParameterReader`.
 - Added component labels and lookups that search subsystems.
 - Added ACTIVSg25k and ACTIVSg70k PhasorDynamics cases.
+- Fixed REPCA PI windup while saturated; the PI states now track the limited outputs.
+- Fixed REECB to limit the direct voltage reference (`VFlag` off) to [`Vmin`, `Vmax`].
+- Fixed ESDC1A rate feedback to use the limited field-voltage rate.
+- Fixed REGCA to hold the terminal voltage at `Vhvmax`, as PowerWorld does; `Khv` is accepted but unused.
+- Added the FourBusLimits validation case, which drives the REPCA, REECB, REGCA, and ESDC1A limits.
 
 ## v0.2
 

GridKit/Model/PhasorDynamics/Controller/REECB/README.md

@@ -205,7 +205,7 @@ Smooth functions: [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`
   0 &= -Q^\mathrm{ref}+s_Q^\mathrm{ref}(s_\mathrm{pf}P^\mathrm{meas}\tan(\phi^\mathrm{ref})+s_\mathrm{pf}^\mathrm{off}k_\mathrm{base}Q^\mathrm{ext}) \\
   0 &= -e_Q+\text{clamp}(Q^\mathrm{ref};\,Q^{\min},Q^{\max})-k_\mathrm{base}Q^\mathrm{gen} \\
   0 &= -V_Q^\mathrm{PI}+\text{clamp}(K_\mathrm{qp}e_Q+x_Q^\mathrm{PI};\,V^{\min},V^{\max}) \\
-  0 &= -e_V^\mathrm{PI}+s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}Q^\mathrm{ext}-s_QV^\mathrm{meas} \\
+  0 &= -e_V^\mathrm{PI}+s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}\text{clamp}(Q^\mathrm{ext};\,V^{\min},V^{\max})-s_QV^\mathrm{meas} \\
   0 &= -r_P^\mathrm{ord}+\text{aslew}\!\left(\dfrac{k_\mathrm{base}P^\mathrm{ref}-P^\mathrm{ord}}{T_\mathrm{pord}};\,R_P^{\min},R_P^{\max}\right) \\
   0 &= -I_L^\mathrm{cap}+\text{sqrtramp}\big((I^{\max}-I^\mathrm{high})(I^{\max}+I^\mathrm{high})\big) \\
   0 &= -I_q^{\max}+s_\mathrm{pq}I_L^\mathrm{cap}+s_\mathrm{pq}^\mathrm{off}I^{\max} \\
@@ -321,7 +321,7 @@ give
         0 & s_Qs_V=0
       \end{cases} \\
   V_Q^\mathrm{PI} &\leftarrow \text{clamp}(K_\mathrm{qp}e_Q+x_Q^\mathrm{PI};\,V^{\min},V^{\max}) \\
-  e_V^\mathrm{PI} &\leftarrow s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}Q^\mathrm{ext}-s_QV^\mathrm{meas} \\
+  e_V^\mathrm{PI} &\leftarrow s_Q^\mathrm{PI}V_Q^\mathrm{PI}+s_V^\mathrm{ref}\text{clamp}(Q^\mathrm{ext};\,V^{\min},V^{\max})-s_QV^\mathrm{meas} \\
   x_V^\mathrm{PI} &\leftarrow
       \begin{cases}
         -K_\mathrm{vp}e_V^\mathrm{PI} & s_Q=1\ \land\ I_q^{\max}\le\epsilon_\mathrm{init} \\
@@ -353,7 +353,7 @@ limit, latch, or signal is changed.
       \end{cases} \\
   Q^\mathrm{ext} &\leftarrow
       \begin{cases}
-        V^\mathrm{meas} & s_V^\mathrm{ref}=1 \\
+        \text{iclamp}(V^\mathrm{meas};\,V^{\min},V^{\max}) & s_V^\mathrm{ref}=1 \\
         0 & s_V^\mathrm{ref}=0\ \land\ s_\mathrm{pf}=1 \\
         Q^\mathrm{target}/k_\mathrm{base} & s_V^\mathrm{ref}=0\ \land\ s_\mathrm{pf}=0
       \end{cases} \\

GridKit/Model/PhasorDynamics/Controller/REECB/ReecbImpl.hpp

@@ -443,14 +443,13 @@ namespace GridKit
         RealT       qmax   = Qmax_;
         RealT       vmin   = Vmin_;
         RealT       vmax   = Vmax_;
+
+        const RealT infinity = std::numeric_limits<RealT>::infinity();
         if (QFlag_ && VFlag_)
         {
           qmin = std::min(Qmin_, qgen0);
           qmax = std::max(Qmax_, qgen0);
-          vmin = std::min(Vmin_, vmeas0);
-          vmax = std::max(Vmax_, vmeas0);
 
-          const RealT infinity = std::numeric_limits<RealT>::infinity();
           if (qmin == qgen0 && qmin < qmax)
           {
             qmin = std::nextafter(qmin, -infinity);
@@ -459,6 +458,12 @@ namespace GridKit
           {
             qmax = std::nextafter(qmax, infinity);
           }
+        }
+        if (QFlag_)
+        {
+          vmin = std::min(Vmin_, vmeas0);
+          vmax = std::max(Vmax_, vmeas0);
+
           if (vmin == vmeas0 && vmin < vmax)
           {
             vmin = std::nextafter(vmin, -infinity);
@@ -489,7 +494,11 @@ namespace GridKit
 
         if (QFlag_ && !VFlag_)
         {
-          qext0_port = vmeas0;
+          if (!iclamp(vmeas0, vmin, vmax, qext0_port))
+          {
+            Log::error() << "Reecb: voltage limiter has no finite steady input\n";
+            return false;
+          }
         }
         else if (PfFlag_)
         {
@@ -541,7 +550,7 @@ namespace GridKit
           }
           else
           {
-            epiv0 = qext0_port - vmeas0;
+            epiv0 = Math::clamp(qext0_port, vmin, vmax) - vmeas0;
           }
 
           if (iqmax0 <= INITIALIZATION_TOLERANCE)
@@ -991,7 +1000,7 @@ namespace GridKit
         f[QREF]   = -qref + qref_target;
         f[EQ]     = -eq + Math::clamp(qref, Qmin_, Qmax_) - qgen;
         f[VPIQ]   = -vpiq + Math::clamp(q_pi_state, Vmin_, Vmax_);
-        f[EPIV]   = -epiv + q_pi_on_ * vpiq + v_ref_on_ * extref - q_on_ * vmeas;
+        f[EPIV]   = -epiv + q_pi_on_ * vpiq + v_ref_on_ * Math::clamp(extref, Vmin_, Vmax_) - q_on_ * vmeas;
         f[RPORD]  = -rpord + aslew(fpord, dPmin_, dPmax_);
         f[ILCAP]  = -ilcap + sqrtramp(circleSquare(Imax_, high));
         f[IQMAX]  = -iqmax + pq_on_ * ilcap + pq_off_ * Imax_;

GridKit/Model/PhasorDynamics/Controller/REPCA/README.md

@@ -68,6 +68,7 @@ A valid REPCA parameter set must satisfy the following conditions:
 \begin{aligned}
   S^\mathrm{base} &> 0 \\
   T_\mathrm{fltr}, T_\mathrm{ft}, T_\mathrm{fv}, T_\mathrm{p}, T_\mathrm{lag} &\ge 0 \\
+  K_\mathrm{p}, K_\mathrm{pg} &\ge 0 \\
   D_\mathrm{bd1} &\le 0 \le D_\mathrm{bd2} \\
   e^{\min} &\le 0 \le e^{\max} \\
   Q^{\min} &\le Q^{\max} \\
@@ -188,6 +189,9 @@ $f^\mathrm{ref}$                | [p.u.] | Frequency reference
 
 Smooth functions: [`above`](../../../../CommonMath.md#above), [`antiwindup`](../../../../CommonMath.md#antiwindup), [`clamp`](../../../../CommonMath.md#clamp), [`deadband2`](../../../../CommonMath.md#type-ii-deadband).
 
+The PI controllers feed back the limited outputs.[^pi-feedback] Limiting the
+state as well keeps it constant at zero error.
+
 ### Internal Equations
 
 #### Differential
@@ -196,10 +200,16 @@ Smooth functions: [`above`](../../../../CommonMath.md#above), [`antiwindup`](../
 \begin{aligned}
   0 &= -\dot{V}^\mathrm{meas} + \dfrac{1}{T_\mathrm{fltr}} (V^\mathrm{ctrl} - V^\mathrm{meas}) \\
   0 &= -\dot{Q}^\mathrm{meas} + \dfrac{1}{T_\mathrm{fltr}} (k_\mathrm{base}Q - Q^\mathrm{meas}) \\
-  0 &= -\dot{x}_Q^\mathrm{PI} + s_\mathrm{frz}\, \text{antiwindup}(Q^\mathrm{PI}, K_\mathrm{i}e_\mathrm{RQ}^\mathrm{lim};\,Q^{\min}, Q^{\max}) \\
+  0 &= -\dot{x}_Q^\mathrm{PI} + s_\mathrm{frz}\, \begin{cases}
+    \dfrac{K_\mathrm{i}}{K_\mathrm{p}}\left(Q^\mathrm{PI}-\text{clamp}(x_Q^\mathrm{PI};\,Q^{\min},Q^{\max})\right) & K_\mathrm{p}>0 \\
+    \text{antiwindup}(x_Q^\mathrm{PI}, K_\mathrm{i}e_\mathrm{RQ}^\mathrm{lim};\,Q^{\min},Q^{\max}) & K_\mathrm{p}=0
+  \end{cases} \\
   0 &= -\dot{x}_Q^\mathrm{lag} + \dfrac{1}{T_\mathrm{fv}} (Q^\mathrm{PI} - x_Q^\mathrm{lag}) \\
   0 &= -\dot{P}^\mathrm{meas} + \dfrac{1}{T_\mathrm{p}} (k_\mathrm{base}P - P^\mathrm{meas}) \\
-  0 &= -\dot{x}_P^\mathrm{PI} + \text{antiwindup}(P^\mathrm{PI}, K_\mathrm{ig}e_P^\mathrm{lim};\,P^{\min}, P^{\max}) \\
+  0 &= -\dot{x}_P^\mathrm{PI} + \begin{cases}
+    \dfrac{K_\mathrm{ig}}{K_\mathrm{pg}}\left(P^\mathrm{PI}-\text{clamp}(x_P^\mathrm{PI};\,P^{\min},P^{\max})\right) & K_\mathrm{pg}>0 \\
+    \text{antiwindup}(x_P^\mathrm{PI}, K_\mathrm{ig}e_P^\mathrm{lim};\,P^{\min},P^{\max}) & K_\mathrm{pg}=0
+  \end{cases} \\
   0 &= -\dot{P}^\mathrm{ref} + \dfrac{1}{T_\mathrm{lag}} (P^\mathrm{PI} - P^\mathrm{ref})
 \end{aligned}
 ```
@@ -299,11 +309,8 @@ If an initial PI output falls outside its configured limits, REPCA expands the
 limits to include it and logs a warning. This matches PowerWorld's default
 `Modify Limits and Run` treatment of initial limit violations.
 
-Initialization rejects an operating point if:
-
-- a required input or derived value is not finite;
-- the gated reactive-power or active-power PI state rate is nonfinite or does
-  not vanish within the implementation tolerance.
+Initialization rejects an operating point if a required input or derived value
+is not finite.
 
 Initialization is atomic; candidates are validated before state or signal writes.
 
@@ -342,3 +349,5 @@ $\text{droop}(0;D_\mathrm{dn},D_\mathrm{up})=0$.
 [^frequency-measurement]: Background for phase-derived, filtered frequency
     measurement: [PSCAD Frequency/Phase/Magnitude Meter](https://www.pscad.com/webhelp-pscad-v5.1.0-ol/Master_Library_Models/Meters/Frequency_Phase_Magnitude_Meter.htm) and
     [Ting et al., *Evaluating Methods for Measuring Grid Frequency in Low-Inertia Power Systems*](https://research-hub.nlr.gov/en/publications/evaluating-methods-for-measuring-grid-frequency-in-low-inertia-po-3/).
+
+[^pi-feedback]: See PowerWorld's [DER_A feedback PI, p. 3](https://www.powerworld.com/WebHelp/Content/TransientModels_PDF/Generator/Machine/Machine%20Model%20DER_A.pdf#page=3).

GridKit/Model/PhasorDynamics/Controller/REPCA/Repca.hpp

@@ -206,6 +206,11 @@ namespace GridKit
         RealT ref_off_{ZERO<RealT>};
         RealT freq_on_{ZERO<RealT>};
 
+        RealT q_feedback_gain_{ONE<RealT>};
+        RealT q_integral_gain_{ZERO<RealT>};
+        RealT p_feedback_gain_{ONE<RealT>};
+        RealT p_integral_gain_{ZERO<RealT>};
+
         ScalarT freqref_set_{ONE<RealT>};
         ScalarT vref_set_{ONE<RealT>};
         ScalarT qref_set_{ZERO<RealT>};

GridKit/Model/PhasorDynamics/Controller/REPCA/RepcaImpl.hpp

@@ -155,6 +155,8 @@ namespace GridKit
                        "system/component power-base conversion ratios must be finite and positive");
         }
 
+        checks.check(Kp_ >= ZERO<RealT>, "Kp must be non-negative");
+        checks.check(Kpg_ >= ZERO<RealT>, "Kpg must be non-negative");
         checks.check(dbdlow_ <= ZERO<RealT> && ZERO<RealT> <= dbdupper_,
                      "dbdlow <= 0 <= dbdupper is required");
         checks.check(emin_ <= ZERO<RealT> && ZERO<RealT> <= emax_,
@@ -335,15 +337,7 @@ namespace GridKit
           Log::error() << "Repca: reactive-power PI limiter has no finite steady input\n";
           return 1;
         }
-        const ScalarT xqpi0      = qpi_input0 - Kp_ * erqlim0;
-        const ScalarT q_aw_rate0 = Math::antiwindup(qpi0, Ki_ * erqlim0, qmin, qmax);
-        const ScalarT xqpi_rate0 = sfrz0 * q_aw_rate0;
-        if (!is_finite(q_aw_rate0) || !is_finite(xqpi_rate0)
-            || std::abs(static_cast<RealT>(xqpi_rate0)) > INITIALIZATION_TOLERANCE)
-        {
-          Log::error() << "Repca: reactive-power PI state rate is nonzero at initialization\n";
-          return 1;
-        }
+        const ScalarT xqpi0 = qpi_input0 - Kp_ * erqlim0;
 
         ScalarT frequency_error0{};
         ScalarT ep0{};
@@ -368,14 +362,7 @@ namespace GridKit
           Log::error() << "Repca: active-power PI limiter has no finite steady input\n";
           return 1;
         }
-        const ScalarT xppi0      = ppi_input0 - Kpg_ * eplim0;
-        const ScalarT p_aw_rate0 = Math::antiwindup(ppi0, Kig_ * eplim0, pmin, pmax);
-        if (!is_finite(p_aw_rate0)
-            || std::abs(static_cast<RealT>(p_aw_rate0)) > INITIALIZATION_TOLERANCE)
-        {
-          Log::error() << "Repca: active-power PI antiwindup rate is nonzero at initialization\n";
-          return 1;
-        }
+        const ScalarT xppi0 = ppi_input0 - Kpg_ * eplim0;
 
         const ScalarT pext_output0 = Freqflag_ ? pext0_system : zero;
         const ScalarT freqref0     = freq + frequency_error0;
@@ -415,8 +402,6 @@ namespace GridKit
             && is_finite(xqlag0)
             && is_finite(qpi_input0)
             && is_finite(xqpi0)
-            && is_finite(q_aw_rate0)
-            && is_finite(xqpi_rate0)
             && is_finite(ef0)
             && is_finite(pfreq0)
             && is_finite(ep0)
@@ -425,7 +410,6 @@ namespace GridKit
             && is_finite(ppi0)
             && is_finite(ppi_input0)
             && is_finite(xppi0)
-            && is_finite(p_aw_rate0)
             && is_finite(pext_output0)
             && is_finite(freqref0)
             && is_finite(vref0)
@@ -793,12 +777,17 @@ namespace GridKit
         const ScalarT vldc_i = vi - Rc_ * ii - Xc_ * ir;
         const ScalarT pfreq  = droop(ef, Ddn_, Dup_);
 
+        const ScalarT q_pi_rate = q_feedback_gain_ * (qpi - Math::clamp(xqpi, Qmin_, Qmax_))
+                                  + Math::antiwindup(xqpi, q_integral_gain_ * erqlim, Qmin_, Qmax_);
+        const ScalarT p_pi_rate = p_feedback_gain_ * (ppi - Math::clamp(xppi, Pmin_, Pmax_))
+                                  + Math::antiwindup(xppi, p_integral_gain_ * eplim, Pmin_, Pmax_);
+
         f[VMEAS]      = -vmeas_dot + (vctrl - vmeas) / Tfltr_;
         f[QMEAS]      = -qmeas_dot + (q - qmeas) / Tfltr_;
-        f[XQPI]       = -xqpi_dot + sfrz * Math::antiwindup(qpi, Ki_ * erqlim, Qmin_, Qmax_);
+        f[XQPI]       = -xqpi_dot + sfrz * q_pi_rate;
         f[XQLAG]      = -xqlag_dot + (qpi - xqlag) / Tfv_;
         f[PMEAS]      = -pmeas_dot + (p - pmeas) / Tp_;
-        f[XPPI]       = -xppi_dot + Math::antiwindup(ppi, Kig_ * eplim, Pmin_, Pmax_);
+        f[XPPI]       = -xppi_dot + p_pi_rate;
         f[PREF_STATE] = -pref_dot + (ppi - pref) / Tlag_;
 
         f[V]      = -v * v + vr * vr + vi * vi;
@@ -929,7 +918,7 @@ namespace GridKit
        * @brief Resolve parameter-derived constants
        *
        * Raises the explicit controller lags in place, computes the component
-       * power base, and resolves selector masks.
+       * power base, and resolves selector masks and PI rate gains.
        */
       template <typename scalar_type, typename index_type>
       void Repca<scalar_type, index_type>::setDerivedParameters()
@@ -956,6 +945,22 @@ namespace GridKit
         ref_on_    = RefFlag_ ? ONE<RealT> : ZERO<RealT>;
         ref_off_   = ONE<RealT> - ref_on_;
         freq_on_   = Freqflag_ ? ONE<RealT> : ZERO<RealT>;
+
+        q_feedback_gain_ = ZERO<RealT>;
+        q_integral_gain_ = Ki_;
+        if (Kp_ > ZERO<RealT>)
+        {
+          q_feedback_gain_ = Ki_ / Kp_;
+          q_integral_gain_ = ZERO<RealT>;
+        }
+
+        p_feedback_gain_ = ZERO<RealT>;
+        p_integral_gain_ = Kig_;
+        if (Kpg_ > ZERO<RealT>)
+        {
+          p_feedback_gain_ = Kig_ / Kpg_;
+          p_integral_gain_ = ZERO<RealT>;
+        }
       }
 
       /**

GridKit/Model/PhasorDynamics/Converter/REGCA/README.md

@@ -32,13 +32,16 @@ $V_{L0}$               | [p.u.]   | `VL0`    | LVPL zero-crossing voltage
 $V_{L1}$               | [p.u.]   | `VL1`    | LVPL upper breakpoint voltage                 | 0.9           | Source label: `brkpt`
 $V_{A0}$               | [p.u.]   | `VA0`    | LVACM lower breakpoint voltage                | 0.4           | Source label: `LVPnt0`
 $V_{A1}$               | [p.u.]   | `VA1`    | LVACM upper breakpoint voltage                | 0.9           | Source label: `LVPnt1`
-$V_\mathrm{hv}^{\max}$ | [p.u.]   | `Vhvmax` | HV reactive management activation threshold   | 1.2           | Source label: `VLim`
-$Q^{\min}$             | [p.u.]   | `Qmin`   | PowerWorld compatibility field                |               | Optional; accepted but unused
-$K_\mathrm{hv}$        | [p.u.]   | `Khv`    | HV reactive management gain                   | 0.7           | Optional; defaults to 0.7; block name: `Khv`
-$X_\mathrm{e}$         | [p.u.]   | `Xe`     | PowerWorld compatibility field                |               | Optional; accepted but unused
+$V_\mathrm{hv}^{\max}$ | [p.u.]   | `Vhvmax` | Terminal-voltage ceiling                      | 1.2           | Source label: `VLim`
+$Q^{\min}$             | [p.u.]   | `Qmin`   | Case-file compatibility field                 |               | Optional; accepted but unused
+$K_\mathrm{hv}$        | [p.u.]   | `Khv`    | Case-file compatibility field                 |               | Optional; accepted but unused
+$X_\mathrm{e}$         | [p.u.]   | `Xe`     | Case-file compatibility field                 |               | Optional; accepted but unused
 
 Omitted parameters default to 0 unless noted.
 
+`Qmin`, `Khv`, and `Xe` are retained for compatibility with existing case
+files and do not affect this model's equations.
+
 ### Parameter Validation
 
 A valid REGCA parameter set must satisfy the following conditions:
@@ -61,9 +64,7 @@ A valid REGCA parameter set must satisfy the following conditions:
   0
     &\le V_{L0} < V_{L1} \\
   0
-    &\le V_{A0} < V_{A1} < V_\mathrm{hv}^{\max} \\
-  0 \le K_\mathrm{hv}
-    &< \infty
+    &\le V_{A0} < V_{A1} < V_\mathrm{hv}^{\max}
 \end{aligned}
 ```
 
@@ -199,8 +200,7 @@ the sign that enables the corresponding limit.
   0 &= -k_\mathrm{base} V_T I_i
        - V_r(I_q - I_q^\mathrm{extra})
        + V_i I_p\,\text{linseg}(V_T; V_{A0}, V_{A1}, 1) \\
-  0 &= -I_q^\mathrm{extra}
-       + K_\mathrm{hv}\,\text{ramp}(V_T - V_\mathrm{hv}^{\max}) \\
+  0 &= -\text{min}(I_q^\mathrm{extra}, V_\mathrm{hv}^{\max}-V_T) \\
   0 &= -I_L
        + \text{linseg}(V_M; V_{L0}, V_{L1}, I_{L1})
        + K_L\,\text{ramp}(V_M - V_{L1}) \\
@@ -233,8 +233,8 @@ the sign that enables the corresponding limit.
 
 ### Internal Initialization
 
-Initialization requires $V_{A1}\le V_T$ and, with LVPL enabled, $I_p\le I_L$.
-All internal derivatives initialize to zero.
+Initialization requires $V_{A1}\le V_T<V_\mathrm{hv}^{\max}$ and, with LVPL enabled, $I_p\le I_L$.
+All internal derivatives initialize to zero. [Appendix C](#appendix-c-iramp) defines `iramp`.
 
 ```math
 \begin{aligned}
@@ -243,7 +243,7 @@ All internal derivatives initialize to zero.
   I_L &\leftarrow \text{linseg}(V_T;V_{L0},V_{L1},I_{L1})
     +K_L\,\text{ramp}(V_T-V_{L1}) \\
   I_p &\leftarrow \dfrac{k_\mathrm{base}P_0}{V_T\,\text{linseg}(V_T;V_{A0},V_{A1},1)} \\
-  I_q^\mathrm{extra} &\leftarrow K_\mathrm{hv}\,\text{ramp}(V_T-V_\mathrm{hv}^{\max}) \\
+  I_q^\mathrm{extra} &\leftarrow V_\mathrm{hv}^{\max}-V_T-\text{iramp}(V_\mathrm{hv}^{\max}-V_T) \\
   I_q &\leftarrow \dfrac{k_\mathrm{base}Q_0}{V_T}+I_q^\mathrm{extra} \\
   I_r &\leftarrow \dfrac{V_rP_0+V_iQ_0}{V_T^2} \\
   I_i &\leftarrow \dfrac{V_iP_0-V_rQ_0}{V_T^2} \\
@@ -333,3 +333,14 @@ The model evaluates this rule with the following smooth approximation:
 
 With a stationary bound ($\dot u = 0$) this reduces to the `antiwindup` of
 CommonMath restricted to its upper limit, which admits an algebraic bound $u$.
+
+## Appendix C: `iramp`
+
+For a positive smooth-ramp output $v>0$ and smoothing parameter $\mu$,
+
+```math
+\text{iramp}(v) = v+\dfrac{1}{\mu}\log(1-\exp(-\mu v))
+```
+
+This is the positive-range inverse of GridKit's smooth
+[`ramp`](../../../../CommonMath.md#ramp).

GridKit/Model/PhasorDynamics/Converter/REGCA/Regca.hpp

@@ -196,6 +196,8 @@ namespace GridKit
         ScalarT& Ir();
         ScalarT& Ii();
 
+        static RealT iramp(RealT value);
+
         static constexpr RealT TIME_CONSTANT_MINIMUM = static_cast<RealT>(1.0e-3);
         static constexpr RealT KL_                   = static_cast<RealT>(100.0);
         static void            logTimeConstantWarning();
@@ -218,7 +220,6 @@ namespace GridKit
         RealT VA0_{0};
         RealT VA1_{0};
         RealT Vhvmax_{0};
-        RealT Khv_{0.7};
 
         // Derived parameters
         RealT use_lvpl_{0};

GridKit/Model/PhasorDynamics/Converter/REGCA/RegcaData.hpp

@@ -32,11 +32,11 @@ namespace GridKit
         VL1,    ///< LVPL upper breakpoint voltage
         VA0,    ///< LVACM lower breakpoint voltage
         VA1,    ///< LVACM upper breakpoint voltage
-        Vhvmax, ///< Terminal-voltage activation threshold for HV reactive management
+        Vhvmax, ///< Terminal-voltage ceiling for HV reactive management
 
-        Qmin, ///< Optional PowerWorld compatibility field, accepted and unused
-        Khv,  ///< Optional HV reactive management gain, defaults to 0.7
-        Xe,   ///< Optional PowerWorld compatibility field, accepted and unused
+        Qmin, ///< Optional case-file compatibility field, accepted and unused
+        Khv,  ///< Optional case-file compatibility field, accepted and unused
+        Xe,   ///< Optional case-file compatibility field, accepted and unused
       };
 
       /// Buses for the REGCA converter model.