Skip to content

Migration guide v7.3.0

Jump to bottom
Olivier Perrin edited this page Jun 24, 2026 · 32 revisions

Breaking Change Breaking changes for all users

IIDM

IIDM 1.17

Adaptations for IIDM 1.17

Downstream projects should:

  • 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_16" with xmlns:iidm="http://www.powsybl.org/schema/iidm/1_17";

    • For ".json" or ".jiidm" files: replace "version" : "1.16" with "version" : "1.17".

Permanent limit name

In iidm-api:

  • LimitViolationUtils.PERMANENT_LIMIT_NAME has been removed. You can instead use LoadingLimits.DEFAULT_PERMANENT_LIMIT_NAME

If you are using iidm-impl, the following changes might impact you:

  • PermanentLimitInfo now takes an additional name String, which corresponds to the name of the permanent limit.
  • notifyPermanentLimitUpdate now takes two new String arguments, oldName and newName.
  • CurrentLimitsImpl, ApparentPowerLimitsImpl and ActivePowerLimitsImpl constructors now take an additional permanentLimitName String argument.

New setId method

In the IIDM in-memory implementation (provided by iidm-impl), the BoundaryLine#replaceId(String newId) method was removed. You can use the new Identifiable#setId(String id) instead.

The DefaultNetworkListener abstract class was removed; its empty implementation methods are now defined as default methods in the NetworkListener interface. If one of your classes extended DefaultNetworkListener, you just have to make it implement NetworkListener instead.

Here are some examples of adaptations:

