Migration guide v6.8.0

Breaking changes for all users

Commons

IIDM

IIDM 1.14

Adaptations for IIDM 1.14

Downstream projects should:

• Update their classes extending AbstractVersionableNetworkExtensionSerDe to add an entry for the new version (1.14) in the first map of the call to super(...);
• Upgrade the version in their XIIDM / JIIDM unit test files corresponding to the current version:
  • For ".xiidm" or ".xml" files: replace xmlns:iidm="http://www.powsybl.org/schema/iidm/1_13" with xmlns:iidm="http://www.powsybl.org/schema/iidm/1_14";
  • For ".json" or ".jiidm" files: replace "version" : "1.13" with "version" : "1.14".

LoadTapChangingCapabilities for phase tap changers

Importer of other grid formats such as CGMES, UCTE-DEF, PSS/E etc. must ensure that regulation is enabled only on TapChangers with loadTapChangingCapabilities set to true.

Network simulators implementing simulation of ratio or tap phase tap control do not need to check the loadTapChangingCapabilities status anymore, since iIDM validation ensures regulation can be enabled only for tap changers with on load tap changing capability.

For backward compatibility of existing external code, PhaseTapChangerAdder assumes a default value of true (unlike RatioTapChangerAdder in which default is false).

ValidationUtil.checkPhaseTapChangerRegulation(...) now takes an additional boolean loadTapChangingCapabilities parameter.

Phase tap changers' FIXED_TAP regulation mode removal

Phase tap changer regulation mode RegulationMode.FIXED_TAP was removed.

Retro compatibility exists to still handle older IIDM versioned files (<1.14) with FIXED_TAP mode. The mode in IIDM will then be CURRENT_LIMITER with regulating=false so an import/export round trip with FIXED_TAP regulation mode at the beginning will fail but functionnally there should be no impact.

If you used FIXED_TAP mode:

• to disable the regulation on an already existing phase tap changer, you should call phaseTapChanger.setRegulating(false) instead.
• to initialize a phase tap changer, you should set regulating to false, and use another regulation mode (default one is CURRENT_LIMITER).

Flag to enable static var compensator regulation

RegulationMode.OFF was removed. If you used it:

• to disable the regulation on an already existing StaticVarCompensator, you should call svc.setRegulating(false) instead and set the regulationMode to VOLTAGE or REACTIVE_POWER.
• to initialize a StaticVarCompensator, you should set regulating to false, and use another regulation mode (default one is VOLTAGE).

Globally:

• in a check, you should now use svc.isRegulating()
• when creating a StaticVarCompensator, it is now mandatory to explicitly set the regulating attribute. If not the validation will fail.
• if you want to set regulating to true then you should set its regulating set point (reactive power or voltage setpoint) and its consequently RegulationMode before setting the regulating value as some controls are made to check that the regulation is correctly set before activating the regulation.

Solved values

Loadflow runs compute the tap positions of tap changers and the section counts of compensators. But with the previous IIDM versions, the loadflow models replaced the original values with the resulting values. This was a problem because running another loadflow on the same network may give different results. To avoid this, new attributes were introduced in IIDM v1.14:

• TapChanger.getSolvedTapPosition()
• ShuntCompensator.getSolvedSectionCount()

New methods were also introduced to replace the original values with the solved values, if they have a value:

• Networks.applySolvedValues(Network network): perform the replacement on a whole network:
  • For transformers: copy solvedTapPosition in tapPosition.
  • For shunt compensators: copy solvedSectionCount in sectionCount.
  • For batteries: copy terminal's p and q respectively in targetP and targetQ.
  • For generators: copy terminal's p and q respectively in targetP and targetQ, and bus' v in targetV.
  • For dangling lines: copy terminal's p and q respectively in targetP and targetQ, and bus' v in targetV.
  • For loads: copy terminal's p and q respectively in p0 and q0.
