Skip to content

Migration guide v4.0.0

Jump to bottom
Jon Harper edited this page Apr 16, 2021 · 7 revisions

Migrating to Java 11

From this version, powsybl-core should now be used with Java 11. Please note that the compilation with Java 8 may now crash or not work correctly. If you are using powsybl-core dependencies in your project, stay on the last release (3.8.0) or migrate to Java 11 to use the latest release.

Contingency API has changed

Contingency.setId method has been removed

Contingency.checkValidity usage has been replaced by ContingencyList.getValidContingencies. This method is deprecated and will be removed in a future release.

Sensitivity Analysis API has changed

ContingenciesProvider usage has been replaced by List<Contingency> in the PR #1553.

Several methods of the SensitivityAnalysis class have changed. You must change your code to use the new API, and avoid compilation issues. Respectively use:

CompletableFuture<SensitivityAnalysisResult> run(Network network,
                                                 String workingStateId,
                                                 SensitivityFactorsProvider factorsProvider,
                                                 List<Contingency> contingencies,
                                                 SensitivityAnalysisParameters parameters,
                                                 ComputationManager computationManager);

instead of

CompletableFuture<SensitivityAnalysisResult> run(Network network,
                                                 String workingStateId,
                                                 SensitivityFactorsProvider factorsProvider,
                                                 ContingenciesProvider contingenciesProvider,
                                                 SensitivityAnalysisParameters parameters,
                                                 ComputationManager computationManager);

If you were using EmptyContingenciesProvider, you can use Collections.emptyList() instead

Migrate to IIDM/XIIDM 1.5

At this release, IIDM has been changed to version 1.5. For more information about the new features, please read the documentation page about IIDM/IIDM-XML 1.5 evolutions.

API

If you are using a custom implementation of IIDM API (different from the one available in powsybl-iidm-impl), please be sure to update your implementation to use the new features.

New methods breaking the API have been added: Branch.newActivePowerLimits1/2(), DanglingLine.newActivePowerLimits(), ThreeWindingsTransformer.Leg.newActivePowerLimits(), Branch.newApparentPowerLimits1/2(), DanglingLine.newApparentPowerLimits() and ThreeWindingsTransformer.Leg.newApparentPowerLimits().

Serialization

If you are using a XIIDM converter from powsybl-core v3.7.0 and above to write IIDM network files in version 1.5, you should use a XIIDM converter from powsybl-core v3.9.0 to read them as well without issues.

Please note that it is possible to read and write XIIDM files in previous IIDM-XML versions.

In order to write XIIDM files in previous versions (e.g. the version 1.0), you need to use the following configuration property:

import-export-parameters-default-value:
  iidm.export.xml.version: "1.0"

or use the Java object ExportOptions in your parameters with a suitable set version:

... // do something
ExportOptions options = new ExportOptions().setVersion("1.0");
NetworkXml.write(network, options, path);
... // do something

⚠️ Writing XIIDM files in previous versions will only be possible if the network you want to serialize has no new features or has only new features that can be interpreted in the previous versions.

Reading XIIDM files in previous versions does not require any particular configuration.

checkRatioTapChangerRegulation new boolean parameter for strict or lenient check

After the bugfix of #1606, some malformed networks will start to fail the checkRatioTapChangerRegulation(...) check. A new parameter boolean loadTapChangingCapabilities has been added in v4.0.1 to allow to log a warning instead of hard failing the check. Strict users should pass true, lenient users should pass the value of the loadTapChangingCapabilities attribute of the equipment. powsybl-iidm-impl is strict in 4.0.0 and lenient in 4.0.1 and later.

powsybl-iidm-util artifact has been removed (to avoid split package)

All powsybl-iidm-util classes have been moved to powsybl-iidm-api with in same package. As powsybl-iidm-util depends on powsybl-iidm-api, the only thing to do for migration is to replace powsybl-iidm-util dependency by powsybl-iidm-api if it's not already present in your pom.xml.

Extensions refactoring (to avoid split package)

  • All powsybl-iidm-api extensions have been moved to powsybl-iidm-extensions in the same package (SlackTerminal and LoadDetail)
  • Extensions implementations of powsybl-iidm-extensions have been moved to powsybl-iidm-impl
  • Extensions XML serializers of powsybl-iidm-extensions have been moved to powsybl-iidm-xml-converter

Extensions writer

The XmlWriterContext::getExtensionsWriter() has been deprecated and will be removed in a next release. Please replace the usage of this method:

XmlUtil.writeFloat("rdp", xnode.getRdp(), context.getExtensionsWriter());

by

XmlUtil.writeFloat("rdp", xnode.getRdp(), context.getWriter());

com.powsybl.commons.io.MathUtil has been removed

CGMES importer needs the new kinds of limits

Active and apparent power limits are imported in the CGMES importer from this version. IIDM API and IIDM impl must be updated as well to prevent breaking change.

Exception thrown if not valid terminal reference in XIIDM export

From this version, if a terminal reference points to a busbar section, an exception is thrown if the user tries to export the network in XIIDM bus-breaker or XIIDM bus-branch. The user should export the network in XIIDM node-breaker or delete or replace the terminal reference.

Clone this wiki locally