Skip to content

Commit f7b5020

Browse files
lukelowrylukelowry
committed
Add HYGOV phasor dynamics governor
1 parent 40b5b3a commit f7b5020

25 files changed

Lines changed: 1820 additions & 17 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@
6464
- Added off-nominal tap ratio and phase shift support to the PhasorDynamics `Branch` model.
6565
- Added portable Vector class to GridKit
6666
- Added support for running IDA with fixed time steps
67+
- Added `HYGOV` governor model implementation for PhasorDynamics.
6768

6869
## v0.1
6970

‎GridKit/CommonMath.hpp‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,31 @@ namespace GridKit
162162
}
163163

164164
/**
165-
* @brief Smooth two-sided deadband function
165+
* @brief Smooth Type 1 no-offset two-sided deadband function
166+
*
167+
* Smooth approximation to a deadband that returns zero inside the band and
168+
* passes the input through unchanged outside the band.
169+
*
170+
* @tparam ScalarT - scalar data type
171+
* @tparam RealT - Real data type (see GridKit::ScalarTraits<ScalarT>::RealT)
172+
*
173+
* @param[in] x - Input signal
174+
* @param[in] lower - Lower breakpoint
175+
* @param[in] upper - Upper breakpoint
176+
* @return Smooth no-offset deadbanded value
177+
*/
178+
template <class ScalarT, typename RealT>
179+
__attribute__((always_inline)) inline ScalarT deadband1(
180+
const ScalarT x,
181+
const RealT lower,
182+
const RealT upper)
183+
{
184+
assert(lower <= upper);
185+
return x * (sigmoid(lower - x) + sigmoid(x - upper));
186+
}
187+
188+
/**
189+
* @brief Smooth Type 2 offset two-sided deadband function
166190
*
167191
* Smooth approximation to x - min(max(x, lower), upper), composed from the
168192
* smooth ramp function.
@@ -173,10 +197,10 @@ namespace GridKit
173197
* @param[in] x - Input signal
174198
* @param[in] lower - Lower breakpoint
175199
* @param[in] upper - Upper breakpoint
176-
* @return Smooth deadbanded value
200+
* @return Smooth offset deadbanded value
177201
*/
178202
template <class ScalarT, typename RealT>
179-
__attribute__((always_inline)) inline ScalarT deadband(
203+
__attribute__((always_inline)) inline ScalarT deadband2(
180204
const ScalarT x,
181205
const RealT lower,
182206
const RealT upper)

‎GridKit/Model/PhasorDynamics/ComponentLibrary.hpp‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
#include <GridKit/Model/PhasorDynamics/BusToSignalAdapter/BusToSignalAdapter.hpp>
88
#include <GridKit/Model/PhasorDynamics/Exciter/IEEET1/Ieeet1.hpp>
99
#include <GridKit/Model/PhasorDynamics/Exciter/SEXS-PTI/SexsPti.hpp>
10+
#include <GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.hpp>
1011
#include <GridKit/Model/PhasorDynamics/Governor/Tgov1/Tgov1.hpp>
1112
#include <GridKit/Model/PhasorDynamics/Load/Load.hpp>
1213
#include <GridKit/Model/PhasorDynamics/LoadZIP/LoadZIP.hpp>

‎GridKit/Model/PhasorDynamics/Governor/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@
44
# ]]
55

66
add_subdirectory(Tgov1)
7+
add_subdirectory(HYGOV)

‎GridKit/Model/PhasorDynamics/Governor/HYGOV/CMakeLists.txt‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# [[
2+
# Author(s):
3+
# - Luke Lowery <lukel@tamu.edu>
4+
# ]]
5+
6+
set(_install_headers Hygov.hpp HygovData.hpp)
7+
8+
if(GRIDKIT_ENABLE_ENZYME)
9+
gridkit_add_library(
10+
phasor_dynamics_governor_hygov
11+
SOURCES HygovEnzyme.cpp
12+
HEADERS ${_install_headers}
13+
INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
14+
LINK_LIBRARIES
15+
PUBLIC
16+
GridKit::phasor_dynamics_core
17+
PUBLIC
18+
GridKit::phasor_dynamics_signal
19+
PRIVATE
20+
ClangEnzymeFlags
21+
COMPILE_OPTIONS
22+
PRIVATE
23+
-mllvm
24+
-enzyme-auto-sparsity=1
25+
-fno-math-errno)
26+
else()
27+
gridkit_add_library(
28+
phasor_dynamics_governor_hygov
29+
SOURCES Hygov.cpp
30+
HEADERS ${_install_headers}
31+
INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
32+
LINK_LIBRARIES
33+
PUBLIC
34+
GridKit::phasor_dynamics_core
35+
PUBLIC
36+
GridKit::phasor_dynamics_signal)
37+
endif()
38+
39+
gridkit_add_library(
40+
phasor_dynamics_governor_hygov_dependency_tracking
41+
SOURCES HygovDependencyTracking.cpp
42+
INCLUDE_DIRECTORIES PRIVATE ${GRIDKIT_THIRD_PARTY_DIR}/magic-enum/include
43+
LINK_LIBRARIES
44+
PUBLIC
45+
GridKit::phasor_dynamics_core
46+
PUBLIC
47+
GridKit::phasor_dynamics_signal_dependency_tracking)
48+
49+
target_link_libraries(
50+
phasor_dynamics_components
51+
INTERFACE GridKit::phasor_dynamics_governor_hygov)
52+
target_link_libraries(
53+
phasor_dynamics_components_dependency_tracking
54+
INTERFACE GridKit::phasor_dynamics_governor_hygov_dependency_tracking)

‎GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.cpp‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/**
2+
* @file Hygov.cpp
3+
* @author Luke Lowery (lukel@tamu.edu)
4+
* @brief Non-Enzyme instantiation for the HYGOV governor model.
5+
*/
6+
7+
#include "HygovImpl.hpp"
8+
9+
namespace GridKit
10+
{
11+
namespace PhasorDynamics
12+
{
13+
namespace Governor
14+
{
15+
template <typename scalar_type, typename index_type>
16+
int Hygov<scalar_type, index_type>::evaluateJacobian()
17+
{
18+
Log::misc() << "Evaluate Jacobian for Hygov..." << std::endl;
19+
Log::misc() << "Jacobian evaluation is not implemented!" << std::endl;
20+
return 0;
21+
}
22+
23+
template class Hygov<double, long int>;
24+
template class Hygov<double, size_t>;
25+
} // namespace Governor
26+
} // namespace PhasorDynamics
27+
} // namespace GridKit

‎GridKit/Model/PhasorDynamics/Governor/HYGOV/Hygov.hpp‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
/**
2+
* @file Hygov.hpp
3+
* @author Luke Lowery (lukel@tamu.edu)
4+
* @brief Declaration of the HYGOV governor model.
5+
*/
6+
7+
#pragma once
8+
9+
#include <array>
10+
#include <cstddef>
11+
#include <memory>
12+
#include <vector>
13+
14+
#include <GridKit/Model/PhasorDynamics/Component.hpp>
15+
#include <GridKit/Model/PhasorDynamics/ComponentSignals.hpp>
16+
#include <GridKit/Model/PhasorDynamics/Governor/HYGOV/HygovData.hpp>
17+
#include <GridKit/Model/VariableMonitor.hpp>
18+
19+
namespace GridKit
20+
{
21+
namespace PhasorDynamics
22+
{
23+
template <typename scalar_type, typename index_type>
24+
class SignalNode;
25+
26+
namespace Governor
27+
{
28+
/// Internal variables of a `Hygov`.
29+
enum class HygovInternalVariables : size_t
30+
{
31+
XN, ///< Speed lead-lag denominator state
32+
XF, ///< Governor error filter output
33+
C, ///< Desired-gate position
34+
G, ///< Gate position
35+
Q, ///< Turbine flow
36+
OMEGADB, ///< Deadbanded speed deviation
37+
YOMEGA, ///< Lead-lag-conditioned speed signal
38+
EF, ///< Governor error into the filter
39+
FC, ///< Desired-gate derivative target
40+
RC, ///< Rate-limited desired-gate derivative target
41+
PGV, ///< Nonlinear gate-to-power curve output
42+
PGVSAFE, ///< Safe gate-to-power value
43+
H, ///< Turbine head
44+
PMECH, ///< Mechanical-power output
45+
MAXIMUM,
46+
};
47+
48+
/// External variables of a `Hygov`.
49+
enum class HygovExternalVariables : size_t
50+
{
51+
OMEGA, ///< Machine speed deviation
52+
PREF, ///< Active-power/load reference
53+
PAUX, ///< Auxiliary power input
54+
MAXIMUM,
55+
};
56+
57+
template <typename scalar_type, typename index_type>
58+
class Hygov : public Component<scalar_type, index_type>
59+
{
60+
using Component<scalar_type, index_type>::alpha_;
61+
using Component<scalar_type, index_type>::f_;
62+
using Component<scalar_type, index_type>::gridkit_component_id_;
63+
using Component<scalar_type, index_type>::J_;
64+
using Component<scalar_type, index_type>::J_cols_buffer_;
65+
using Component<scalar_type, index_type>::J_rows_buffer_;
66+
using Component<scalar_type, index_type>::J_vals_buffer_;
67+
using Component<scalar_type, index_type>::residual_indices_;
68+
using Component<scalar_type, index_type>::size_;
69+
using Component<scalar_type, index_type>::tag_;
70+
using Component<scalar_type, index_type>::variable_indices_;
71+
using Component<scalar_type, index_type>::wb_;
72+
using Component<scalar_type, index_type>::y_;
73+
using Component<scalar_type, index_type>::yp_;
74+
75+
public:
76+
using ScalarT = scalar_type;
77+
using IdxT = index_type;
78+
using RealT = typename Component<ScalarT, IdxT>::RealT;
79+
using SignalT = SignalNode<ScalarT, IdxT>;
80+
using ModelDataT = HygovData<RealT, IdxT>;
81+
using MonitorT = Model::VariableMonitor<Hygov, HygovData>;
82+
83+
Hygov();
84+
Hygov(const ModelDataT& data);
85+
~Hygov();
86+
87+
int setGridKitComponentID(IdxT) override final;
88+
int allocate() override final;
89+
int verify() const override final;
90+
int initialize() override final;
91+
int tagDifferentiable() override final;
92+
int evaluateResidual() override final;
93+
int evaluateJacobian() override final;
94+
95+
auto getSignals()
96+
-> ComponentSignals<ScalarT,
97+
IdxT,
98+
HygovInternalVariables,
99+
HygovExternalVariables>&
100+
{
101+
return signals_;
102+
}
103+
104+
const Model::VariableMonitorBase* getMonitor() const override;
105+
106+
__attribute__((always_inline)) inline int evaluateInternalResidual(
107+
ScalarT*, ScalarT*, ScalarT*, ScalarT*, ScalarT*);
108+
109+
private:
110+
void initModelParams(const ModelDataT& data);
111+
void initializeMonitor();
112+
113+
ScalarT gatePower(ScalarT gate) const;
114+
RealT invertGatePower(RealT pgv) const;
115+
ScalarT toComponentBase(ScalarT value) const;
116+
ScalarT toPmechBase(ScalarT value) const;
117+
118+
RealT Trate_{0};
119+
RealT pmech_mva_base_{0};
120+
RealT Rperm_{0};
121+
RealT Rtemp_{0};
122+
RealT Tr_{0};
123+
RealT Tf_{0};
124+
RealT Tg_{0};
125+
RealT Velm_{0};
126+
RealT Gmax_{0};
127+
RealT Gmin_{0};
128+
RealT Tw_{0};
129+
RealT At_{0};
130+
RealT Dturb_{0};
131+
RealT Qnl_{0};
132+
RealT Tn_{0};
133+
RealT Tnp_{0};
134+
RealT leadlag_gain_{0};
135+
RealT db1_{0};
136+
RealT db2_{0};
137+
RealT Hdam_{1};
138+
std::array<RealT, 6> Gv_{};
139+
std::array<RealT, 6> Pgv_{};
140+
141+
IdxT parameter_error_count_{0};
142+
143+
ScalarT pref_set_{0};
144+
ScalarT paux_set_{0};
145+
146+
ComponentSignals<ScalarT, IdxT, HygovInternalVariables, HygovExternalVariables> signals_;
147+
std::unique_ptr<MonitorT> monitor_;
148+
149+
std::vector<ScalarT> ws_;
150+
std::vector<IdxT> ws_indices_;
151+
};
152+
} // namespace Governor
153+
} // namespace PhasorDynamics
154+
} // namespace GridKit

‎GridKit/Model/PhasorDynamics/Governor/HYGOV/HygovData.hpp‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
/**
2+
* @file HygovData.hpp
3+
* @author Luke Lowery (lukel@tamu.edu)
4+
* @brief Modeling data for the HYGOV governor model.
5+
*/
6+
7+
#pragma once
8+
9+
#include <GridKit/Model/PhasorDynamics/ComponentData.hpp>
10+
11+
namespace GridKit
12+
{
13+
namespace PhasorDynamics
14+
{
15+
namespace Governor
16+
{
17+
/// Parameter keys for the HYGOV governor model.
18+
enum class HygovParameters
19+
{
20+
Trate, ///< Turbine-rating power base
21+
mva, ///< MVA base of the pmech signal
22+
Rperm, ///< Permanent droop
23+
Rtemp, ///< Temporary droop
24+
Tr, ///< Temporary-droop reset time constant
25+
Tf, ///< Governor error filter time constant
26+
Tg, ///< Gate servo time constant
27+
Velm, ///< Maximum desired-gate velocity magnitude
28+
Gmax, ///< Maximum desired-gate position
29+
Gmin, ///< Minimum desired-gate position
30+
Tw, ///< Water inertia time constant
31+
At, ///< Turbine gain
32+
Dturb, ///< Turbine damping coefficient
33+
Qnl, ///< No-load flow at nominal head
34+
Tn, ///< Speed lead-lag numerator time constant
35+
Tnp, ///< Speed lead-lag denominator time constant
36+
db1, ///< Type 1 speed deadband threshold
37+
db2, ///< Unsupported mechanical backlash deadband
38+
Hdam, ///< Head available at dam
39+
Gv0, ///< Gate point 0
40+
Gv1, ///< Gate point 1
41+
Gv2, ///< Gate point 2
42+
Gv3, ///< Gate point 3
43+
Gv4, ///< Gate point 4
44+
Gv5, ///< Gate point 5
45+
Pgv0, ///< Power point 0
46+
Pgv1, ///< Power point 1
47+
Pgv2, ///< Power point 2
48+
Pgv3, ///< Power point 3
49+
Pgv4, ///< Power point 4
50+
Pgv5 ///< Power point 5
51+
};
52+
53+
/// Ports for the HYGOV governor model.
54+
enum class HygovPorts
55+
{
56+
bus, ///< Optional terminal bus ID for case-format compatibility
57+
speed, ///< Machine speed-deviation signal ID
58+
pmech, ///< Mechanical-power output signal ID
59+
pref, ///< Optional active-power/load reference signal ID
60+
paux ///< Optional auxiliary power input signal ID
61+
};
62+
63+
/// Variables available through the monitor interface.
64+
enum class HygovMonitorableVariables
65+
{
66+
pmech, ///< Mechanical power output
67+
leadlag, ///< Speed lead-lag denominator state
68+
filter, ///< Governor error filter output
69+
desiredgate, ///< Desired-gate position
70+
gate, ///< Gate position
71+
flow, ///< Turbine flow
72+
head, ///< Turbine head
73+
pgv ///< Nonlinear gate-to-power curve output
74+
};
75+
76+
template <typename real_type, typename index_type>
77+
struct HygovData : public ComponentData<real_type,
78+
index_type,
79+
HygovParameters,
80+
HygovPorts,
81+
HygovMonitorableVariables>
82+
{
83+
HygovData() = default;
84+
85+
using Parameters = HygovParameters;
86+
using Ports = HygovPorts;
87+
using MonitorableVariables = HygovMonitorableVariables;
88+
};
89+
} // namespace Governor
90+
} // namespace PhasorDynamics
91+
} // namespace GridKit

0 commit comments

Comments
 (0)