Skip to content

Migration guide v7.4.0

Jump to bottom
Olivier Perrin edited this page Sep 25, 2026 · 23 revisions

Breaking Change Breaking changes for all users

IIDM

IIDM 1.18

Adaptations for IIDM 1.18

Downstream projects should:

  • Check in their versionable extensions' serializers/deserializers (classes extending AbstractVersionableNetworkExtensionSerDe) that a SerDeVersion value support the new version (1.18) (usually, at least a SerDeVersion has its maxIidmVersionExcluded attribute set to null);

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

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

Low limits' serialization

In the new IIDM 1.18 format, the detection kind is added for all the loading limits:
There's a new detectionKind attribute (which values are either "LOW" or "HIGH") in the activePowerLimits, apparentPowerLimits and currentLimits elements.

ValidationUtil.checkLoadingLimits(Validable, double, DetectionKind,
    Collection<LoadingLimits.TemporaryLimit>, ValidationLevel, ReportNode)

takes an additional String permanentLimitName parameter (before the DetectionKind detectionKind parameter). It now also checks that when the detection kind is "LOW", the permanent limit name is empty (limits of this kind don't have a permanent limit).

Voltage regulation refactoring

The voltage regulation was refactored to be consistent between the different network elements (generators, batteries, shunt compensators, ...).
A lot of the existing methods still exist for compatibility but are now deprecated.
You can find detailed informations on this refactoring: the breaking changes, the way to adapt your existing code to remove usage of the deprecated methods, ... in this dedicated page.

In-memory implementation

Memory improvements

This is not a breaking change per se, but in order to limit memory usage when using the in-memory IIDM implementation, it is recommended:

  • to call hasProperties() before calling getProperties() on:
    • the PropertiesHolder objects (and then the Identifiable objects)
    • the PropertiesContainer objects.
  • to call hasExtensions() before calling getExtensions() on:
    • the Identifiable objects.

Other

R on HVDC line

Negative R values on HVDC lines are now forbidden.

Change P_PCC_DROOP control mode to DC_DROOP for AcDcConverter

Existing uses of AcDcConverter.ControlMode.P_PCC_DROOP enum constant must be renamed to AcDcConverter.ControlMode.DC_DROOP. Where relevant, the load flow formula must be changed, as the definition of DC_DROOP and of the droop curve is modified. A validation of the droop curve is added to prevent its slope crossing zero, i.e. only all-positive or all-negative values of the slopes of the piecewise linear curve are allowed.

Connectable ordering at network copy

  • Both sort(...) methods of IidmSerDeUtil take an additional Network network parameter.
  • NetworkSerDe.copy(Network, NetworkFactory, ExecutorService, TreeDataFormat) takes an additional boolean preserveConnectableCreationOrder parameter.
    • When set to true, the behavior is the same as before.
    • When set to false, the connectables' creation order is preserved, but the copy takes slightly more time.
    • The NetworkSerDe.copy(...) methods that don't have this parameter keep the same behavior as before (the connectables' creation order is not preserved, but it is more performant).

Enforce valid reactive capability curve minQ/maxQ ordering

Reactive capability curve points with minQ > maxQ are now rejected by IIDM validation.

Applications importing IIDM files containing reversed values should either fix the source data or enable the iidm.import.repair-invalid-reactive-curve-limits import option to automatically reorder minQ and maxQ during import.

Applications importing from other formats (e.g. CGMES) with invalid values need to fix the data at the source, no option is provided to automatically repair in this case.

Limit scaling

Limit reduction renamed to limit scaling

This renaming impacts the following modules:

  • action-ial
  • contingency-api
  • dynamic-security-analysis
  • security-analysis
  • iidm-api
  • iidm-impl
  • iidm-tck

You can batch rename the functions, variables and documentation in the following order:

  • reduction -> scaling
  • Reduction -> Scaling (this will work for both limitReduction and limitReductions)
  • reduced -> scaled
  • reduce -> scale

There are version changes for the following elements:

  • shortcircuit results, from 1.5 to 1.6, inside limitViolations limitReduction has been renamed to limitScaling
  • security analysis result, from 1.9 to 1.10, in both PreContingencyResult and PostContingencyResult limitReduction has been renamed to limitScaling
  • serialized limit reductions files (in JSON) have been renamed to limit scalings files, bumping version from 1.2 to 1.3

In itools: The option --limit-reductions-file has been renamed to --limit-scalings-file

Permanent limit name in the scaled limits

The constructors of the following classes take an additional permanentLimitName parameter:

  • AbstractScaledLoadingLimits (AbstractReducedLoadingLimits before the renaming)
  • ScaledActivePowerLimits (ReducedActivePowerLimits before the renaming)
  • ScaledApparentPowerLimits (ReducedApparentPowerLimits before the renaming)
  • ScaledCurrentLimits (ReducedCurrentLimits before the renaming)

Math

Matrix

If you have defined implementations of the Matrix interface, you must implement the following methods:

  • void print(PrintStream out, List<String> rowNames, List<String> columnNames, PrintConfig config)
  • void print(PrintStream out, PrintConfig config)

Traversal

If you were manually implementing the traversal-and-partition pattern (iterating over vertices, tracking visited state, grouping results), you can now replace this logic with a call to computeTraversalPartitions(Traverser) or its generic overload computeTraversalPartitions(Traverser, Supplier<C>, ObjIntConsumer<C>).

Load flow validation

The following methods were renamed:

