Skip to content

IEEEST Stabilizer Improvements/Corrections #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lukelowry wants to merge 10 commits into
base: develop
Choose a base branch
from
Draft

IEEEST Stabilizer Improvements/Corrections #460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ea23f7a
Fix bad parameter initialization and polish docs
lukelowry Jun 8, 2026
33c30c2
Update Docs
lukelowry Jun 8, 2026
3b1f563
isEqual change and tidy
lukelowry Jun 25, 2026
ba4fbe9
Hessenberg form
lukelowry Jun 26, 2026
0b0a21e
rebased IEEEST
lukelowry Jul 3, 2026
da5d04b
tempalte parameter for order implemetnations
lukelowry Jul 6, 2026
eecfa61
clean/correct ieeest impl per review
lukelowry Jul 9, 2026
44cc340
IeeestFactory rename
lukelowry Jul 22, 2026
35a101f
Add order as parameter
lukelowry Jul 22, 2026
5a00d48
zreo comparison
lukelowry Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion GridKit/Model/PhasorDynamics/INPUT_FORMAT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ are specified:
`Regca` | WECC REGCA renewable generator/converter model | `bus`, `ipcmd`\*, `iqcmd`\*, `ibranchr`\*, `ibranchi`\*, `pbranch`\*, `qbranch`\* | `p0`, `q0`, `mva`, `Tg`, `TM`, `Rqmax`, `Rqmin`, `Rpmax`, `sL`, `IL1`, `VL0`, `VL1`, `VA0`, `VA1`, `Vhvmax`, `Qmin`, `Khv`, `Xe` | `ir`, `ii`, `p`, `q`
`Ieeet1` | the IEEET1 exciter model | `bus`, `speed`, `efd`, `vs`\* | `Tr`, `Ka`, `Ta`, `Ke`, `Te`, `Kf`, `Tf`, `Vrmin`, `Vrmax`, `E1`, `E2`, `Se1`, `Se2`, `Ispdlim` | `efd`, `ksat`
`SexsPti` | the SEXS-PTI simplified exciter model | `bus`, `efd`, `vs`\* | `Ta`, `Tb`, `Te`, `K`, `Efdmax`, `Efdmin` | `efd`
`Ieeest` | the IEEEST stabilizer model | `input`, `output` | `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `T1`, `T2`, `T3`, `T4`, `T5`, `T6`, `Ks`, `Lsmin`, `Lsmax`, `Vcl`, `Vcu`, `Tdelay` | `vss`
`Ieeest` | the IEEEST stabilizer model | `input`, `output` | `order`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `T1`, `T2`, `T3`, `T4`, `T5`, `T6`, `Ks`, `Lsmin`, `Lsmax`, `Vcl`, `Vcu`, `Tdelay` | `vss`
`BusFault` | simple impedance-based fault at a bus | `bus`, `status`\* | `state0`, `R`, `X` | `state`, `ir`, `ii`
`BusToSignalAdapter` | signal adapter component for a bus | `bus`, `vr`, `vi`, `ir`, `ii` | |

Expand Down
2 changes: 1 addition & 1 deletion GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# - Luke Lowery <lukel@tamu.edu>
# ]]

set(_install_headers Ieeest.hpp IeeestData.hpp)
set(_install_headers Ieeest.hpp IeeestData.hpp IeeestFactory.hpp)

if(GRIDKIT_ENABLE_ENZYME)
gridkit_add_library(
Expand Down
16 changes: 12 additions & 4 deletions GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/Ieeest.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,25 @@ namespace GridKit
*
* @return int - error code, 0 = success
*/
template <typename scalar_type, typename index_type>
int Ieeest<scalar_type, index_type>::evaluateJacobian()
template <typename scalar_type, typename index_type, size_t order>
int Ieeest<scalar_type, index_type, order>::evaluateJacobian()
{
Log::misc() << "Evaluate Jacobian for Ieeest..." << std::endl;
Log::misc() << "Jacobian evaluation not implemented!" << std::endl;
return 0;
}

// Available template instantiations
template class Ieeest<double, long int>;
template class Ieeest<double, size_t>;
template class Ieeest<double, long int, 0>;
template class Ieeest<double, long int, 1>;
template class Ieeest<double, long int, 2>;
template class Ieeest<double, long int, 3>;
template class Ieeest<double, long int, 4>;
template class Ieeest<double, size_t, 0>;
template class Ieeest<double, size_t, 1>;
template class Ieeest<double, size_t, 2>;
template class Ieeest<double, size_t, 3>;
template class Ieeest<double, size_t, 4>;
} // namespace Stabilizer
} // namespace PhasorDynamics
} // namespace GridKit
123 changes: 85 additions & 38 deletions GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/Ieeest.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@

#pragma once

#include <cstddef>
#include <memory>
#include <vector>
Comment thread
nkoukpaizan marked this conversation as resolved.

#include <GridKit/Definitions.hpp>
#include <GridKit/Model/PhasorDynamics/Component.hpp>
#include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
#include <GridKit/Model/VariableMonitor.hpp>
Expand All @@ -16,6 +21,8 @@ namespace GridKit
{
namespace Stabilizer
{
enum class IeeestParameters;

template <typename real_type, typename index_type>
struct IeeestData;
} // namespace Stabilizer
Expand All @@ -32,34 +39,82 @@ namespace GridKit
{
namespace Stabilizer
{
/// Internal variables of a `Ieeest`
enum class IeeestInternalVariables : size_t
/// Active notch-filter state indices for each configured order.
template <size_t order>
struct IeeestNotchStates;

template <>
struct IeeestNotchStates<0>
{
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)
MAXIMUM,
};

template <>
struct IeeestNotchStates<1>
{
static constexpr size_t X1 = 0;
};

template <>
struct IeeestNotchStates<2>
{
static constexpr size_t X1 = 0;
static constexpr size_t X2 = 1;
};

template <>
struct IeeestNotchStates<3>
{
static constexpr size_t X1 = 0;
static constexpr size_t X2 = 1;
static constexpr size_t X3 = 2;
};

template <>
struct IeeestNotchStates<4>
{
static constexpr size_t X1 = 0;
static constexpr size_t X2 = 1;
static constexpr size_t X3 = 2;
static constexpr size_t X4 = 3;
};

/// Internal variable layout of a `Ieeest` by notch-filter order
template <size_t order>
struct IeeestVariables
{
static_assert(order <= 4, "Ieeest notch filter order must be in [0, 4]");

/// Shared variables follow the active notch-filter states.
enum class InternalVariables : size_t
{
X5 = order, ///< 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)
MAXIMUM,
};
};

/// Internal variables of a `Ieeest` of the given notch-filter order
template <size_t order>
using IeeestInternalVariables = typename IeeestVariables<order>::InternalVariables;

/// External variables of a `Ieeest`
enum class IeeestExternalVariables : size_t
{
U, ///< Stabilizer input signal
MAXIMUM,
};

template <typename scalar_type, typename index_type>
template <typename scalar_type, typename index_type, size_t order>
class Ieeest : public Component<scalar_type, index_type>
{
static_assert(order <= 4, "Ieeest notch filter order must be in [0, 4]");

using Component<scalar_type, index_type>::gridkit_component_id_;
using Component<scalar_type, index_type>::alpha_;
using Component<scalar_type, index_type>::f_;
Expand All @@ -71,7 +126,6 @@ namespace GridKit
using Component<scalar_type, index_type>::y_;
using Component<scalar_type, index_type>::yp_;
using Component<scalar_type, index_type>::wb_;
using Component<scalar_type, index_type>::h_;
using Component<scalar_type, index_type>::J_rows_buffer_;
using Component<scalar_type, index_type>::J_cols_buffer_;
using Component<scalar_type, index_type>::J_vals_buffer_;
Expand Down Expand Up @@ -104,7 +158,7 @@ namespace GridKit
auto getSignals()
-> ComponentSignals<ScalarT,
IdxT,
IeeestInternalVariables,
IeeestInternalVariables<order>,
IeeestExternalVariables>&
{
return signals_;
Expand All @@ -120,6 +174,8 @@ namespace GridKit
ScalarT*);

private:
static constexpr RealT TIME_CONSTANT_MINIMUM = static_cast<RealT>(1.0e-3);

RealT A1_{0};
RealT A2_{0};
RealT A3_{0};
Expand All @@ -139,34 +195,25 @@ namespace GridKit
RealT Vcu_{0};
RealT Tdelay_{0};

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};

ComponentSignals<ScalarT, IdxT, IeeestInternalVariables, IeeestExternalVariables> signals_;
int parameter_error_count_{0};

ComponentSignals<ScalarT, IdxT, IeeestInternalVariables<order>, IeeestExternalVariables> signals_;

std::unique_ptr<MonitorT> monitor_;

void initializeParameters(const ModelDataT& data);
void initializeMonitor();
void initializeParameters(const ModelDataT& data);
void initializeMonitor();
void setDerivedParameters();
void loadRealParameter(const ModelDataT& data,
IeeestParameters parameter,
RealT& target,
const char* name);
static int validateLeadingCoefficient(RealT value, const char* name);

std::vector<ScalarT> ws_;
std::vector<IdxT> ws_indices_;
Expand Down
1 change: 1 addition & 0 deletions GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/IeeestData.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ namespace GridKit
*/
enum class IeeestParameters
{
order, ///< Active order of the expanded notch-filter denominator
A1, ///< Notch filter denominator coefficient
A2, ///< Notch filter denominator coefficient
A3, ///< Notch filter denominator coefficient
Expand Down
16 changes: 12 additions & 4 deletions GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/IeeestDependencyTracking.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,25 @@ namespace GridKit
*
* @return int - error code, 0 = success
*/
template <typename scalar_type, typename index_type>
int Ieeest<scalar_type, index_type>::evaluateJacobian()
template <typename scalar_type, typename index_type, size_t order>
int Ieeest<scalar_type, index_type, order>::evaluateJacobian()
{
Log::misc() << "Evaluate Jacobian for Ieeest..." << std::endl;
Log::misc() << "Jacobian evaluation not implemented!" << std::endl;
return 0;
}

// Available template instantiations
template class Ieeest<DependencyTracking::Variable, long int>;
template class Ieeest<DependencyTracking::Variable, size_t>;
template class Ieeest<DependencyTracking::Variable, long int, 0>;
template class Ieeest<DependencyTracking::Variable, long int, 1>;
template class Ieeest<DependencyTracking::Variable, long int, 2>;
template class Ieeest<DependencyTracking::Variable, long int, 3>;
template class Ieeest<DependencyTracking::Variable, long int, 4>;
template class Ieeest<DependencyTracking::Variable, size_t, 0>;
template class Ieeest<DependencyTracking::Variable, size_t, 1>;
template class Ieeest<DependencyTracking::Variable, size_t, 2>;
template class Ieeest<DependencyTracking::Variable, size_t, 3>;
template class Ieeest<DependencyTracking::Variable, size_t, 4>;
} // namespace Stabilizer
} // namespace PhasorDynamics
} // namespace GridKit
23 changes: 16 additions & 7 deletions GridKit/Model/PhasorDynamics/Stabilizer/IEEEST/IeeestEnzyme.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ namespace GridKit
*
* @tparam ScalarT - Scalar data type
* @tparam IdxT - Index data type

@nkoukpaizan nkoukpaizan Jul 24, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note the changes in templating style in #410 and #505. Something to be careful with when rebasing. We'll have to make sure new instances of the old format are not introduced in new PRs.

* @tparam order - Notch filter order
* @return int - error code, 0 = success
*/
template <typename scalar_type, typename index_type>
int Ieeest<scalar_type, index_type>::evaluateJacobian()
template <typename scalar_type, typename index_type, size_t order>
int Ieeest<scalar_type, index_type, order>::evaluateJacobian()
{
Log::misc() << "Evaluate Jacobian for Ieeest..." << std::endl;
Log::misc() << "Jacobian evaluation is experimental!" << std::endl;
Expand All @@ -42,7 +43,7 @@ namespace GridKit

nnz_ = 0;

GridKit::Enzyme::Sparse::DfDy<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT>,
GridKit::Enzyme::Sparse::DfDy<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT, order>,
GridKit::Enzyme::Sparse::MemberFunctions::InternalResidualWithSignal>::eval(this,
static_cast<size_t>(f_.getSize()),
static_cast<size_t>(y_.getSize()),
Expand All @@ -57,7 +58,7 @@ namespace GridKit
J_vals_buffer_,
nnz_);

GridKit::Enzyme::Sparse::DfDyp<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT>,
GridKit::Enzyme::Sparse::DfDyp<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT, order>,
GridKit::Enzyme::Sparse::MemberFunctions::InternalResidualWithSignal>::eval(this,
static_cast<size_t>(f_.getSize()),
static_cast<size_t>(y_.getSize()),
Expand All @@ -73,7 +74,7 @@ namespace GridKit
J_vals_buffer_,
nnz_);

GridKit::Enzyme::Sparse::DfDws<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT>,
GridKit::Enzyme::Sparse::DfDws<GridKit::PhasorDynamics::Stabilizer::Ieeest<ScalarT, IdxT, order>,
GridKit::Enzyme::Sparse::MemberFunctions::InternalResidualWithSignal>::eval(this,
static_cast<size_t>(f_.getSize()),
ws_.size(),
Expand All @@ -94,8 +95,16 @@ namespace GridKit
}

// Available template instantiations
template class Ieeest<double, long int>;
template class Ieeest<double, size_t>;
template class Ieeest<double, long int, 0>;
template class Ieeest<double, long int, 1>;
template class Ieeest<double, long int, 2>;
template class Ieeest<double, long int, 3>;
template class Ieeest<double, long int, 4>;
template class Ieeest<double, size_t, 0>;
template class Ieeest<double, size_t, 1>;
template class Ieeest<double, size_t, 2>;
template class Ieeest<double, size_t, 3>;
template class Ieeest<double, size_t, 4>;

} // namespace Stabilizer
} // namespace PhasorDynamics
Expand Down
Loading
Loading