• applySolvedValues on all these network elements, if you want to copy only the solved values for a single network element.
• applySolvedTapPositionAndSolvedSectionCount(Network network): perform the replacement on the whole network, but only for solvedTapPosition (for transformers) and solvedSectionCount (for shunt compensators) fields.

As not all load flow models may support these new fields, if you want to maintain the same behaviour as before, simply call the applySolvedTapPositionAndSolvedSectionCount(Network network) method after your load flow has run.

New parameter for ValidationUtil.validate

The boolean throwException parameter of ValidationUtil.validate(...) was replaced by an enum value. If you used this method, you can use one of the following values:

• ValidationUtil.ActionOnError.THROW_EXCEPTION: throw an exception if an error is detected - corresponds to older throwException = true);
• ValidationUtil.ActionOnError.LOG_ERROR: report all the errors in the given reportNode and on the console - corresponds to older throwException = false);
• ValidationUtil.ActionOnError.IGNORE: ignore all the errors (no exception, no logs and no reports)

Contingency

Introduction of a ContingencyElementFactory

Users should replaces calls of ContingencyElement.of(Identifiable<?> identifiable) to ContingencyElementFactory.create(Identifiable<?> identifiable)

Identifiers

UTF-16 support in IdWithWildcardsNetworkElementIdentifier

• The JSON serialization of IdWithWildcardsNetworkElementIdentifier now contains a wildcard attribute. When reading a JSON without this attribute, the default wildcard (?) is used.
• As a consequence, the serializations of the following elements (which can contain a IdWithWildcardsNetworkElementIdentifier) are potentially impacted. Their serialization version numbers were increased:

Category	Element	Previous version	New version
Action list	ActionList	1.1	1.2
Contingency list	IdentifierContingencyList	1.2	1.3
Contingency list	ListOfContingencyLists	1.0	1.1

⚠️ The JSON serialized version of these elements (action or contingency list) may be not readable with older versions of PowSyBl.

Also, this change of serialization versions can have an impact on your unit tests (if you use a JSON serialized object as a reference).

CGMES

Drop support for CIM14

• CIM 14 CGMES files are not supported anymore. Please use CIM16 (2.4.15) or CIM100 (3.0) files.
• As a direct consequence, the followings were removed:
  • CgmesModel.CIM_14_NAMESPACE,
  • CgmesModel.CIM_14,
  • CgmesOnDataSource.existsCim14() : now it would have always returned false,
  • CgmesModel.Cim.hasProfiles(): now it would have always returned true.
• The CgmesModel interface was also modified. The method modelProfiles is no longer a default method, meaning that you have now to implement it if you designed your own implementation of the interface.
• The public constant CIM_LIST from the CgmesNamespace class has gone from List.of(CIM_14, CIM_16, CIM_100) to List.of(CIM_16, CIM_100)
• Deleted CIM14 network files are available in previous releases ( $vX.Y.Z \leq v6.7.0$) if needed.

New DC conversion

• The CgmesModel interface has been modified with:

  • 2 additions:
    • PropertyBags dcSwitches()
    • PropertyBags dcGrounds()
  • 1 deletion:
    • CgmesDcTerminal dcTerminal(String dcTerminalId)

• Context.getDc() was removed.

• The com.powsybl.cgmes.conversion.elements.hvdc package was removed and replaced by a new com.powsybl.cgmes.conversion.elements.dc package.

Unit tests refactoring

The following methods of CgmesConformity1ModifiedCatalog, were removed:

