Support voltage-regulator Q limits and PV→PQ switching #1452
Support voltage-regulator Q limits and PV→PQ switching #1452scud-soptim wants to merge 6 commits into
Conversation
- add bus_type to node output
- implement feature in newton_raphson solver
- implmentet iterative equal distribution of Q at the end
- try distributing equally
- if individual regulator limit is violated, then save unallocated
amount and distribute again in next iteration
Signed-off-by: Eduard Fried <eduard.fried@soptim.de>
Signed-off-by: Eduard Fried <eduard.fried@soptim.de>
Signed-off-by: Eduard Fried <eduard.fried@soptim.de>
Signed-off-by: SCUD-SOPTIM <udo.schmitz@soptim.de>
Signed-off-by: Eduard Fried <eduard.fried@soptim.de>
figueroa1395
added
documentation
|
Hello @scud-soptim and @frie-soptim, Thank you once more for your contribution! Since this is a large and very involved PR, I'll give some initial comments:
Additionally, we notice that this PR only includes the Q-limit handling and not yet the voltage-setpoint controller as described in #1236. We agree with this decision. Let's keep the scope of this PR strictly to the Q-limit handling and leave the voltage-setpoint controller for a follow up discussion. That said, I'll add a few additional remarks about this in the issue itself. |
figueroa1395
left a comment
figueroa1395
left a comment
There was a problem hiding this comment.
@scud-soptim , @frie-soptim As always, great job!
Some additional comments:
- CI is broken, but it's just minor stuff.
- I see merge conflicts due to a recently merged documentation PR. Let us know if you want us to help resolving those.
- There's some TODOs in
power_grid_model_c/power_grid_model/include/power_grid_model/math_solver/common_solver_functions.hpp, I agree that those should be implemented. - The logic looks good, no comment yet about that part.
- The rest of the review will follow tomorrow :)
| - Voltage controlled bus: a bus with known $P$ and $U$. | ||
| Note: this bus is not supported by power-grid-model yet. | ||
| - Voltage-controlled bus: a bus with known active power $P$ and voltage magnitude $U$. In power-grid-model this is | ||
| modeled by an active `voltage_regulator` on a regulated load or generator and is supported by the Newton-Raphson |
There was a problem hiding this comment.
Maybe add a hyperlink for voltage_regulator here.
| }, | ||
| { | ||
| "data_type": "IntS", | ||
| "names": ["bus_type"], | ||
| "description": "effective bus type after calculation" |
There was a problem hiding this comment.
I'm not sure about this new output attribute. As you describe in the documentation below, doesn't the voltage_regulator.limit_violated output attribute already give enough information to determine if its bus is in PQ or PV mode? Or if multiple regulators are attached to the same node, just "loop" over such attributes?
The reason I'm hesitant is because this would now be an output attribute present for all calculation types and methods, but it's only useful for Newton Raphson Power Flow.
| ``` | ||
|
|
||
| ```{warning} | ||
| `bus_type` output is available only for the [Newton-Raphson power flow](./calculations.md#newton-raphson-power-flow) method; for other methods, `bus_type` is set to `0` (PQ) by default. |
There was a problem hiding this comment.
This is what I meant in https://github.com/PowerGridModel/power-grid-model/pull/1452/changes#r3504924406. How important is this attribute for you? Rather than bus_type only being available for Newton-Raphson Power Flow, the case is that it's only relevant for that method, but it's "available", albeit useless, for the rest.
| Voltage regulation is supported only by the [Newton-Raphson power flow](./calculations.md#newton-raphson-power-flow) | ||
| method. |
There was a problem hiding this comment.
Can you leave this as a warning or note please?
| return node.template get_null_output<sym>(); | ||
| } | ||
| auto bus_type = BusType::pq; | ||
| if (solver_output[math_id.group].bus.size() == solver_output[math_id.group].u.size()) { |
| } | ||
|
|
||
| // apply distributed Q to load_gens | ||
| for (auto const& [idx, load_gen] : enumerate(load_gens)) { |
There was a problem hiding this comment.
I think regulating_gens already contains the relevant load_gens. That would also remove the need for the status check below.
| for (auto const& [idx, load_gen] : enumerate(load_gens)) { | ||
| if (!loadgen_to_regulator.contains(load_gen)) { | ||
| continue; | ||
| } |
There was a problem hiding this comment.
You can also pass as argument to this function the list of relevant ones.
| if (std::abs(base_total) > numerical_tolerance) { | ||
| double const scale = q_scalar / base_total; | ||
| return RealValue<asymmetric_t>{base_distribution(0) * scale, base_distribution(1) * scale, | ||
| base_distribution(2) * scale}; | ||
| } | ||
| return RealValue<asymmetric_t>{q_scalar / 3.0, q_scalar / 3.0, q_scalar / 3.0}; |
There was a problem hiding this comment.
This logic looks very similar to what's done in allocate_q_bus_limit_violated when distributing. With some minor refactoring it can probably be made into a helper function.
|
|
||
| // auto num_regulating_gens = static_cast<double>(std::ranges::distance(regulating_gens)); // <- fails in windows | ||
| // build | ||
| double num_regulating_gens = 0.0; |
There was a problem hiding this comment.
I just realized, why is this a double?
| // When a regulator hits its limit, it is removed from the active set and the unallocated Q is | ||
| // redistributed among the remaining regulators. Unallocated Q remaining after all regulators hit | ||
| // their limits should not occur, as then the bus would have been switched to a PQ bus. | ||
| while (std::abs(total_q(q_remaining)) > numerical_tolerance && num_regulating_gens > 0.0) { |
There was a problem hiding this comment.
Could this get into an infinite loop?
figueroa1395
left a comment
figueroa1395
left a comment
There was a problem hiding this comment.
Some additional comments
| // keep copy, as reference might break batching | ||
| auto derived_solver = static_cast<DerivedSolver&>(*this); |
There was a problem hiding this comment.
The comment changed but the line below didn't. Also, this is still a reference to the BaseSolver which is then casted to a reference to the DerivedSolver.
Or is this to reinforce the absence of auto& instead of auto there? Can you try with auto&? If I recall correctly we create a solver per thread/set of batches and per independent grid, so I imagine this shouldn't be an issue.
| // finalize | ||
| { | ||
| // Timer const sub_timer{log, LogEvent::calculate_math_result}; // TODO(mgovers): need new event ?!? | ||
| derived_solver.finalize_derived_result(input, output); | ||
| } | ||
|
|
There was a problem hiding this comment.
Is the TODO a question to us?
Also, maybe doing something along the lines of
template <typename DerivedSolver>
void finalize(DerivedSolver& derived_solver, PowerFlowInput<sym> const& input, SolverOutput<sym> const& output) {
if constexpr (requires { derived_solver.finalize_derived_result(input, output); }) {
derived_solver.finalize_derived_result(input, output);
}
}makes sense so we don't have to include no-op finalize_derived_result in other solvers other than the Newton-Raphson one.
|
|
||
| void parameters_changed(bool changed) { parameters_changed_ = parameters_changed_ || changed; } | ||
|
|
||
| void finalize_derived_result(PowerFlowInput<sym> const& /*input*/, SolverOutput<sym>& /*output*/) { |
There was a problem hiding this comment.
| // initialize with BusType::pq, set calculated value in newton_raphson solver | ||
| BusType bus_type{BusType::pq}; | ||
| // 0: no violation, -1: q_min violated, 1: q_max violated | ||
| IntS q_limit_violated{0}; |
There was a problem hiding this comment.
Let's make this use a named variable or enum please.
There was a problem hiding this comment.
Thanks for the useful description of what's going on.
Additionally, would it make sense that for the node with two regulators, one violates q_max and the other violates q_min but they compensate each other? If this makes sense, can you add such a test? The same for the situation in which both violate opposite boundaries but they aren't able to compensate and the node becomes PQ instead.
figueroa1395
left a comment
figueroa1395
left a comment
There was a problem hiding this comment.
To be continued. I'm almost done now :)
| // TODO(frie-soptim): remove experimental feature, but add option to globally disable q-limit handling even if | ||
| // limits are set?! |
There was a problem hiding this comment.
- Let's remove the experimental feature flag as the last step indeed.
- How do you propose to add this switch? Would leaving the q-limits un-initialized or set as
nanenough? So when that's the case the regulator behaves as if it had an "infinite" pool ofqto regulate? Or is this switch important for you?
If so, perhaps a bool to turn on-off the q-limits at the voltage regulator component-level is enough?
| // todo(frie-soptim): use "max_iter == 1" to indicate that this is the base case for a batch run, | ||
| // and thus q-limit handling does not apply here | ||
| // => maybe find a better solution |
There was a problem hiding this comment.
Indeed using max_iter isn't ideal. This would be problematic in the hypothetical case of running with 1 iteration only and q-limit-handling enabled. It's also not very readable.
Instead, I have the following suggestion:
In
Options is available, which also contains cache_run. With this in mind, you can modify the signature of run_power_flow in the math_solver at cache_run as an argument and propagate this "flag" downstream to the important code block. Don't forget to update the other solver's signatures and base class if necessary, but only NRPF should "consume" cache_run.
This way we have minimal changes and have a readable reason of why to ignore q-limit-handling (it's the first cache run). What do you think? Other suggestions are welcome.
| // TODO(frie-soptim): sets max_iter to 1, which must handled in the newton-raphson solver for batch mode. Is | ||
| // there a better solution? |
| auto& bus_control = bus_control_[bus_idx]; | ||
| if (!sources.empty()) { | ||
| bus_types_[bus_idx] = BusType::slack; | ||
| bus_control.type = BusType::slack; |
There was a problem hiding this comment.
Reinforcing on earlier comments. slack type is only here for convenience but can be easily deduced as well starting from your comment. In addition, unless we would also make such changes in other solvers, I don't think we should add BusType to output types.
In addition, we had added such a check at construction time already, right? As in PGM would throw if a regulator is added where there is a source, right?
| std::vector<BusType> bus_types_; | ||
| struct QLimitState { | ||
| bool has_q_limits{false}; // check before using limits | ||
| IntS limit_violated{0}; // -1: q_min, +1: q_max |
There was a problem hiding this comment.
Let's add an enum for this instead.
| for (Idx const load_gen : load_gens) { | ||
| for (Idx const regulator : regulators_per_load_gen.get_element_range(load_gen)) { | ||
| if (input.load_gen_status[load_gen] != 0 && input.voltage_regulator[regulator].status != 0) { | ||
| specified_regulating_q += specified_q(load_gen, bus, input); |
There was a problem hiding this comment.
I don't quite remember if having an asym and a sym load on the same node is allowed nor if this would handle it correctly. Could you make sure it's unit tested to make sure?
| // initialize bus state, in case solver instance is reused in batching | ||
| std::ranges::fill(bus_control_, BusControlState{}); | ||
|
|
||
| q_limits_need_initial_check_ = set_u_ref_and_bus_types_and_q_limits(input, output.u); |
There was a problem hiding this comment.
Why the variable name change from has_usable_q_limits? Later in prepare_matrix_and_rhs it becomes confusing, does that need to have q-limits available or do they need to also be in some sort of state that requires intiial check?
| // = (Q_specified_regulating + Q_specified_nonregulating - del_x_pq_[bus].q()) | ||
| // - Q_specified_nonregulating | ||
| // = Q_specified_regulating - del_x_pq_[bus].q() |
There was a problem hiding this comment.
These couple of lines made me a bit confused. With
Since Q_specified_all = Q_specified_regulating + Q_specified_nonregulating
and the above equation we can reach the desired result. Could you remove them?
| const bool buses_switched = !q_limits_need_initial_check_ && enforce_q_limits(input); | ||
| if (buses_switched) { | ||
| // rebuild jacobian and del_pq after PV -> PQ switching | ||
| build_jacobian_and_rhs(y_bus, input, u); |
There was a problem hiding this comment.
I believe only add_loads and add_sources would be "affected" or important in this additional re-build. Would it be possible to do that instead of a full rebuild? So a partial one instead?
Or does that make the logic too complex and not worth the effort given the small gains? Please think about this.
On the other hand, I see that a first full build is needed because you use del_x_pq_[bus].q() to determine q_limits. Would it be possible to consider using a "base reference" from the previous run or an approximated one from the initial "guess" start? This is thinking on how not to do two builds.
| return 1; | ||
| } | ||
| if (!is_nan(q_min) && q_total < q_min - numerical_tolerance) { | ||
| return -1; | ||
| } | ||
| return 0; |
|
Hi, we'll answer your questions when Frie returns from vacation. |
figueroa1395
left a comment
figueroa1395
left a comment
There was a problem hiding this comment.
Double checking, but is there any additional validation needed on the python side? Say anything regarding the q-limits for instance? What would happen if q_min is set to 1 and q_max to -1 by mistake? I imagine this should be catched by both the validator and a hard error thrown?
Can you add some unit testing handling sym and asym regulated loads on a node? one violating limits, both violating limits, and both not violating limits?
I think I should be done with the overall review. If I have anything else to comment on, I'll mention it once Frie is back so this doesn't grow even more.
| // The specified Q values from regulating generators were already added to del_x_pq_[bus].q() | ||
| // in add_loads(). To extract the ACTUAL Q that regulators are providing (including their | ||
| // contribution to voltage control), we must "subtract back out" this mismatch term. | ||
| // This works because: actual = specified - mismatch. |
There was a problem hiding this comment.
Does this mean Q_calc_network = Q_specified_all - del_x_pq_[bus].q() as indicated above, or is this line referring to something different and I am miss-understanding things?
| clamped_regulators_per_load_gen_[load_gen] = RealValue<asymmetric_t>{ | ||
| q_limit_scalar / 3.0, q_limit_scalar / 3.0, q_limit_scalar / 3.0}; |
There was a problem hiding this comment.
Is this fallback physically meaningful enough? Could it happen that the input q is zero but the regulators fall out of the limit anyway? Could you test this?
| // TODO(frie-soptim): don't forget to reset regulators if the bus is switched back to PV in the future | ||
| // clamped_regulators_per_load_gen_[load_gen] = RealValue<sym>{nan}; | ||
|
|
There was a problem hiding this comment.
This would only be relevant in case we enable switching back from PQ to PV after the first PV to PQ transition has already happened because the limits were violated, right?
So for now, this isn't relevant, correct?
| static bool is_value_nan(RealValue<sym> const& value) { | ||
| if constexpr (is_symmetric_v<sym>) { | ||
| return is_nan(value); | ||
| } else { | ||
| // all three phases are set together, need to check only one phase for NaN | ||
| return is_nan(value(0)); |
There was a problem hiding this comment.
Why is this needed? Wouldn't the overload of is_nan present in common.hpp already work for this?
| // load_gen hit a Q-limit, use the clamped value | ||
| del_x_pq_[bus_number].p() += real(input.s_injection[load_number]); | ||
| del_x_pq_[bus_number].q() += clamped_q; | ||
| // TODO(frie-soptim): prevent regulation of const_i/const_y load_gens in validation |
| CHECK(imag(output.load_gen[0].s) > -1.0); | ||
| CHECK(imag(output.load_gen[0].s) < 1.0); |
There was a problem hiding this comment.
I imaging checking for the exact value is not practical? But double checking why a range instead? Also, why not check for q directly?
| TEST_CASE_TEMPLATE_INVOKE(test_math_solver_pf_id, NewtonRaphsonPFSolver<symmetric_t>); | ||
| TEST_CASE_TEMPLATE_INVOKE(test_math_solver_pf_id, NewtonRaphsonPFSolver<asymmetric_t>); | ||
|
|
||
| TEST_CASE("Newton-Raphson PV reactive-power limits switch one-way to PQ") { |
There was a problem hiding this comment.
I think the name is a bit missleading since in the first subcase it never switches to PQ since no limits are violated.
| } | ||
| } | ||
|
|
||
| TEST_CASE("Newton-Raphson PV reactive-power limit switches are deterministic") { |
There was a problem hiding this comment.
Why the "deterministic" in the name? Curious.
| CHECK(output.bus[3].bus_type == BusType::pv); // Two regulators | ||
| } | ||
|
|
||
| SUBCASE("Single regulator controls voltage") { |
There was a problem hiding this comment.
Can you explicitly check the other remaining two don't?
There was a problem hiding this comment.
Incredibly extended testing! Kudos for the awesome work!
There was a problem hiding this comment.
....we answer next week to your comments....
There was a problem hiding this comment.
@scud-soptim No problem and no rush, I just wanted to finish the overall review before moving on. We won't be making any more comments/reviews until you have had the time to read and address the current ones.
Signed-off-by: Martijn Govers <martijn.govers@alliander.com>
|
Hello @scud-soptim and @frie-soptim, Once small remark for when you return. We have enabled mandatory cryptographic signing for the PGM-org. Could you please amend your commits and either This was announced during the last community meeting, where @scud-soptim was present. |
4 participants
Implements #1236
Summary
This PR adds reactive-power limit handling for voltage-regulated nodes in Newton-Raphson power-flow calculations.
An active
voltage_regulatornow models the regulated node as a PV node by enforcing the configured voltage magnitudeu_ref. If the reactive power required to maintain this voltage violatesq_minorq_max, the regulated object is clamped to the violated limit and the effective node type is switched from PV to PQ.The PR also exposes the effective node type in steady-state node output and documents the voltage-regulator behavior, including PV→PQ switching and reactive-power allocation when multiple regulators are connected to the same node.
Main changes
Add effective
bus_typeto steady-state node output.0: PQ1: PV2: Source/SlackExtend voltage-regulator steady-state output with a limit indicator.
-1: lower reactive-power limitq_minreached0: no limit violation1: upper reactive-power limitq_maxreachedImplement PV-node handling in Newton-Raphson power flow for active voltage regulators.
Implement PV→PQ switching when the required reactive power violates configured Q limits.
Clamp the regulated object to the violated Q limit after switching to PQ.
Propagate final bus type and Q-limit status to steady-state output.
Add and update tests for voltage-regulator Q-limit behavior, PV→PQ switching, batch updates, and output metadata.
Update user documentation for voltage-regulator behavior and power-flow algorithm details.
Reactive-power allocation with multiple voltage regulators
When multiple active voltage regulators are connected to the same node, they jointly regulate the same node voltage. The required reactive power is initially distributed equally over the active regulated objects. If one regulator reaches its individual
q_minorq_max, it is clamped at that limit and removed from the remaining allocation. The unallocated reactive power is redistributed over the remaining regulators until all required reactive power has been allocated or all available regulators have reached a limit.For asymmetric calculations, limit checks use the total three-phase reactive power. The phase distribution follows the available phase proportions where possible; if no usable phase proportion is available, the value is distributed equally over the three phases.
Documentation updates
The documentation now describes:
node.bus_type;voltage_regulator.limit_violated;voltage_regulatorcomponents in Newton-Raphson power flow.Testing
Added and updated tests cover:
bus_type;limit_violated;Notes for reviewers
q_minandq_max.voltage_regulatoroutput only reports the limit status.Related to #1236toCloses #1236.