Voltage regulation refactoring

Migration guide: voltage regulation refactoring

Starting from powsybl-core 7.4.0, voltage regulation is no longer modeled with different equipment-specific attributes or with dedicated extensions. Equipment able to regulate voltage now directly or indirectly owns a com.powsybl.iidm.network.regulation.VoltageRegulation object through the VoltageRegulationHolder API.

This guide explains the new model and gives migration procedures and examples. The new model is also described in the powsybl-core documentation.

1. Model overview

1.1 Before the refactoring

Before the refactoring, voltage regulation data was spread across:

• direct attributes on network elements;
• equipment-specific regulation modes;
• tap-changer-specific attributes;
• IIDM extensions.

The model was inconsistent between equipment types.

Equipment / feature	Previous modeling
Generator	voltageRegulatorOn, targetV, targetQ, regulatingTerminal
Battery	targetQ and VoltageRegulation extension
StaticVarCompensator	regulationMode, voltageSetpoint, reactivePowerSetpoint, regulating, regulatingTerminal
VscConverterStation / VoltageSourceConverter	voltageRegulatorOn, voltageSetpoint, reactivePowerSetpoint, regulatingTerminal
ShuntCompensator	voltageRegulatorOn, targetV, targetDeadband, regulatingTerminal
RatioTapChanger	regulationMode, regulationValue, targetV, targetDeadband, regulating, regulationTerminal
Remote reactive power regulation	RemoteReactivePowerControl extension
Voltage per reactive power regulation	VoltagePerReactivePowerControl extension
Battery voltage regulation	VoltageRegulation extension

Conceptually, the previous model was:

Equipment:

• local regulation attributes:
  • targetV / voltageSetpoint
  • targetQ / reactivePowerSetpoint
  • voltageRegulatorOn / regulating
  • regulatingTerminal
• optional extensions:
  • VoltageRegulation
  • RemoteReactivePowerControl
  • VoltagePerReactivePowerControl

1.2 After the refactoring

After the refactoring, voltage regulation is represented by:

• a common VoltageRegulation object;
• a common RegulationMode enum;
• local target values stored on the regulated equipment;
• optional remote regulation data stored in VoltageRegulation.

The new model is:

VoltageRegulationHolder:

• localTargetV
• localTargetQ
• VoltageRegulation:
  • mode
  • regulating
  • terminal
  • targetValue
  • targetDeadband
  • slope

The VoltageRegulation object is optional.

The common API is available through:

com.powsybl.iidm.network.regulation.VoltageRegulation;
com.powsybl.iidm.network.regulation.VoltageRegulationHolder;
com.powsybl.iidm.network.regulation.VoltageRegulationHolderAdder;
com.powsybl.iidm.network.regulation.RegulationMode;

1.3 Equipment affected by the new model

The following equipment can directly or indirectly contain a VoltageRegulation object:

Equipment	How regulation is now modeled
Battery	Implements the common voltage regulation holder API
Generator	Implements the common voltage regulation holder API
StaticVarCompensator	Implements the common voltage regulation holder API
VscConverterStation	Implements the common voltage regulation holder API
ShuntCompensator	Implements the common voltage regulation holder API
RatioTapChanger	Uses the common VoltageRegulation model for tap-changer voltage/reactive regulation

In addition, RatioTapChanger objects may be contained in:

Parent equipment	Impact
TwoWindingsTransformer	Its RatioTapChanger, if present, uses VoltageRegulation
ThreeWindingsTransformer.Leg	Each leg ratio tap changer, if present, uses VoltageRegulation

PhaseTapChanger is not migrated to the new VoltageRegulation model. It keeps its own phase regulation API.

2. New VoltageRegulation attributes

The VoltageRegulation object contains the regulation state and the target used when regulation is explicitly associated with a terminal.