• smallNodeBreakerHvdcDcLine2Inverter1Rectifier2()
• smallNodeBreakerHvdcDcLine2BothConvertersTargetPpcc1inverter2rectifier()
• smallNodeBreakerHvdcDcLine2BothConvertersTargetPpcc1rectifier2inverter()
• smallNodeBreakerHvdcVscReactiveQPcc()
• smallNodeBreakerHvdcNanTargetPpcc()
• smallNodeBreakerHvdcMissingDCLineSegment()
• smallNodeBreakerHvdcMissingAcDcConverters()
• smallNodeBreakerHvdcTwoDcLineSegments()
• smallNodeBreakerHvdcTwoDcLineSegmentsOneTransformer()
• smallNodeBreakerHvdcTwoAcDcConvertersOneDcLineSegments()
• smallNodeBreakerHvdcWithTransformers()
• smallNodeBreakerHvdcWithTwoTransformers()
• smallNodeBreakerHvdcWithDifferentConverterTypes()
• smallNodeBreakerHvdcWithVsCapabilityCurve()
• smallNodeBreakerVscConverterRemotePccTerminal()
• smallNodeBreakerHvdcTwoAcDcConvertersTwoDcLineSegments()
• smallNodeBreakerHvdcTwoAcDcConvertersTwoDcLineSegmentsNoAcConnectionAtOneEnd()

They were used for unit testing, but they relied on big CGMES files ; this slowed the tests execution. If you still need to use them, you can retrieve the methods at this URL and the corresponding CGMES files in this directory.

Quality

Equipments class' removal

Starting from this release, the previously deprecated Equipments class has been removed from iidm API. If you were using getConnectionInfoInBusBreakerView(Terminal t), use the following code instead:

connected = t.getBusBreakerView().getBus();
bus = Optional.ofNullable(t.getBusBreakerView().getBus()).orElse(t.getBusBreakerView().getConnectableBus());

Notice for custom IIDM implementations maintainers

New method in ThreeWindingsTransformer

Custom IIDM implementation maintainers should implement the following method in their ThreeWindingsTransformer's implementations:

Terminal getTerminal(String voltageLevelId);

Properties on OperationalLimitsGroup

Custom IIDM implementations' maintainers should implement the following methods in their OperationalLimitsGroup implementations:

• public boolean hasProperty()
• public boolean hasProperty(String key)
• public String getProperty(String key)
• public String getProperty(String key, String defaultValue)
• public String setProperty(String key, String value)
• public boolean removeProperty(String key)
• public Set<String> getPropertyNames()

New methods for phase tap changers

Custom IIDM implementations' maintainers should implement the following methods:

• In PhaseTapChanger's implementations (noted as C below):
  • C setLoadTapChangingCapabilities(boolean loadTapChangingCapabilities)
  • boolean hasLoadTapChangingCapabilities()
• In PhaseTapChangeAdder's implementations (noted as S below):
  • S setLoadTapChangingCapabilities(boolean loadTapChangingCapabilities)

New default regulation mode for phase tap changers

Custom IIDM implementations' maintainers should change the default regulationMode value to CURRENT_LIMITER in their PhaseTapChangerAdder's implementations.

SVC regulation changes

Custom IIDM implementations' maintainers should implement the following methods:

• in StaticVarCompensator's implementations:
  • boolean isRegulating()
  • StaticVarCompensator setRegulating(boolean regulating)
• in StaticVarCompensatorAdder's implementations:
  • StaticVarCompensatorAdder setRegulating(boolean regulating)

In their StaticVarCompensatorAdder implementations, they should set:

• regulating to false when it is null in EQUIPMENT level;
• regulationMode to VOLTAGE when it is null.

In their RegulatingPoint implementations, they should:

• have regulating depending on the variant;
• initialize regulating to VOLTAGE by default.

Solved section count on shunt compensator

Custom IIDM implementations' maintainers should implement the following methods:

• in their ShuntCompensator's implementations:
  • Integer getSolvedSectionCount()
  • ShuntCompensator setSolvedSectionCount(int solvedSectionCount)
  • ShuntCompensator unsetSolvedSectionCount()
• in their ShuntCompensatorAdder's implementations:
  • ShuntCompensatorAdder setSolvedSectionCount(Integer solvedSectionCount)

Deprecated methods

CGMES post processors' methods deprecation

If you called one of these methods, you should use their new signatures instead (old signatures are now deprecated):

• CgmesAnalogPostProcessor.process(...)
• CgmesDiscretePostProcessor.process(...)

They both now take a Map<String, PropertyBag> idToBayBag instead of a PropertyBags bays.