Module taps 

Transformer tap control: the on-load tap changer as a control rather than a constant.

Every steady-state result gridoxide produced before this module existed was computed with taps that never move, which is a modelling assumption four of the five tools in docs/src/reference/feature_comparison.md do not make. A real tap changer holds a voltage or a flow, and its position is an output of the solve.

The strategy, and why this one

powsybl-open-loadflow offers three for voltage control. Two put the continuous ratio inside the Newton system and round afterwards; the third — IncrementalTransformerVoltageControlOuterLoop — steps the discrete position directly, using the sensitivity of the controlled voltage to the ratio:

\[ \Delta\rho = \frac{V^{\text{target}} - V_c}{\partial V_c/\partial\rho} \]

The incremental one is implemented here, for a reason specific to this crate: that derivative is already crate::ac_sensitivity::AcSensitivity with Variable::TransformerRatio against Function::VoltageMagnitude, validated against a central-difference re-solve of the full nonlinear power flow. The continuous variants would need the ratio inside crate::jacobian::JacobianPattern and a different n_unknowns.

Three guards, all load-bearing

• Deadband. Every enabled control in the CGMES conformity fixtures carries one. A loop that ignores it hunts, and a loop that hunts does not terminate.
• Insensitivity filter (MIN_SENSITIVITY). Below it the controller cannot reach its bus, and \(\Delta\rho\) is a division by nearly zero that slams the tap to a limit.
• Direction-change budget (MAX_DIRECTION_CHANGES). A tap that has reversed this many times is oscillating between two positions that straddle the target with none inside the deadband. That is a property of the network and the deadband, not a solver failure, and the honest answer is to stop and report ControllerOutcome::Hunting.

Structs

ControllerReport

One controller’s history through a solve.

PhaseControl

A phase-shifting transformer holding the active power on a monitored branch.

TapControlReport

What a tap-control loop did.

TapRegulation

One regulating control, resolved against gridoxide’s own indices.

TransformerVoltageControl

A ratio tap changer holding the voltage magnitude at its controlled bus.

Enums

ControllerOutcome

How one controller finished.

RegulationMode

What a tap changer’s regulating control holds.

Constants

MAX_DIRECTION_CHANGES

How many times a controller may reverse direction before it is declared to be hunting. powsybl’s own MAX_DIRECTION_CHANGE.

MIN_SENSITIVITY

Below this, a controller is treated as unable to reach its controlled quantity. powsybl’s own MIN_SENSI_FILTER.