Skip to content

Migration guide v7.3.0

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

Breaking Change Breaking changes for all users

IIDM

IIDM 1.17

Adaptations for IIDM 1.17

Downstream projects should:

  • TBD

  • 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".

TBD

N/A

Detail of the renamed classes, methods, constants, ...


Classes

The following classes were renamed:

Old name New name
TBD TBD
Methods

The following methods were renamed:

Old name New name
TBD TBD
Constants

The following constants were renamed:

Old name New name
TBD TBD
Reports

The following ReportNode keys were renamed:

Old name New name
TBD TBD

In the messages of the following ReportNode keys, some variables were renamed:

  • ReportNode keys:
    • TBD
Old name New name
TBD TBD

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.

CGMES

TBD

N/A

TBD

N/A

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

  • Univocity-parsers has been removed from the dependencies

  • The following dependencies have been replaced:

    Old dependency New dependency
    TBD TBD

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.

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.

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

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