Migration guide v3.2.0

Migrate to IIDM/XIIDM 1.1

At this release, IIDM has been changed to version 1.1. Consequently, if you are using a XIIDM converter from powsybl-core v3.2.0 and above to write IIDM network files in version 1.1, you should use a XIIDM converter from powsybl-core v3.2.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.

For more information about the new features, please read the documentation page on IIDM/IIDM-XML 1.1 evolutions.

Deprecate AbstractConnectableXml.writeCurrentLimits methods without an IidmXmlVersion parameter

From this release, the methods AbstractConnectableXml.writeCurrentLimits(Integer, CurrentLimits, XMLStreamWriter) and AbstractConnectableXml.writeCurrentLimits(Integer, CurrentLimits, XMLStreamWriter, String) are deprecated. In order to keep the same behavior, instead of:

AbstractConnectableXml.writeCurrentLimits(index, limits, writer);
AbstractConnectableXml.writeCurrentLimits(index, limits, writer, nsUri);

respectively use:

AbstractConnectableXml.writeCurrentLimits(index, limits, writer, IidmXmlConstants.CURRENT_IIDM_XML_VERSION);
AbstractConnectableXml.writeCurrentLimits(index, limits, writer, nsUri, IidmXmlConstants.CURRENT_IIDM_XML_VERSION);

Default IIDM implementation depends on configuration

From this release, the default IIDM implementation is not hard-coded anymore, it can be found in the dependencies graph or in the configuration. Hence, it is now necessary to add an implementation of PowSyBl configuration in your pom.xml file whenever an IIDM implementation is called. In order to keep the behavior of previous releases, if the default IIDM implementation is called in your test, add this dependency:

<dependency>
  <groupId>com.powsybl</groupId>
  <artifactId>powsybl-config-test</artifactId>
  <version>3.2.0</version>
  <scope>test</scope>
</dependency>

and if it is called elsewhere, add:

<dependency>
  <groupId>com.powsybl</groupId>
  <artifactId>powsybl-config-classic</artifactId>
  <version>3.2.0</version>
</dependency>

To know more about this new configuration module, go to the documentation page of network module configuration.

Change property name in load-flow configuration module

From this release, the name of the property to choose the load-flow default implementation is not default anymore but default-impl-name. Replace your configuration accordingly as follows:

load-flow:
    default-impl-name: your-default-implementation-name

instead of:

load-flow:
    default: your-default-implementation-name

Moved classes from iidm-impl artifact to iidm-api artifact

The following classes have moved

Before:

com.powsybl.iidm.network.impl.Validable
com.powsybl.iidm.network.impl.ValidationException
com.powsybl.iidm.network.impl.ValidationUtil

After:

com.powsybl.iidm.network.Validable
com.powsybl.iidm.network.ValidationException
com.powsybl.iidm.network.ValidationUtil   

IEEE CDF import format has been renamed

IEEE CDF is now IEEE-CDF. Be careful to update your code accordingly e.g. replace:

Importer ieeeCdfImporter = Importers.getImporter("IEEE CDF");

by

Importer ieeeCdfImporter = Importers.getImporter("IEEE-CDF");

InternalConnectionAdder does not inherit from IdentifiableAdder anymore

From this release, InternalConnectionAdder does not inherit from IdentifiableAdder anymore. Therefore, the methods InternalConnectionAdder.setId(String), InternalConnectionAdder.setName(String) and InternalConnectionAdder.setEnsureIdUnicity(boolean) do not exist anymore. Be careful to delete them from your code.

New Extension API

A new extension API is available. It allows to choose the extension implementation at runtime. It works like this:

// Old API
// new Extension hardcodes the implementation
extendable.addExtension(Extension.class, new Extension(data));

// new API
// the extension implementation is selected at 
// runtime based on the implementation of the extendable.
// This is only possible for extensions that
// have been migrated to the new API.
extendable.newExtension(ExtensionBuilder.class).withData(data).add();

Using the previous API still works, but extensions will be gradually migrated to the new API. Using extensions that have been migrated to the new API with the old API will not be compatible: you will usually need to replace new Extension() by new ExtensionImpl() For clients, migrating to the new API means that their code will be usable by other implementations than the default in memory implementation.

If you have a custom implementation of the Extendable API, you will also have to code an implementation of the method <E extends Extension<Generator>, B extends ExtensionAdder<Generator, E>> B newExtension(Class<B> type).

Migrated extensions

The Xnode and ActivePowerControl extensions have been migrated to the new API.

Loadflow validation. StaticVarCompensator check.

StaticVarCompensator check has been extended to support remote control. A new argument Vcontrolled has been added to method checkSVCs. Now, this method has three voltage arguments:
vControlled specifies the voltage of the controlled bus.
vController specifies the voltage of the controller bus and
nominalVcontroller specifies the nominal voltage of the controller bus.

vControlled and vController must be equal if the control is local (controlled and controller buses are the same) and will have different values when the control is remote.