- public class MyListener extends DefaultNetworkListener {
+ public class MyListener implement NetworkListener {
- NetworkListener listener = new DefaultNetworkListener() {
+ NetworkListener listener = new NetworkListener() {
      @Override
      public void onCreation(Identifiable identifiable) {
          listenerCalled.setTrue();
      }
}
- Mockito.mock(DefaultNetworkListener.class);
+ Mockito.mock(NetworkListener.class);

Low loading limits

In iidm-api, ValidationUtil, checkLoadingLimitsand checkPermanentLimit now take an additional DetectionKind parameter. If you have the limit where this function is called, use limit.getDetectionKind. Otherwise, you can use a default value of DetectionKind.HIGH but this is not recommended, as any use of your code with a low limit might lead to a bug.

The following methods of ValidationUtil take an additional DetectionKind detectionKind parameter:

  • checkLoadingLimits(Validable validable, double permanentLimit, Collection<LoadingLimits.TemporaryLimit> temporaryLimits, ValidationLevel validationLevel, ReportNode reportNode)
  • checkPermanentLimit(Validable validable, double permanentLimit, Collection<LoadingLimits.TemporaryLimit> temporaryLimits, ValidationLevel validationLevel, ReportNode reportNode)

getPermanentLimit() and setPermanentLimit(double) of the following interfaces will throw an exception when called on an object with the detection kind LOW:

  • CurrentLimits
  • ApparentPowerLimits
  • ActivePowerLimits

In addition, getOriginalPermanentLimit() and getPermanentLimitReduction() of the following classes will also throw an exception when called on an object with the detection kind LOW:

  • AbstractReducedLoadingLimits
  • ReducedCurrentLimits
  • ReducedApparentPowerLimits
  • ReducedActivePowerLimits

Load flow

Load flow parameters

A new version of load flow parameters files, the 1.11, was introduced. Differences with the previous version are:

  • a new debugDir element was added.

This is not a breaking change per se, but you should be aware of this if your project communicates with another one based on an older version of PowSyBl:

  • Load flow parameters JSON files generated by an older version of PowSyBl could still be read;
  • but load flow parameters JSON files generated by this version of PowSyBl won't be readable by older versions.

Security analysis

Limit Reductions

The LimitReduction JSON format has been bump to version 1.2.

This is not a breaking change per se, but you should be aware of this if your project communicates with another one based on an older version of PowSyBl:

  • LimitReduction JSON files generated by an older version of PowSyBl could still be read;
  • but LimitReduction JSON files generated by this version of PowSyBl won't be readable by older versions.

Security analysis parameters

A new version of security analysis parameters files, the 1.3, was introduced. Differences with the previous version are:

  • a new monitored-element-modification-threshold element was added, containing thresholds configuration allowing to filter monitored elements results;
  • a new debug-dir element was added.

This is not a breaking change per se, but you should be aware of this if your project communicates with another one based on an older version of PowSyBl:

  • Security analysis parameters JSON files generated by an older version of PowSyBl could still be read;
  • but Security analysis parameters JSON files generated by this version of PowSyBl won't be readable by older versions.

Sensitivity analysis

Sensitivity factors reader

The constructor of SensitivityFactorJsonReader now takes an additional Network network parameter. It is used to resolve busses from bus view ids, bus/breaker view ids and a busbar section ids.

Sensitivity analysis parameters

A new version of sensitivity analysis parameters files, the 1.3, was introduced. Differences with the previous version are:

  • a new debug-dir element was added.

This is not a breaking change per se, but you should be aware of this if your project communicates with another one based on an older version of PowSyBl:

  • Sensitivity analysis parameters JSON files generated by an older version of PowSyBl could still be read;
  • but sensitivity analysis parameters JSON files generated by this version of PowSyBl won't be readable by older versions.

Sensitivity analysis results format

A new version of sensitivity analysis result files, the 1.2, was introduced. It allows to have factors with new sensitivity variable types:

  • SHUNT_COMPENSATOR_SUSCEPTANCE
  • BRANCH_RESISTANCE
  • BRANCH_REACTANCE
  • BRANCH_ADMITTANCE
  • SVC_PILOT_POINT_TARGET_VOLTAGE

This is not a breaking change per se, but you should be aware of this if your project communicates with another one based on an older version of PowSyBl:

  • Sensitivity analysis results JSON files generated by an older version of PowSyBl could still be read;
  • but sensitivity analysis results JSON files generated by this version of PowSyBl won't be readable by older versions.

AMPL

AMPL 1.3

By default, the AMPL files are now generated with the new v1.3 format, adding new columns for batteries' voltage regulation.

Network modifications

Network modifications ReportNode messages

The voltageLevelRemovingEquipmentsLeftReport(...) method of ModificationReports was replaced by the followings:

  • voltageLevelNotRemovedWithRemainingBranches(...), that should be called when branches are still present on the voltage level to remove;
  • voltageLevelNotRemovedWithNoBranch(...), that should be called when there are no remaining branches on the voltage level to remove.

Also, in the report property files, the key core.iidm.modification.voltageLevelRemovingEquipmentsLeft was replaced by the followings:

  • core.iidm.modification.voltageLevelNotRemovedWithRemainingBranches, used when branches are still present;
  • core.iidm.modification.voltageLevelNotRemovedWithNoBranch, used when there are no remaining branches.

Dependencies

These dependencies has been removed:

  • com.google.code.findbugs:annotations
  • com.google.code.findbugs:jsr305
  • com.univocity:univocity-parsers
  • org.anarres.graphviz:graphviz-builder

Other

PSS/E

A few classes were either moved to a new package or removed entirely in the package com.powsybl.psse.model.pf. This should however not impact users as those are internal classes and are not expected to be used directly.

Moved classes
Old classes New classes
c.p.p.m.pf.PsseSubstation.PsseSubstationEquipmentTerminal c.p.p.m.pf.internal.PsseSubstationEquipmentTerminal
c.p.p.m.pf.PsseSubstation.PsseSubstationEquipmentTerminalCommonStart c.p.p.m.pf.internal.PsseSubstationEquipmentTerminalCommonStart
c.p.p.m.pf.PsseSubstation.PsseSubstationEquipmentTerminalx c.p.p.m.pf.internal.PsseSubstationEquipmentTerminalx
c.p.p.m.pf.PsseSubstation.PsseSubstationNode c.p.p.m.pf.internal.PsseSubstationNode
c.p.p.m.pf.PsseSubstation.PsseSubstationNodex c.p.p.m.pf.internal.PsseSubstationNodex
c.p.p.m.pf.PsseSubstation.PsseSubstationRecord c.p.p.m.pf.internal.PsseSubstationRecord
c.p.p.m.pf.PsseSubstation.PsseSubstationSwitchingDevice c.p.p.m.pf.internal.PsseSubstationSwitchingDevice
c.p.p.m.pf.PsseSubstation.PsseSubstationSwitchingDevicex c.p.p.m.pf.internal.PsseSubstationSwitchingDevicex
c.p.p.m.pf.PsseTransformer.TransformerImpedances c.p.p.m.pf.internal.TransformerImpedances
c.p.p.m.pf.PsseTransformer.TransformerWindingRecord c.p.p.m.pf.internal.TransformerWindingRecord
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcBus c.p.p.m.pf.internal.PsseMultiTerminalDcBus
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcBusx c.p.p.m.pf.internal.PsseMultiTerminalDcBusx
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcConverter c.p.p.m.pf.internal.PsseMultiTerminalDcConverter
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcConverterx c.p.p.m.pf.internal.PsseMultiTerminalDcConverterx
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcLink c.p.p.m.pf.internal.PsseMultiTerminalDcLink
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcLinkx c.p.p.m.pf.internal.PsseMultiTerminalDcLinkx
c.p.p.m.pf.PsseMultiTerminalDcTransmissionLine.PsseMultiTerminalDcMain c.p.p.m.pf.internal.PsseMultiTerminalDcMain
c.p.p.m.pf.io.TransformerImpedanceCorrectionTablesData.ZCorr33 c.p.p.m.pf.internal.ZCorr33
c.p.p.m.pf.io.TransformerImpedanceCorrectionTablesData.ZCorr35First c.p.p.m.pf.internal.ZCorr35First
c.p.p.m.pf.io.TransformerImpedanceCorrectionTablesData.ZCorr35Points c.p.p.m.pf.internal.ZCorr35Points
c.p.p.m.pf.io.TransformerImpedanceCorrectionTablesData.ZCorr35X c.p.p.m.pf.internal.ZCorr35X
Removed classes
Removed classes
c.p.p.m.pf.io.WindingHeaderTransformer
c.p.p.m.pf.io.WindingRatesHeaderTransformer

IEEE-CDF

The following classes have been moved from com.powsybl.ieeecdf.model to com.powsybl.ieeecdf.model.elements:

  • IeeeCdfBranch
  • IeeeCdfBus
  • IeeeCdfInterchangeData
  • IeeeCdfLossZone
  • IeeeCdfTieLine
  • IeeeCdfTitle

They now extend the new abstract class AbstractIeeeElement.

The following classes have been moved from com.powsybl.ieeecdf.model to com.powsybl.ieeecdf.model.conversion:

  • BranchSideConversion
  • BranchTypeConversion
  • BusTypeConversion
  • LocalDateConversion
  • SeasonConversion

They do not extend anymore the class com.univocity.parsers.conversions.ObjectConversion.

unused attribute of IeeeCdfBranch and IeeeCdfBus were renamed sequenceNumber. Their setters and getters were renamed accordingly.


Custom IIDM Impl Notice for custom IIDM implementations maintainers

IIDM

Add resistance to DC switch

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

  • In your DcSwitch implementation:
    • double getR()
    • DcSwitch setR(double r)
  • In your DcSwitchAdder implementation:
    • DcSwitchAdder setR(double r)

Loading limits detection kind

Custom IIDM implementations' maintainers must implement the following methods:

  • in their LoadingLimits implementations:
    • DetectionKind getDetectionKind()

Only import/export active limits groups

The getAllSelectedOperationalLimitsGroups methods of Branch and FlowsLimitsHolder now return a List<OperationalLimitsGroup> instead of a Collection<OperationalLimitsGroup>. A stable ordering when adding or deleting selected group is now required for these methods, and enforced by a TCK test.

setConnectableBus with variants

In the Bus/Breaker view, the connectable bus of the terminals is supposed to be managed by variant.
This wasn't the case for the IIDM in-memory implementation. This was fixed, and a unit tests was introduced in the TCK to cover this case.
Custom IIDM implementation maintainers may have adaptations to do in order to respect this new test.

Active power limits for AC/DC converters

  • Implementations of AcDcConverterAdder will need to implement methods setMinP and setMaxP to set power limits of ACDC converters.
  • Implementations of AcDcConverter will need to implement methods getMinP, setMinP, getMaxP and setMaxP.
  • Default values are -Double.MAX_VALUE (resp. Double.MAX_VALUE) for minP (resp. maxP) so you only need to assign these bounds if you actually need them.

PQU diagram for reactive limits

Custom IIDM implementation maintainers must implement the following interfaces:

  • ReactiveCapabilityShape
  • ReactiveCapabilityShapeAdder
  • ReactiveCapabilityShapePlane

And the following method in their ReactiveLimitsHolder implementations

  • ReactiveCapabilityShapeAdder newReactiveCapabilityShape()

Note that:

  • this feature is in BETA for now. No TCK are available for now, since the format may change a little in the future.
  • these elements are not handled by the IIDM (de)serialization

Short-circuit

Add homopolar conductance and susceptance to LineFortescue

Custom IIDM implementation maintainers must implement the following methods:

  • in their LineFortescue implementations:

    • double getG1z()
    • double getB1z()
    • double getG2z()
    • double getB2z()
    • void setG1z(double g1z)
    • void setB1z(double b1z)
    • void setG2z(double g2z)
    • void setB2z(double b2z)

  • in their LineFortescueAdder implementations:

    • LineFortescueAdder withG1z(double g1z)
    • LineFortescueAdder withB1z(double b1z)
    • LineFortescueAdder withG2z(double g2z)
    • LineFortescueAdder withB2z(double b2z)

Add magnetizing reactance to TwoWindingsTransformerFortescue

Custom IIDM implementation maintainers must implement the following methods:

  • In their TwoWindingsTransformerFortescue implementations:

    • double getXm();
    • void setXm(double xm);

  • In their TwoWindingsTransformerFortescueAdder implementations:

    • TwoWindingsTransformerFortescueAdder withXm(double xm);

Other

Connect / disconnect on terminal, tie line, HVDC line

Custom IIDM implementations' maintainers should modify:

  • Terminal.disconnect()
  • TIeLine.disconnectBoundaryLines()
  • HvdcLine.disconnectConverterStations()

to only change the state of the non-fictional breakers, instead of all the breakers.

DC connectable connect and disconnect

If you have your own implementation of DcConnectable, you must implement the following methods:

  • boolean connectDc()
  • boolean disconnectDc()

Duplicates detected when merging networks

The error message when elements with the same ID are found during network merge was changed to indicate which networks are concerned.

  • Before: The following object(s) of type <type> exist(s) in both networks: [<duplicate_ids>]
  • After: The following object(s) of type <type> already exist in merged network when trying to merge network '<network_id_2>': [<duplicate_ids>]

Since some TCK unit tests check this message, custom IIDM implementation maintainers should adapt there merge method to have the same error message.

More detailed error messages at temporary limits creation

Custom IIDM implementations' maintainers should change the exception messages that may be encountered at the temporary limits creation:

  • When the value is NaN:
    • temporary limit value is not set for '<name>' within limit set '<operationalGroupId>'
  • When the value is < 0:
    • temporary limit value must be >= 0 for '<name>' within limit set '<operationalGroupId>'
  • When the acceptable duration is null:
    • acceptable duration is not set for '<name>' within limit set '<operationalGroupId>'
  • When the acceptable duration is < 0:
    • acceptable duration must be >= 0 for '<name>' within limit set '<operationalGroupId'>

Topology-specific error messages at equipment creation

Custom IIDM implementations' maintainers should change the message of the validation exception that is thrown when an equipment is created in a VoltageLevel in node/breaker without specifying the node:

  • Before: <equipment type> '<ID>': connectable bus is not set
  • After: <equipment type> '<ID>': node is not set

setId method for Identifiables

Custom IIDM implementations' maintainers should implement the following method:

  • Identifiable#setId(String id)

They should also remove the following method:

  • BoundaryLine#replaceId(String newId)

Deprecated Deprecated methods

Contingency

LimitViolation constructors deprecation

If you are using the following constructors:

  • LimitViolation(String subjectId, @Nullable String subjectName, String operationalLimitsGroupId, LimitViolationType limitType, @Nullable String limitName, int acceptableDuration, double limit, double limitReduction, double value, @Nullable ThreeSides side, @Nullable ViolationLocation voltageLocation)
  • LimitViolation(String subjectId, LimitViolationType limitType, double limit, double limitReduction, double value, ViolationLocation voltageLocation)

Then no change is required.

Otherwise you can:

  • use LimitViolationBuilder, either with new LimitViolationBuilder() or with LimitViolation.builder(), add the values and then use .build()
  • use the constructor of LimitViolation with all the variables (mentionned above), and provide null values for all the variables you do not have a value for

Note that if you were using a constructor and were providing null values to it, you do not need to do that with the Builder. Also note that the default limitReduction is 1 and the default acceptableDuration is Integer.MAX_VALUE.

Clone this wiki locally