Class Old name New name
GeneratorsValidation checkGenerators(Generator, ...) checkGenerator(Generator, ...)
GeneratorsValidation checkGenerators(String, ...) checkGenerator(String, ...)
ShuntCompensatorsValidation checkShunts(ShuntCompensator, ...) checkShunt(ShuntCompensator, ...)
ShuntCompensatorsValidation checkShunts(String, ...) checkShunt(String, ...)
StaticVarCompensatorsValidation checkSVCs(StaticVarCompensator, ...) checkSVC(StaticVarCompensator, ...)
StaticVarCompensatorsValidation checkSVCs(String, ...) checkSVC(String, ...)
BusesValidation checkBuses(Bus, ...) checkBus(Bus, ...)
BusesValidation checkBuses(String, ...) checkBus(String, ...)

Refactor observability extensions

In the InjectionObservability extension, the methods getQualityP, getQualityQ and getQualityV now return Optional values. It is either possible to adapt the code and use these Optionals or use the new methods getNullableQualityP, getNullableQualityQ and getNullableQualityV that return nullables.

In the BranchObservability extension, the methods getQualityP1, getQualityP2, getQualityQ1 and getQualityQ2 now return Optional values. It is either possible to adapt the code and use these Optionals or use the new methods getNullableQualityP1, getNullableQualityP2, getNullableQualityQ1 and getNullableQualityQ2 that return nullables.

Security analysis

Changed phase tap changers

The PostContingencyResult constructor signature changed from 6 to 7 parameters, adding a required changedPhaseTapChangers list as the last parameter. All direct instantiations must pass this parameter; use List.of() when no changes are detected.

The PreContingencyResult maintains backward compatibility via constructor overloading. Existing 4-parameter calls continue to work, but to pass phase tap changer data, you must use the new 5-parameter constructor.

JSON deserialization of existing results remains compatible with the new changedPhaseTapChangers field, which is treated as optional and defaults to an empty list.

Applications can now access phase tap changers changes through the new getChangedPhaseTapChangers(), getChangedPhaseTapChanger(String transformerId) and getChangedPhaseTapChanger(String transformerId, ThreeSides side) methods on both result classes.

Dynamic simulation run parameters

A class that implement the DynamicSimulationProvider API has to implement the new method CompletableFuture<DynamicSimulationResult> run(Network network, String workingVariantId, DynamicModelsSupplier dynamicModelsSupplier, DynamicSimulationRunParameters runParameters) that replaces the deprecated method of the same name.


Dependencies

Other


Custom IIDM Impl Notice for custom IIDM implementations maintainers

IIDM

R on HVDC line checks

Custom IIDM implementations maintainers must:

  • ensure that all their implementations of HvdcLineAdder check that there is no negative r value (either check when setting r or when creating the HvdcLine with add())
  • ensure that all their implementations of HvdcLine forbid negative r values in the setR(...) method.

Change P_PCC_DROOP control mode to DC_DROOP for AcDcConverter

Custom IIDM implementations maintainers must ensure that all their implementations of DroopCurveAdder check that the droop curve has no zero droop value (on endSegment()) and that all droop values are of the same sign (on add()).

Reactive capability curve minQ/maxQ ordering

Custom IIDM implementations maintainers must ensure that all their implementations of ReactiveCapabilityCurveAdder check that minQ <= maxQ (on endPoint()).

Equivalent attributes on Connectables

Custom IIDM implementation maintainers must implement the following methods:

  • In their Connectable implementations:
    • boolean isEquivalent()
    • Connectable setEquivalent()
  • In every Adder class of a Connectable (InjectionAdder, BranchAdder, ThreeWindingsTransformerAdder, AcDcConverterAdder and BusbarSectionAdder): setEquivalent(boolean equivalent).

Deprecated Deprecated methods

IIDM

Country API

Change call to function Country::getName() to Country::getFullName() as Country::getName() is now deprecated and will later be removed. Both functions have the same behaviour, hence no more change is required.

iTools

Security analysis preprocessor

The following interfaces are deprecated:

ContingenciesProviderPreprocessorFactory SecurityAnalysisPreprocessor SecurityAnalysisPreprocessorFactory SecurityAnalysisPreprocessors

The preprocessor property in the SecurityAnalysis tool will not be replaced, the code should be adapted to stop using it.

Security analysis

Dynamic simulation parameters deprecation

In DynamicSimulationProvider

Deprecated method New method
run(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, ComputationManager, DynamicSimulationParameters , ReportNode run(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)

In DynamicSimulation API

Deprecated method New method
run(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, ComputationManager, DynamicSimulationParameters , ReportNode run(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, ComputationManager, DynamicSimulationParameters run(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, DynamicSimulationParameters run(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, DynamicSimulationParameters run(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, EventModelsSupplier, DynamicSimulationParameters run(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, OutputVariablesSupplier, DynamicSimulationParameters run(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
run(Network, DynamicModelsSupplier, EventModelsSupplier run(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, ComputationManager, DynamicSimulationParameters , ReportNode runAsync(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, ComputationManager, DynamicSimulationParameters runAsync(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, String, DynamicSimulationParameters runAsync(Network, String, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier, OutputVariablesSupplier, DynamicSimulationParameters runAsync(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier, DynamicSimulationParameters runAsync(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, OutputVariablesSupplier, DynamicSimulationParameters runAsync(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)
runAsync(Network, DynamicModelsSupplier, EventModelsSupplier runAsync(Network, DynamicModelsSupplier, DynamicSimulationRunParameters)

Math

Traversal

If you were using the method traverse(int, TraversalType, Traverser, boolean[]) to manually track visited vertices, switch to the standard traverse(int, TraversalType, Traverser) method. If needed, visited vertices can be captured directly inside your Traverser lambda.

Clone this wiki locally