Grid model extensions

The grid model contains enough data to basically describe supported components and run power flow computations, but it may not be sufficient for more complex studies. The extensions are a way to add additional structured data to an equipment to extend its features. The extensions can be attached to any objects of a network or to the network itself.

Some extensions are mono-variant meaning the data are identical for all the variants of the network. However, some of them are multi-variants to allow a different value for each variant of the network. It’s typically the case for the LoadDetail extension that give the distribution of the constant part and the thermo-sensitive part of a consumption.

Note that some extensions provided by PowSyBl aren’t supported in the persistent implementation of IIDM.

Every extension is considered as serializable unless explicitly specified as non-serializable in XML-IIDM.

• Active power control
• Branch observability
• Branch status
• Bus bar section position
• Connectable position
• Coordinated reactive control
• Discrete measurements
• ENTSO-E area
• HVDC angle droop active power control
• HVDC operator active power range
• Generator ENTSO-E category
• Generator short-circuit
• Identifiable short-circuit
• Injection observability
• Load asymmetrical
• Load detail
• Measurements
• Remote reactive power control
• Slack terminal
• Three-windings transformer phase angle clock
• Three-windings transformer to be estimated
• Two-windings transformer phase angle clock
• Two-windings transformer to be estimated
• Voltage per reactive power control
• Reference Priority
• Reference Terminals

Active power control

This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with balance type on generator). This extension is attached to a generator or a battery.

Here is how to add an active power control extension to a generator:

generator.newExtension(ActivePowerControlAdder.class)
    .withParticipate(true)
    .withDroop(4)
    .withParticipationFactor(1.5)
    .add();

The participation status and the participation factor are multi-variants: they can vary from one variant to another.

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Branch observability

This extension models branches’ flows’ observability on both sides, obtained after a state estimation.

Observability quality

This extension contains the sub-object ObservabilityQuality.

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Branch status

This extension models the status of a connectable. The status could be IN_OPERATION, PLANNED_OUTAGE or FORCED_OUTAGE.

Bus bar section position

This extension gives positions information about a bus bar section. The busBarIndex gives the position of the bus bar section relatively to other bus bars. The sectionIndex gives the position of the bus bar section within the corresponding bus bar. Note that a bus bar is a set of bus bar sections. Hence, the sections of a same bus bar should have the same bus bar index. The bus bar indices induce an order of bus bars within the voltage level, which usually reflects the bus bars physical relative positions. Similarly, the section indices induce an order of sections of a same bus bar, which usually reflects their physical relative position.

Connectable position

TODO

Coordinated reactive control

Some generators can be coordinated to control reactive power in a point of the network. This extension is used to configure the percent of reactive coordinated control that comes from a generator. This extension is attached to a generator.

Here is how to add a coordinated reactive control extension to a generator:

generator.newExtension(CoordinatedReactiveControlAdder.class)
    .withQPercent(40)
    .add();

Please note that the sum of the \(qPercent\) values of the generators coordinating a same point of the network must be 100.

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Discrete measurements

This extension is used to store discrete measurements (such as tap positions, switch positions etc.) collected in substations.

The DiscreteMeasurement class characteristics are the following:

ENTSO-E area

TODO

HVDC angle droop active power control

This is an extension dedicated to DC line in order to model AC emulation. For a VSC converter station operating in AC emulation, its active power setpoint is given by \(P = P0 + k~(ph1 - ph2)\)

HVDC operator active power range

This extension enables to replace the operational limits of an DC line in AC emulation. In that case, the VSC converter stations min active power and max active power are not used.

Generator ENTSO-E category

TODO

Generator short-circuit

This extension models the generators data used for short-circuit calculations. Depending on the type of short-circuit study to be performed, either the transient or the sub-transient reactance should be filled. The reactance of the step-up transformer should be filled if the generator has a transformer that is not directly modeled in the network.

This extension is provided in the com.powsybl:powsybl-iidm-extensions module.

To add this extension to a generator, the code to be used is:

generator.newExtension(GeneratorShortCircuitAdder.class)
    .withDirectTransX(20)
    .withDirectSubtransX(14)
    .withStepUpTransformerX(10)
    .add();