Attribute	Type	Variant-dependent	Meaning
mode	RegulationMode	Yes	Regulation mode
regulating	boolean	Yes	Whether regulation is enabled
terminal	Terminal	No	Regulated terminal. Can be local or remote
targetValue	double	Yes	Target value for the selected mode when a terminal is explicitly set
targetDeadband	double	Yes	Deadband, mainly for discrete regulation such as ratio tap changers and shunt compensators
slope	double	Yes	Slope for VOLTAGE_PER_REACTIVE_POWER

The common regulation modes are:

New mode	Meaning
RegulationMode.VOLTAGE	Voltage regulation
RegulationMode.REACTIVE_POWER	Reactive power regulation
RegulationMode.VOLTAGE_PER_REACTIVE_POWER	Voltage per reactive power regulation

The previous equipment-specific regulation mode enums have been replaced by this common enum.

Here is the table of the authorized modes by equipment:

Equipment	Voltage	Reactive Power	Voltage per reactive power
Battery	X	X (*)
Generator	X	X (*)
RatioTapChanger	X (*)	X (*)
ShuntCompensator	X
StaticVarCompensator	X	X	X
VscConverterStation / VoltageSourceConverter	X	X (*)

(*) The terminal is required

3. Local and remote regulation

3.1 Local regulation

For local regulation, no explicit VoltageRegulation.terminal is required.

The target is stored on the regulated equipment:

Mode	Local target attribute
RegulationMode.VOLTAGE	localTargetV
RegulationMode.VOLTAGE_PER_REACTIVE_POWER	localTargetV and slope
RegulationMode.REACTIVE_POWER	localTargetQ

Example:

generator.setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .build();

3.2 Remote regulation

For remote regulation, set an explicit terminal on VoltageRegulation.

The remote target is stored in VoltageRegulation.targetValue.

Example:

generator.setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(400.0)
        .build();

The local target may still be useful, for instance as an equivalent local target or fallback value.

3.3 Reading target values

Use the common helper methods on voltage-regulation holders:

Need	Method
Check whether regulation is enabled	isRegulating()
Check whether an equipment regulates in a mode	isRegulatingWithMode(RegulationMode)
Get the effective regulating terminal: the explicitly configured regulating terminal when one exists, otherwise the holder’s own local terminal	getRegulatingTerminal()
Returns whether a regulating terminal has been explicitly configured. This does not take the implicit local-terminal fallback into account, so it can return false even though getRegulatingTerminal() returns the local terminal	hasRegulatingTerminal()
Get the effective voltage target	getRegulatingTargetV()
Get the effective reactive power target	getRegulatingTargetQ()
Get local voltage target	getLocalTargetV()
Get local reactive power target	getLocalTargetQ()
Get the raw regulation object	getVoltageRegulation()

4. Removed and moved extensions

The former voltage-regulation extensions are no longer part of the active public extension model.

They have been moved to:

com.powsybl.iidm.network.extensions.removed

Moved extensions:

Previous extension	New status
VoltageRegulation	Moved to com.powsybl.iidm.network.extensions.removed.VoltageRegulationExtension
RemoteReactivePowerControl	Moved to com.powsybl.iidm.network.extensions.removed.RemoteReactivePowerControl
VoltagePerReactivePowerControl	Moved to com.powsybl.iidm.network.extensions.removed.VoltagePerReactivePowerControl

These classes exist for backward compatibility during serialization/deserialization. New application code must not create or rely on these extensions.

4.1 Removed extension implementation classes

The following implementation and adder classes are removed from the active extension API:

• VoltageRegulationImpl
• VoltageRegulationAdder
• VoltageRegulationAdderImpl
• VoltageRegulationAdderImplProvider
• RemoteReactivePowerControlImpl
• RemoteReactivePowerControlAdder
• RemoteReactivePowerControlAdderImpl
• RemoteReactivePowerControlAdderImplProvider
• VoltagePerReactivePowerControlImpl
• VoltagePerReactivePowerControlAdder
• VoltagePerReactivePowerControlAdderImpl
• VoltagePerReactivePowerControlAdderImplProvider
• AbstractVoltagePerReactivePowerControlTest

5. Serialization compatibility

IIDM serialization remains backward compatible.

5.1 Importing older IIDM files

When importing IIDM files using versions before the refactoring, old attributes and extensions are converted into the new VoltageRegulation object.

Examples:

Old data	Imported as
Battery VoltageRegulation extension	Battery.getVoltageRegulation()
Generator RemoteReactivePowerControl extension	Generator.getVoltageRegulation() with RegulationMode.REACTIVE_POWER
SVC VoltagePerReactivePowerControl extension	StaticVarCompensator.getVoltageRegulation() with RegulationMode.VOLTAGE_PER_REACTIVE_POWER
voltageRegulatorOn / voltageSetpoint / reactivePowerSetpoint	VoltageRegulation plus localTargetV / localTargetQ

5.2 Exporting to older IIDM versions

When exporting to older IIDM versions, the new model is converted back when possible:

New model	Exported as in older versions
Battery voltage regulation	Former battery VoltageRegulation extension
Generator remote reactive power regulation	RemoteReactivePowerControl extension
SVC voltage per reactive power regulation	VoltagePerReactivePowerControl extension
VSC voltage regulation attributes	Former VSC attributes and regulating terminal representation

6. Migration procedure

Step 1: Replace imports

Replace equipment-specific regulation mode imports with the common enum.

Before:

import com.powsybl.iidm.network.StaticVarCompensator;

After:

import com.powsybl.iidm.network.regulation.RegulationMode;

Then replace:

StaticVarCompensator.RegulationMode.VOLTAGE

with:

RegulationMode.VOLTAGE

Step 2: Replace old regulation flags

Replace old boolean regulation flags with VoltageRegulation.isRegulating() or holder helper methods.

Before	After
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	getVoltageRegulation().setRegulating(boolean) or newVoltageRegulation().withRegulating(boolean)
isRegulating() on older equipment-specific APIs	isRegulating() from VoltageRegulationHolder

Step 3: Replace old target getters and setters

Use local targets for local regulation, and VoltageRegulation.targetValue for explicit-terminal regulation.

Previous concept	New concept
Local voltage setpoint	setLocalTargetV(double) / getLocalTargetV()
Local reactive power setpoint	setLocalTargetQ(double) / getLocalTargetQ()
Remote voltage target	getVoltageRegulation().setTargetValue(double)
Remote reactive power target	getVoltageRegulation().setTargetValue(double)
Generic effective voltage target	getRegulatingTargetV()
Generic effective reactive power target	getRegulatingTargetQ()

Step 4: Replace old regulating terminal API

Before	After
getRegulatingTerminal()	getRegulatingTerminal() still available as common helper
setRegulatingTerminal(Terminal)	getVoltageRegulation().setTerminal(terminal, targetValue) or builder .withTerminal(terminal).withTargetValue(value)
getRegulationTerminal() on RatioTapChanger	getVoltageRegulation().getTerminal() or getRegulatingTerminal()
setRegulationTerminal(Terminal) on RatioTapChanger	newVoltageRegulation().withTerminal(terminal)

Step 5: Create regulation with the new API

For an existing object:

equipment.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE)
    .withRegulating(true)
    .build();

For an equipment adder:

voltageLevel.newGenerator()
    .setId("GEN")
    .setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .add()
    .add();

Use:

• .build() when configuring regulation on an existing equipment;
• .add() when configuring regulation through an equipment adder.

7. Generic migration patterns

7.1 Local voltage regulation

Before:

generator.setTargetV(225.0)
    .setVoltageRegulatorOn(true);

After:

generator.setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .build();

7.2 Remote voltage regulation

Before:

generator.setTargetV(400.0, 225.0)
    .setRegulatingTerminal(remoteTerminal)
    .setVoltageRegulatorOn(true);

After:

generator.setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(400.0)
        .build();

7.3 Local reactive power regulation

Before:

svc.setReactivePowerSetpoint(50.0)
    .setRegulationMode(StaticVarCompensator.RegulationMode.REACTIVE_POWER)
    .setRegulating(true);

After:

svc.setLocalTargetQ(50.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.REACTIVE_POWER)
        .withRegulating(true)
        .build();

7.4 Remote reactive power regulation

Before (generators):

generator.newExtension(RemoteReactivePowerControlAdder.class)
    .withTargetQ(-100.0)
    .withRegulatingTerminal(remoteTerminal)
    .withEnabled(true)
    .add();

After:

generator.setLocalTargetQ(25.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.REACTIVE_POWER)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(-100.0)
        .build();

7.5 Voltage per reactive power regulation (Static var compensator)

Before:

svc.newExtension(VoltagePerReactivePowerControlAdder.class)
    .withSlope(0.3)
    .add();

After:

svc.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE_PER_REACTIVE_POWER)
    .withRegulating(true)
    .withSlope(0.3)
    .build();

8. Equipment-specific migration

8.1 Battery

Model changes

Before	After
targetQ	localTargetQ
Battery VoltageRegulation extension	Battery.getVoltageRegulation()
Extension voltageRegulatorOn	VoltageRegulation.isRegulating()
Extension targetV	localTargetV for local regulation, targetValue for explicit-terminal regulation
Extension regulatingTerminal	VoltageRegulation.terminal

API mapping

Deprecated / removed API	New API
Battery.getTargetQ()	Battery.getRegulatingTargetQ() or getLocalTargetQ()
Battery.setTargetQ(double)	Battery.setLocalTargetQ(double)
BatteryAdder.setTargetQ(double)	BatteryAdder.setLocalTargetQ(double)
VoltageRegulationExtension.isVoltageRegulatorOn()	Battery.isRegulating() or VoltageRegulation.isRegulating()
VoltageRegulationExtension.setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
VoltageRegulationExtension.getTargetV()	Battery.getRegulatingTargetV()
VoltageRegulationExtension.setTargetV(double)	Battery.setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
VoltageRegulationExtension.getRegulatingTerminal()	Battery.getRegulatingTerminal()
VoltageRegulationExtension.setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Creating a battery before

Battery battery = voltageLevel.newBattery()
    .setId("BAT")
    .setBus("B1")
    .setConnectableBus("B1")
    .setTargetP(10.0)
    .setTargetQ(5.0)
    .setMinP(-20.0)
    .setMaxP(20.0)
    .add();

battery.newExtension(VoltageRegulationAdder.class)
    .withVoltageRegulatorOn(true)
    .withTargetV(225.0)
    .add();

Creating a battery after

Battery battery = voltageLevel.newBattery()
    .setId("BAT")
    .setBus("B1")
    .setConnectableBus("B1")
    .setTargetP(10.0)
    .setLocalTargetQ(5.0)
    .setLocalTargetV(225.0)
    .setMinP(-20.0)
    .setMaxP(20.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .add()
    .add();

Remote voltage regulation after

Battery battery = voltageLevel.newBattery()
    .setId("BAT")
    .setBus("B1")
    .setConnectableBus("B1")
    .setTargetP(10.0)
    .setLocalTargetQ(5.0)
    .setLocalTargetV(225.0)
    .setMinP(-20.0)
    .setMaxP(20.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(400.0)
        .add()
    .add();

8.2 Generator

Model changes

Before	After
voltageRegulatorOn	VoltageRegulation.regulating
targetV	localTargetV or VoltageRegulation.targetValue
targetQ	localTargetQ or VoltageRegulation.targetValue in REACTIVE_POWER mode
regulatingTerminal	VoltageRegulation.terminal
RemoteReactivePowerControl extension	VoltageRegulation with RegulationMode.REACTIVE_POWER

API mapping

Deprecated API	New API
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	setLocalTargetV(double) for local regulation
setTargetV(double, double)	VoltageRegulation.setTargetValue(double) and setLocalTargetV(double)
getTargetQ()	getRegulatingTargetQ()
setTargetQ(double)	setLocalTargetQ(double)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Creating a generator before

Generator generator = voltageLevel.newGenerator()
    .setId("GEN")
    .setBus("B1")
    .setConnectableBus("B1")
    .setEnergySource(EnergySource.THERMAL)
    .setMinP(0.0)
    .setMaxP(100.0)
    .setTargetP(80.0)
    .setTargetQ(10.0)
    .setTargetV(225.0)
    .setVoltageRegulatorOn(true)
    .add();

Creating a generator after

Generator generator = voltageLevel.newGenerator()
    .setId("GEN")
    .setBus("B1")
    .setConnectableBus("B1")
    .setEnergySource(EnergySource.THERMAL)
    .setMinP(0.0)
    .setMaxP(100.0)
    .setTargetP(80.0)
    .setLocalTargetQ(10.0)
    .setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .add()
    .add();

Remote reactive power regulation after

generator.setLocalTargetQ(10.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.REACTIVE_POWER)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(-100.0)
        .build();

8.3 StaticVarCompensator

Model changes

Before	After
StaticVarCompensator.RegulationMode	RegulationMode
voltageSetpoint	localTargetV or VoltageRegulation.targetValue
reactivePowerSetpoint	localTargetQ or VoltageRegulation.targetValue
regulating	VoltageRegulation.regulating
regulatingTerminal	VoltageRegulation.terminal
VoltagePerReactivePowerControl extension	VoltageRegulation with RegulationMode.VOLTAGE_PER_REACTIVE_POWER

API mapping

Deprecated API	New API
getVoltageSetpoint()	getRegulatingTargetV()
setVoltageSetpoint(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getReactivePowerSetpoint()	getRegulatingTargetQ()
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or VoltageRegulation.setTargetValue(double)
getRegulationMode()	VoltageRegulation.getMode()
setRegulationMode(RegulationMode)	VoltageRegulation.setMode(RegulationMode)
setRegulating(boolean)	VoltageRegulation.setRegulating(boolean)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Creating an SVC before

StaticVarCompensator svc = voltageLevel.newStaticVarCompensator()
    .setId("SVC")
    .setBus("B1")
    .setConnectableBus("B1")
    .setBmin(-0.01)
    .setBmax(0.01)
    .setVoltageSetpoint(225.0)
    .setReactivePowerSetpoint(20.0)
    .setRegulationMode(StaticVarCompensator.RegulationMode.VOLTAGE)
    .setRegulating(true)
    .add();

Creating an SVC after

StaticVarCompensator svc = voltageLevel.newStaticVarCompensator()
    .setId("SVC")
    .setBus("B1")
    .setConnectableBus("B1")
    .setBmin(-0.01)
    .setBmax(0.01)
    .setLocalTargetV(225.0)
    .setLocalTargetQ(20.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .add()
    .add();

Voltage per reactive power regulation after

svc.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE_PER_REACTIVE_POWER)
    .withRegulating(true)
    .withSlope(0.3)
    .build();

8.4 VscConverterStation

Model changes

Before	After
voltageRegulatorOn	VoltageRegulation.regulating
voltageSetpoint	localTargetV or VoltageRegulation.targetValue
reactivePowerSetpoint	localTargetQ or VoltageRegulation.targetValue
regulatingTerminal	VoltageRegulation.terminal

API mapping

Deprecated API	New API
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
getVoltageSetpoint()	getRegulatingTargetV()
setVoltageSetpoint(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getReactivePowerSetpoint()	getRegulatingTargetQ()
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or VoltageRegulation.setTargetValue(double)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Creating a VSC converter station before

VscConverterStation vsc = voltageLevel.newVscConverterStation()
    .setId("VSC")
    .setBus("B1")
    .setConnectableBus("B1")
    .setLossFactor(1.0f)
    .setVoltageSetpoint(225.0)
    .setReactivePowerSetpoint(20.0)
    .setVoltageRegulatorOn(true)
    .add();

Creating a VSC converter station after

VscConverterStation vsc = voltageLevel.newVscConverterStation()
    .setId("VSC")
    .setBus("B1")
    .setConnectableBus("B1")
    .setLossFactor(1.0f)
    .setLocalTargetV(225.0)
    .setLocalTargetQ(20.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .add()
    .add();

Remote voltage regulation after

vsc.setLocalTargetQ(20.0)
    .setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .withTerminal(remoteTerminal)
        .withTargetValue(400.0)
        .build();

8.5 ShuntCompensator

Model changes

Before	After
voltageRegulatorOn	VoltageRegulation.regulating
targetV	localTargetV or VoltageRegulation.targetValue
targetDeadband	VoltageRegulation.targetDeadband
regulatingTerminal	VoltageRegulation.terminal

API mapping

Deprecated API	New API
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getTargetDeadband()	VoltageRegulation.getTargetDeadband()
setTargetDeadband(double)	VoltageRegulation.setTargetDeadband(double)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Local voltage regulation after

shuntCompensator.setLocalTargetV(225.0)
    .newVoltageRegulation()
        .withMode(RegulationMode.VOLTAGE)
        .withRegulating(true)
        .withTargetDeadband(0.1)
        .build();

Remote voltage regulation after

shuntCompensator.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE)
    .withRegulating(true)
    .withTerminal(remoteTerminal)
    .withTargetValue(400.0)
    .withTargetDeadband(0.1)
    .build();

8.6 RatioTapChanger

Model changes

Before	After
RatioTapChanger.RegulationMode	RegulationMode
regulationMode	VoltageRegulation.mode
regulationValue	VoltageRegulation.targetValue
targetV	VoltageRegulation.targetValue with RegulationMode.VOLTAGE
targetDeadband	VoltageRegulation.targetDeadband
regulating	VoltageRegulation.regulating
regulationTerminal	VoltageRegulation.terminal

API mapping

Deprecated API	New API
getRegulationMode()	VoltageRegulation.getMode()
setRegulationMode(RegulationMode)	VoltageRegulation.setMode(RegulationMode)
getRegulationValue()	VoltageRegulation.getTargetValue()
setRegulationValue(double)	VoltageRegulation.setTargetValue(double)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	VoltageRegulation.setTargetValue(double)
getTargetDeadband()	VoltageRegulation.getTargetDeadband()
setTargetDeadband(double)	VoltageRegulation.setTargetDeadband(double)
setRegulating(boolean)	VoltageRegulation.setRegulating(boolean)
getRegulationTerminal()	VoltageRegulation.getTerminal() or getRegulatingTerminal()
setRegulationTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

Ratio tap changer voltage regulation before

ratioTapChanger.setTargetV(225.0)
    .setRegulating(true)
    .setRegulationTerminal(regulationTerminal)
    .setTargetDeadband(0.1);

Ratio tap changer voltage regulation after

ratioTapChanger.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE)
    .withRegulating(true)
    .withTerminal(regulationTerminal)
    .withTargetValue(225.0)
    .withTargetDeadband(0.1)
    .build();

Ratio tap changer reactive power regulation after

ratioTapChanger.newVoltageRegulation()
    .withMode(RegulationMode.REACTIVE_POWER)
    .withRegulating(true)
    .withTerminal(regulationTerminal)
    .withTargetValue(50.0)
    .withTargetDeadband(0.1)
    .build();

9. Validation changes

Voltage regulation validation is now centralized.

Important validation rules include:

Rule	Consequence
If regulating is true, mode must be defined	Otherwise the network is invalid
If a remote or explicit terminal is used, targetValue must be defined	Otherwise the network is invalid
If no terminal is set for local voltage or local reactive regulation, targetValue is expected to be NaN	Use localTargetV or localTargetQ instead
targetDeadband must be defined for regulating ShuntCompensator and RatioTapChanger	Otherwise the network is invalid
targetDeadband must not be negative	Otherwise the network is invalid
slope must be defined for VOLTAGE_PER_REACTIVE_POWER when regulating	Otherwise the network is invalid
VoltageRegulation.terminal must belong to the same network	Otherwise the network is invalid
A regulating RatioTapChanger must have a regulation terminal	Otherwise the network is invalid
A regulating RatioTapChanger must have load tap changing capabilities	Otherwise the network is invalid

10. Load-flow validation output

The verbose generator load-flow validation result format has changed.

Previous column	New columns
voltageRegulatorOn	regulationMode, regulating
voltageRegulatorOn_postComp	regulationMode_postComp, regulating_postComp

Update parsers and tests that read verbose load-flow validation files.

11. Moved utility class

VoltageRegulationUtils has moved.

Before	After
com.powsybl.iidm.modification.util.VoltageRegulationUtils	com.powsybl.iidm.network.util.VoltageRegulationUtils

12. TapChanger breaking changes

The following methods have been removed from the generic TapChanger interface:

• setRegulating(boolean)
• getRegulationTerminal()
• setRegulationTerminal(Terminal)

They are now specific to the appropriate tap changer APIs:

• PhaseTapChanger keeps its own phase regulation API;
• RatioTapChanger uses the new VoltageRegulation model, with deprecated compatibility methods where available.

13. Generator modification API

Generator modifications now distinguish the regulation mode from the regulation status.

Deprecated attribute / method	Replacement
Boolean voltageRegulatorOn	RegulationMode voltageRegulationMode and Boolean regulating
getVoltageRegulatorOn()	VoltageRegulation.isRegulating()
setVoltageRegulatorOn(boolean)	Set regulating and, if needed, voltageRegulationMode

Example:

generator.newVoltageRegulation()
    .withMode(RegulationMode.VOLTAGE)
    .withRegulating(true)
    .build();

14. Deprecated methods summary

Battery

Deprecated method	New method
getTargetQ()	getRegulatingTargetQ() or getLocalTargetQ()
setTargetQ(double)	setLocalTargetQ(double)

BatteryAdder

Deprecated method	New method
setTargetQ(double)	setLocalTargetQ(double)

Generator

Deprecated method	New method
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
setTargetV(double, double)	setLocalTargetV(double) and VoltageRegulation.setTargetValue(double)
getEquivalentLocalTargetV()	getLocalTargetV()
getTargetQ()	getRegulatingTargetQ()
setTargetQ(double)	setLocalTargetQ(double)

GeneratorAdder

Deprecated method	New method
setVoltageRegulatorOn(boolean)	newVoltageRegulation().withRegulating(boolean)
setRegulatingTerminal(Terminal)	newVoltageRegulation().withTerminal(Terminal)
setTargetV(double)	setLocalTargetV(double) or newVoltageRegulation().withTargetValue(double)
setTargetV(double, double)	setLocalTargetV(double) and newVoltageRegulation().withTargetValue(double)
setTargetQ(double)	setLocalTargetQ(double)

StaticVarCompensator

Deprecated method	New method
getVoltageSetpoint()	getRegulatingTargetV()
setVoltageSetpoint(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getReactivePowerSetpoint()	getRegulatingTargetQ()
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or VoltageRegulation.setTargetValue(double)
getRegulationMode()	VoltageRegulation.getMode()
setRegulationMode(RegulationMode)	VoltageRegulation.setMode(RegulationMode)
setRegulating(boolean)	VoltageRegulation.setRegulating(boolean)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

StaticVarCompensatorAdder

Deprecated method	New method
setVoltageSetpoint(double)	setLocalTargetV(double) or newVoltageRegulation().withTargetValue(double)
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or newVoltageRegulation().withTargetValue(double)
setRegulationMode(RegulationMode)	newVoltageRegulation().withMode(RegulationMode)
setRegulating(boolean)	newVoltageRegulation().withRegulating(boolean)
setRegulatingTerminal(Terminal)	newVoltageRegulation().withTerminal(Terminal)

VscConverterStation

Deprecated method	New method
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
getVoltageSetpoint()	getRegulatingTargetV()
setVoltageSetpoint(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getReactivePowerSetpoint()	getRegulatingTargetQ()
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or VoltageRegulation.setTargetValue(double)
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

VscConverterStationAdder

Deprecated method	New method
setVoltageRegulatorOn(boolean)	newVoltageRegulation().withRegulating(boolean)
setVoltageSetpoint(double)	setLocalTargetV(double) or newVoltageRegulation().withTargetValue(double)
setReactivePowerSetpoint(double)	setLocalTargetQ(double) or newVoltageRegulation().withTargetValue(double)
setRegulatingTerminal(Terminal)	newVoltageRegulation().withTerminal(Terminal)

ShuntCompensator

Deprecated method	New method
setRegulatingTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)
isVoltageRegulatorOn()	isRegulating()
setVoltageRegulatorOn(boolean)	VoltageRegulation.setRegulating(boolean)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	setLocalTargetV(double) or VoltageRegulation.setTargetValue(double)
getTargetDeadband()	VoltageRegulation.getTargetDeadband()
setTargetDeadband(double)	VoltageRegulation.setTargetDeadband(double)

ShuntCompensatorAdder

Deprecated method	New method
setRegulatingTerminal(Terminal)	newVoltageRegulation().withTerminal(Terminal)
setVoltageRegulatorOn(boolean)	newVoltageRegulation().withRegulating(boolean)
setTargetV(double)	setLocalTargetV(double) or newVoltageRegulation().withTargetValue(double)
setTargetDeadband(double)	newVoltageRegulation().withTargetDeadband(double)

RatioTapChanger

Deprecated method	New method
getRegulationMode()	VoltageRegulation.getMode()
setRegulationMode(RegulationMode)	VoltageRegulation.setMode(RegulationMode)
getRegulationValue()	VoltageRegulation.getTargetValue()
setRegulationValue(double)	VoltageRegulation.setTargetValue(double)
getTargetV()	getRegulatingTargetV()
setTargetV(double)	VoltageRegulation.setTargetValue(double)
getTargetDeadband()	VoltageRegulation.getTargetDeadband()
setTargetDeadband(double)	VoltageRegulation.setTargetDeadband(double)
setRegulating(boolean)	VoltageRegulation.setRegulating(boolean)
getRegulationTerminal()	VoltageRegulation.getTerminal() or getRegulatingTerminal()
setRegulationTerminal(Terminal)	VoltageRegulation.setTerminal(Terminal, double)

RatioTapChangerAdder

Deprecated method	New method
setRegulationMode(RegulationMode)	newVoltageRegulation().withMode(RegulationMode)
setRegulationValue(double)	newVoltageRegulation().withTargetValue(double)
setTargetV(double)	newVoltageRegulation().withMode(RegulationMode.VOLTAGE).withTargetValue(double)
setRegulating(boolean)	newVoltageRegulation().withRegulating(boolean)
setRegulationTerminal(Terminal)	newVoltageRegulation().withTerminal(Terminal)
setTargetDeadband(double)	newVoltageRegulation().withTargetDeadband(double)

15. Migration checklist

Use the following checklist when migrating an application:

1. Replace equipment-specific regulation mode enums with com.powsybl.iidm.network.regulation.RegulationMode.
2. Replace old regulation extensions with newVoltageRegulation().
3. Replace targetV / voltageSetpoint with:
   • localTargetV for local voltage targets;
   • VoltageRegulation.targetValue for explicit-terminal voltage targets.
4. Replace targetQ / reactivePowerSetpoint with:
   • localTargetQ for local reactive power targets;
   • VoltageRegulation.targetValue for explicit-terminal reactive power targets.
5. Replace voltageRegulatorOn with VoltageRegulation.regulating.
6. Replace regulatingTerminal / regulationTerminal setters with VoltageRegulation.terminal.
7. For ShuntCompensator and RatioTapChanger, move targetDeadband to VoltageRegulation.targetDeadband.
8. For voltage-per-reactive-power regulation, set:
   • mode = RegulationMode.VOLTAGE_PER_REACTIVE_POWER;
   • slope;
   • regulating = true.
9. Update imports of VoltageRegulationUtils.
10. Update load-flow validation result parsers if they read verbose generator validation files.