Migration guide v6.8.0

Breaking changes for all users

Commons

ReportNode usage in ValidationUtil

• NetworkReports.parentHasBothRatioAndPhaseTapChanger(ReportNode reportNode, String parentMessage) was replaced by NetworkReports.transformerHasBothRatioAndPhaseTapChanger(ReportNode reportNode, String id).
• NetworkReports.parentHasDuplicatePointForActivePower(ReportNode reportNode, String ownerMessage, Double p) was replaced by NetworkReports.parentHasDuplicatePointForActivePower(ReportNode reportNode, String id, Double p).

ReportNode test bundle renaming

PowsyblCoreTestReportResourceBundle has been renamed to PowsyblTestReportResourceBundle.

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 behavior 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)

Limits creation methods' change

The methods newCurrentLimits, newApparentPowerLimits and newActivePowerLimits on Branch and FlowsLimitsHolder are now deprecated.

Their use should be replaced by the call to the new method getOrCreateSelectedOperationalLimitsGroup() (that creates anOperationalLimitsGroup and set it as selected, if needed) followed by a call to the limits' creation on the group.

Basically, replace myDanglingLine.newCurrentLimits() by myDanglingLine.getOrCreateSelectedOperationalLimitsGroup().newCurrentLimits()

Note that previously, the deprecated methods only created the default group - if needed - at the limits' creation (during the call to add() on the resulting limits adder). Now, the default group is created by the deprecated methods. Therefore, the group is created even if add() is never called on the resulting adder.

Regulation value check in current limiter

When validating a PhaseTapChanger by calling ValidationUtil.checkPhaseTapChangerRegulation(Validable validable, PhaseTapChanger.RegulationMode regulationMode, double regulationValue, boolean regulating, Terminal regulationTerminal, Network network, ValidationLevel validationLevel, ReportNode reportNode) method with STEADY_STATE_HYPOTHESIS validationLevel, a ValidationException is now thrown if regulationMode=CURRENT_LIMITER and regulationValue is negative.

With this new rule, manually creating or modifying a PhaseTapChanger will throw an exception when it is configured in CURRENT_LIMITER regulation with a negative regulation value. At CGMES or IIDM import, when a negative regulation value is encountered for a phase tap changer in CURRENT_LIMITER regulation, its sign will be changed (the value will be considered as positive).

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.

CGMES import property removal

CGMES import parameter CgmesImport.PROFILE_FOR_INITIAL_VALUES_SHUNT_SECTIONS_TAP_POSITIONS ("iidm.import.cgmes.profile-for-initial-values-shunt-sections-tap-positions") was removed. Now that there are distinct attributes for initial values (sectionCount and tapPosition) and solved values (resp. solvedSectionCount and solvedTapPosition), this parameter was no more pertinent.

If you need to have the SV values in the initial values' attributes (which corresponds to the "SV" value of the removed parameter), you can copy the solved values in the initial values' attributes by calling Networks.applySolvedTapPositionAndSolvedSectionCount(network);

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());

Dependencies

Annotations

Replace every import javax.annotation.Nullable; with import org.jspecify.annotations.Nullable;

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()

Get or create selected operational limits group

Custom IIDM implementations' maintainers should implement the following methods:

• in their Branch implementations:

  • OperationalLimitsGroup getOrCreateSelectedOperationalLimitsGroup1();
  • OperationalLimitsGroup getOrCreateSelectedOperationalLimitsGroup2();

• In their FlowsLimitsHolder implementations:

  • OperationalLimitsGroup getOrCreateSelectedOperationalLimitsGroup();

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 compensators

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)

Load tap changing capabilities 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.

Solved tap position on tap changers

Custom IIDM implementations' maintainers should implement the following methods:

• in their TapChanger's implementations:
  • Integer getSolvedTapPosition()
  • C setSolvedTapPosition(int solvedTapPosition)
  • C unsetSolvedTapPosition()
  • S getSolvedCurrentStep();
• in their TapChangerAdder's implementations:
  • S setSolvedTapPosition(Integer solvedTapPosition)

Detailed DC model

If you defined your own IIDM implementation, you should implement the following methods:

• in your Network implementations:

  • DcNode
    • DcNodeAdder newDcNode()
    • Iterable<DcNode> getDcNodes()
    • Stream<DcNode> getDcNodeStream()
    • int getDcNodeCount()
    • DcNode getDcNode(String id)
  • DcLine
    • DcLineAdder newDcLine()
    • Iterable<DcLine> getDcLines()
    • Stream<DcLine> getDcLineStream()
    • int getDcLineCount()
    • DcLine getDcLine(String id)
  • DcSwitch
    • DcSwitchAdder newDcSwitch()
    • Iterable<DcSwitch> getDcSwitchs()
    • Stream<DcSwitch> getDcSwitchStream()
    • int getDcSwitchCount()
    • DcSwitch getDcSwitch(String id)
  • DcGround
    • DcGroundAdder newDcGround()
    • Iterable<DcGround> getDcGrounds()
    • Stream<DcGround> getDcGroundStream()
    • int getDcGroundCount()
    • DcGround getDcGround(String id)
  • LineCommutatedConverter
    • Iterable<LineCommutatedConverter> getLineCommutatedConverters()
    • Stream<LineCommutatedConverter> getLineCommutatedConverterStream()
    • int getLineCommutatedConverterCount()
    • LineCommutatedConverter getLineCommutatedConverter(String id)
  • VoltageSourceConverter
    • Iterable<VoltageSourceConverter> getVoltageSourceConverters()
    • Stream<VoltageSourceConverter> getVoltageSourceConverterStream()
    • int getVoltageSourceConverterCount()
    • VoltageSourceConverter getVoltageSourceConverter(String id)
  • DcConnectable
    • Iterable<DcConnectable> getDcConnectables()
    • Stream<DcConnectable> getDcConnectableStream()
    • int getDcConnectableCount()
    • DcConnectable getDcConnectable(String id)

• in your VoltageLevel implementation:

  • LineCommutatedConverter
    • LineCommutatedConverterAdder newLineCommutatedConverter()
    • Iterable<LineCommutatedConverter> getLineCommutatedConverters()
    • Stream<LineCommutatedConverter> getLineCommutatedConverterStream()
    • int getLineCommutatedConverterCount()
  • VoltageSourceConverter
    • VoltageSourceConverterAdder newVoltageSourceConverter()
    • Iterable<VoltageSourceConverter> getVoltageSourceConverters()
    • Stream<VoltageSourceConverter> getVoltageSourceConverterStream()
    • int getVoltageSourceConverterCount()

• in your TopologyVisitor implementation:

  • void visitAcDcConverter(AcDcConverter<?> converter, TwoSides side)

getMessageHeader return type

Users which were using a custom IIDM implementation need to return a MessageHeader instead of a String for getMessageHeader method in the classes implementing Validable.

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.