Identifiable short-circuit

This extension models the maximum and minimum short-circuit current admissible for any identifiable.

This extension is provided in the com.powsybl:powsybl-iidm-extensions module.

To add this extension to a bus, for example, the code to be used is:

bus.newExtension(IdentifiableShortCircuitAdder.class)
    .withIpMin(3000)
    .withIpMax(10000)
    .add();

The code is similar for every identifiable.

Injection observability

This extension models injections’ flows’ observability, obtained after a state estimation.

Observability quality

This extension contains the sub-object ObservabilityQuality.

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Load asymmetrical

A balanced load is described by its active power setpoint \(P0\) and its reactive power setpoint \(Q0\). This extension is used to describe the power asymmetry for each ABC phase. In the three-phase representation, the complex power injected at a bus \(i\) is constant for each phase and represented by three complex values:

But for a balanced load flow, the constant power load \(P\) and \(Q\) refer to the positive sequence load. Given that, in balanced conditions, the load for zero and negative sequences should always be zero. However, in real life, power loads are better defined in the ABC three phases representation. The load extension addresses this issue keeping the default behavior for balanced conditions.

Balanced load flow conditions:

In balanced conditions given the load at bus:

We must verify:

Unbalanced load flow conditions:

We must take into account that many loads are still balanced and information related to balanced loads is sufficient. The extension proposes a delta approach where unbalances are expressed in the extension. Supposing that:

are provided in input through the extension. The three-phase power values used as inputs of an unbalanced load flow calculation are:

As a consequence, if no extension provided for the load, the unbalanced load flow will use in input:

Here is how to add a load detail extension to a load:

load.newExtension(LoadAsymmetricalAdder.class)
        .withDeltaPa(-1)
        .withDeltaQa(1)
        .withDeltaPb(-2)
        .withDeltaQc(2)
        .add();

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Load detail

A load is described by its active power setpoint \(P0\) and its reactive power setpoint \(Q0\). This extension is used to detail :

• In the total amount of active power what is fixed and what is time-dependant (also called variable). The time-dependant part can be adjusted for production equals consumption.
• In the total amount of reactive power what is fixed and what is time-dependant (also called variable).

Here is how to add an load detail extension to a load:

load.newExtension(LoadDetailAdder.class)
    .withVariableActivePower(40)
    .withFixedActivePower(20)
    .withVariableReactivePower(5)
    .withFixedReactivePower(2)
    .add();

All of this extension’s attributes are multi-variants: they can vary from one variant to another.

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Measurements

This extension is used to store measurements collected in substations.

The Measurement class characteristics are the following:

Remote reactive power control

This extensions is used for generators with a remote reactive control.

Slack terminal

This extension is attached to a voltage level and is used to define the slack bus of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis. Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter isReadSlackBus. Use this extension after a computation to attach to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable default load flow parameter isWriteSlackBus.

The slack bus is defined through the terminal of a connectable that belongs to the bus. It is totally allowed to define a disconnected terminal as slack as the connectable could be reconnected during a grid study.

SlackTerminal.attach(bus);

This extension is provided by the com.powsybl:powsybl-iidm-api module.

Three-windings transformer phase angle clock

This extension is used to model the Vector Group of a three windings transformer. The phase angle clock could be modeled at leg 2, leg 3 or both legs 2 and 3 and of a three windings transformer (network side). The voltage phase angle displacement is represented with clock hours. The valid values are 0 to 11. This extension is attached to a three windings transformer.

transformer.newExtension(ThreeWindingsTransformerPhaseAngleClock.class)
    .withPhaseAngleClockLeg2(10)
    .withPhaseAngleClockLeg3(1)
    .add();

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Three-windings transformer to be estimated

This extension is used to indicate if a three-winding transformer tap changer is to be estimated during a state estimation, i.e. if its tap position should be an output of the state estimation.

• The three-winding transformer model offers the possibility to have up to 3 ratio tap changers and up to 3 phase tap changers. Each tap changer can be estimated or not.
• If a tap changer is not to be estimated, it should not be changed during a state estimation (its tap position is merely an input of the state estimation).

Example of code to get the status of the n°1 phase tap changer:

3wt.getExtension(ThreeWindingsTransformerToBeEstimated.class).shouldEstimatePhaseTapChanger1();

This extension is provided in the module com.powsybl:powsybl-iidm-extensions.

When adding the extension, the ThreeWindingsTransformerToBeEstimatedAdder extension should be used.

Example of code to add the extension:

transformer.newExtension(ThreeWindingsTransformerToBeEstimatedAdder.class)
        .withRatioTapChanger1Status(true)
        .add();

Two-windings transformer phase angle clock

This extension is used to model the Vector Group of a two windings transformer. The phase angle clock is modeled at side 2 of a two windings transformer. The voltage phase angle displacement is represented with clock hours. The valid values are 0 to 11. This extension is attached to a two windings transformer.

transformer.newExtension(TwoWindingsTransformerPhaseAngleClockAdder.class)
    .withPhaseAngleClock(3)
    .add();

This extension is provided in the module com.powsybl:powsybl-iidm-extensions.

Two-windings transformer to be estimated

This extension is used to indicate if a two-winding transformer tap changer is to be estimated during a state estimation, i.e. if its tap position should be an output of the state estimation.

• A two-winding transformer has a ratio tap changer and/or a phase tap changer. Each tap changer can be estimated or not.
• If a tap changer is not to be estimated, it should not be changed during a state estimation (its tap position is merely an input of the state estimation).

Example of code to get the status of the ratio tap changer:

2wt.getExtension(TwoWindingsTransformerToBeEstimated.class).shouldEstimateRatioTapChanger();

This extension is provided in the module com.powsybl:powsybl-iidm-extensions.

When adding the extension, the TwoWindingsTransformerToBeEstimatedAdder extension should be used.

Example of code to add the extension:

Example of code:

transformer.newExtension(TwoWindingsTransformerToBeEstimatedAdder.class)
        .withPhaseTapChangerStatus(true)
        .add();

Voltage per reactive power control

This extension is used to model voltage control of static VAR compensators. This extension is attached to a static VAR compensator.

When this extension is present and the slope greater than zero, the reactive output of the static VAR compensator is defined by:

\(Q = \dfrac{VoltageSetpoint - V}{slope}\)
where \(V\) is the voltage at regulating terminal and \(VoltageSetpoint\) the target value in voltage given as attribute in a static VAR compensator.

Here is how to add a voltage per reactive power control extension to a static VAR compensator:

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

This extension is provided by the com.powsybl:powsybl-iidm-extensions module.

Reference Priority

This extension is attached to a Generator, or a BusBarSection or a Load and is used to define the angle reference bus of a power flow calculation, i.e. which bus will be used with a zero voltage angle. Use this extension before a computation to force the reference bus selection. The support of this feature by Load Flow implementations may vary. For example, the OpenLoadFlow implementation today supports Reference Priorities on generators only when this feature is activated.

The reference bus is defined through the terminal of the equipment and an integer specifying the reference priority. 0 means “do not use as reference”, 1 is “highest priority”, 2 “second priority”, etc.

ReferencePriority.set(generator, 1);

int priority = ReferencePriority.get(generator); // note: returns zero if none defined

This extension is provided by the com.powsybl:powsybl-iidm-api module.

Reference Terminals

This extension is attached to a Network and is used to define the angle references of a Power Flow solution. The support of this feature by Load Flow implementations may vary. For example, the OpenLoadFlow implementation today supports writing to the Network the terminals of the reference generators chosen via the Reference Priority extension.

The reference bus is defined through the terminal of the equipment and an integer specifying the reference priority. 0 means “do not use as reference”, 1 is “highest priority”, 2 “second priority”, etc.

Set<Terminal> referenceTerminals = ReferenceTerminals.getTerminals(network);

ReferenceTerminals.reset(network);

ReferenceTerminals.add(terminal);

This extension is provided by the com.powsybl:powsybl-iidm-api module.