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
• Busbar section position
• CIM-CGMES control areas
• CIM-CGMES conversion context extension
• CIM-CGMES dangling line boundary node
• CIM-CGMES line boundary node
• CIM-CGMES model extension
• CIM-CGMES Tap Changers
• CIM-CGMES SSH metadata
• CIM-CGMES SV metadata
• CIM characteristics
• 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 detail
• Measurements
• Merged X-node
• PSS/E conversion context extension
• PSS/E model extension
• 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
• X-node

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.

Busbar 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.

CIM-CGMES control areas

This extensions models all the control areas contained in the network as modeled in CIM-CGMES.

CGMES control area

It is possible to retrieve a control area by its ID. It is also possible to iterate through all control areas.

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

CIM-CGMES conversion context extension

This extension is used to store the CIM-CGMES conversion context as built during the CIM-CGMES import. It contains the used configuration, the terminal mapping and the CIM-CGMES model. It is provided by the com.powsybl:powsybl-cgmes-conversion module. It is not serializable.

CIM-CGMES dangling line boundary node

This extension is used to add some CIM-CGMES characteristics to dangling lines.

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

CIM-CGMES line boundary node

This extension is used to add some CIM-CGMES characteristics to boundary lines.

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

CIM-CGMES model extension

This extension is used to store the CGMES model as retrieved from the triplestore (as a query catalog) on the network. It is provided by the com.powsybl:powsybl-cgmes-conversion module. It is not serializable.

CIM-CGMES Tap Changers

TODO

CIM-CGMES SSH metadata

TODO

CIM-CGMES SV metadata

TODO

CIM characteristics

TODO

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

TODO

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 subtransient 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 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

TODO

Merged X-node

TODO

PSS/E conversion context extension

TODO

PSS/E model extension

TODO

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{V - VoltageSetpoint}{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.

X-node

TODO