Support voltage-regulator Q limits and PV→PQ switching by scud-soptim · Pull Request #1452 · PowerGridModel/power-grid-model

scud-soptim · 2026-06-25T09:08:55Z

Implements #1236

Summary

This PR adds reactive-power limit handling for voltage-regulated nodes in Newton-Raphson power-flow calculations.

An active voltage_regulator now models the regulated node as a PV node by enforcing the configured voltage magnitude u_ref. If the reactive power required to maintain this voltage violates q_min or q_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_type to steady-state node output.
- 0: PQ
- 1: PV
- 2: Source/Slack
Extend voltage-regulator steady-state output with a limit indicator.
- -1: lower reactive-power limit q_min reached
- 0: no limit violation
- 1: upper reactive-power limit q_max reached
Implement 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_min or q_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:

voltage-regulator PV-node behavior;
PV→PQ switching on reactive-power limit violation;
the meaning of node.bus_type;
the meaning of voltage_regulator.limit_violated;
reactive-power allocation for multiple voltage regulators at the same node;
the fact that voltage-controlled buses are supported through active voltage_regulator components in Newton-Raphson power flow.

Testing

Added and updated tests cover:

node output metadata for bus_type;
voltage-regulator output metadata for limit_violated;
Newton-Raphson PV-node handling;
PV→PQ switching on lower and upper Q-limit violations;
multiple voltage regulators at the same node;
batch calculation scenarios with voltage-regulator updates;
reference power-flow test data for the new PV→PQ switching case.

Notes for reviewers

The implementation is limited to Newton-Raphson power flow.
This PR does not change the public input model beyond the voltage-regulator Q-limit behavior already represented by q_min and q_max.
The reactive-power value is reported on the regulated load/generator output. The voltage_regulator output only reports the limit status.
If this PR fully resolves issue [FEATURE] Q limit handling for PV nodes #1236, the PR description can be changed from Related to #1236 to Closes #1236.

- 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: SCUD-SOPTIM <udo.schmitz@soptim.de>

Signed-off-by: Eduard Fried <eduard.fried@soptim.de>

figueroa1395 · 2026-06-26T10:22:07Z

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:

We will start now the reviewing progress, but it will take us some time. Please be patient.
We'll address any question/comment presented during the review process itself.
As usual, feel free to ping us at any point in time if there is any urgency or you need help.

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

@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 :)

figueroa1395 · 2026-07-01T09:50:02Z

- 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


Maybe add a hyperlink for voltage_regulator here.

figueroa1395 · 2026-07-01T09:56:20Z

+        },
+        {
+          "data_type": "IntS",
+          "names": ["bus_type"],
+          "description": "effective bus type after calculation"


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.

figueroa1395 · 2026-07-01T09:58:43Z

+```
+
+```{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.


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.

figueroa1395 · 2026-07-01T09:59:44Z

+Voltage regulation is supported only by the [Newton-Raphson power flow](./calculations.md#newton-raphson-power-flow)
+method.


Can you leave this as a warning or note please?

figueroa1395 · 2026-07-01T11:35:47Z

        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()) {


Isn't this always true?

figueroa1395 · 2026-07-01T14:48:17Z

+    }
+
+    // apply distributed Q to load_gens
+    for (auto const& [idx, load_gen] : enumerate(load_gens)) {


I think regulating_gens already contains the relevant load_gens. That would also remove the need for the status check below.

figueroa1395 · 2026-07-01T14:50:11Z

+    for (auto const& [idx, load_gen] : enumerate(load_gens)) {
+        if (!loadgen_to_regulator.contains(load_gen)) {
+            continue;
+        }


You can also pass as argument to this function the list of relevant ones.

figueroa1395 · 2026-07-01T15:00:37Z

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


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.

figueroa1395 · 2026-07-01T15:02:43Z

+
+    // auto num_regulating_gens = static_cast<double>(std::ranges::distance(regulating_gens)); // <- fails in windows
+    // build
    double num_regulating_gens = 0.0;


I just realized, why is this a double?

figueroa1395 · 2026-07-01T15:09:29Z

+    // 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) {


Could this get into an infinite loop?

figueroa1395

Some additional comments

figueroa1395 · 2026-07-02T06:31:53Z

+        // keep copy, as reference might break batching
        auto derived_solver = static_cast<DerivedSolver&>(*this);


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.

figueroa1395 · 2026-07-02T08:09:34Z

+        // finalize
+        {
+            // Timer const sub_timer{log, LogEvent::calculate_math_result}; // TODO(mgovers): need new event ?!?
+            derived_solver.finalize_derived_result(input, output);
+        }
+


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.

figueroa1395 · 2026-07-02T08:17:34Z


    void parameters_changed(bool changed) { parameters_changed_ = parameters_changed_ || changed; }

+    void finalize_derived_result(PowerFlowInput<sym> const& /*input*/, SolverOutput<sym>& /*output*/) {


See https://github.com/PowerGridModel/power-grid-model/pull/1452/changes#r3511454470

figueroa1395 · 2026-07-02T08:18:33Z

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


Let's make this use a named variable or enum please.

figueroa1395 · 2026-07-02T08:33:55Z

Very nice cleanup :)

figueroa1395 · 2026-07-02T16:19:19Z

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.

frie-soptim and others added 5 commits June 25, 2026 09:53

Add unit tests

fb57e14

Signed-off-by: Eduard Fried <eduard.fried@soptim.de>

Add validation tests

bf71775

Signed-off-by: Eduard Fried <eduard.fried@soptim.de>

add documentation

8d272c1

Signed-off-by: SCUD-SOPTIM <udo.schmitz@soptim.de>

Fix test for conda build

4d6fc8e

Signed-off-by: Eduard Fried <eduard.fried@soptim.de>

figueroa1395 assigned scud-soptim Jun 26, 2026

figueroa1395 added documentation Improvements or additions to documentation feature New feature or request improvement Improvement on internal implementation labels Jun 26, 2026

figueroa1395 mentioned this pull request Jun 26, 2026

[FEATURE] Q limit handling for PV nodes #1236

Open

figueroa1395 reviewed Jul 1, 2026

View reviewed changes

figueroa1395 reviewed Jul 2, 2026

View reviewed changes

		Voltage regulation is supported only by the [Newton-Raphson power flow](./calculations.md#newton-raphson-power-flow)
		method.

		// keep copy, as reference might break batching
		auto derived_solver = static_cast<DerivedSolver&>(*this);


		void parameters_changed(bool changed) { parameters_changed_ = parameters_changed_ \|\| changed; }

		void finalize_derived_result(PowerFlowInput<sym> const& /input/, SolverOutput<sym>& /output/) {

Uh oh!

Conversation

scud-soptim commented Jun 25, 2026

Summary

Main changes

Reactive-power allocation with multiple voltage regulators

Documentation updates

Testing

Notes for reviewers

Uh oh!

figueroa1395 commented Jun 26, 2026

Uh oh!

figueroa1395 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

figueroa1395 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants