Describe the current behavior

Many IIDM objects are able to regulate voltage, either directly or through the control of reactive power. However, the modeling of the voltage regulation varies greatly from one class to another.

Describe the expected behavior

The voltage regulation modeling should be homogeneous for all objects capable of such regulation:

• Battery
• Generator
• RatioTapChanger
• ShuntCompensator
• StaticVarCompensator
• VscConverterStation
• VoltageSourceConverter

These voltage control capable classes should refer a new object of type (to be created): VoltageRegulation with the following attributes:

• double targetValue
• double targetDeadband
• double slope
• Terminal terminal
• RegulationMode mode
• boolean regulating

Notes:

• Unlike in CGMES, the VoltageRegulation object isn't shared: each IIDM object capable of voltage regulation shall have its own.
• The terminal corresponds to the old regulatingTerminal attribute, the reason for the renaming is that the word regulation is already bear by the class name VoltageRegulation.
• RegulationMode is an enum describing the kinds of regulation. It has the following values:
  • VOLTAGE
  • REACTIVE_POWER
  • VOLTAGE_PER_REACTIVE_POWER
  • REACTIVE_POWER_PER_ACTIVE_POWER
• The slope attribute is relevant for:
  • VOLTAGE_PER_REACTIVE_POWER: it corresponds to the lambda in U0 = U + lambda*Q
  • REACTIVE_POWER_PER_ACTIVE_POWER: it corresponds to the tan(phi) in Q = tan(phi)*P
• The targetDeadband is only pertinent for objects with discrete (as opposed to continuous) voltage regulation, which is the case for RatioTapChanger and ShuntCompensator.
• terminal is optional. If not set, the local terminal of the connectable should be used.
• targetValue, mode and regulating are always required.

Controls must be performed in adders, setters and in the global network validation (method validate of ValidationUtil class) to ensure that:

• The regulation mode is authorized for this class:

• slope attribute is defined when the regulation mode is VOLTAGE_PER_REACTIVE_POWER or REACTIVE_POWER_PER_ACTIVE_POWER.
• targetDeadband is defined for RatioTapChanger and ShuntCompensator.
• In the case of reactive power regulation, the regulated terminal should be the terminal of a branch or 3-winding transformer leg.

To minimize the breaking changes:

• In the IIDM objects interfaces, the legacy methods (get/setRegulatingTerminal, get/setTargetV...) should be kept but marked deprecated.
• In the IIDM objects implementations, the legacy methods should call the ones of VoltageRegulation. For instance, GeneratorImpl.getRegulatingTerminal() should call GeneratorImpl.getVoltageRegulation().getTerminal().

Describe the motivation

• All objects capable of regulating voltage have a similar way to describe this regulation.

Extra Information

Here are the elements that will be part of this refactoring:

• The interfaces and implementations of voltage regulation capable connectables
• VoltageRegulation extension of Battery
• RemoteReactivePowerControl extension of Generator
• VoltagePerReactivePowerControl extension of StaticVarCompensator

Here are the elements that won't be part of this refactoring:

• CoordinatedReactiveControl extension of Generator that is too specific (only applies for Generator)
• Other regulation types than voltage/reactive power. For instance, active power regulation of Generator, phase tap changer regulation, dc voltage or active power regulation of voltage source converters.
• A targetQ should remain on injections. It is used to represent the reactive power injection in case the voltage regulation is deactivated, or as starting value for a dynamic simulator.
• A targetV should remain on Generator and on Battery as local back-up value in case the simulator deems the one in VoltageRegulation inappropriate. This local backup targetV must be set together and in accordance with the one in VoltageRegulation.