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.

The new features of IIDM/XIIDM 1.1 are:

Regulating terminal for StaticVarCompensator

StaticVarCompensator can now regulate remotely. Hence, a new field regulatingTerminal is added if it is the case when serialized in a XIIDM file. This feature can not be interpreted by version 1.0: if your network has a static var compensator with a remote regulating terminal, the serialization in version 1.0 will fail. You will have to serialize it in version 1.1.

ThreeWindingsTransformer

ThreeWindingsTransformer can now support a ratio tap changer and a phase tap changer at each of its legs. Furthermore, each leg has a magnetizing conductance (g1, g2 or g3) and a magnetizing susceptance (b1, b2 or b3). It also now has a ratedU0 attribute which indicates the theorical nominal voltage of its bus star. By default, ratedU0 equals to ratedU1 (nominal voltage at leg 1).

These features can not always be interpreted by version 1.0: if your network has a three windings transformer with g2, b2, g3 or b3 which does not equal to zero, ratedU0 which does not equal ratedU1, a phase tap changer on any leg or a ratio tap changer on leg 1, the serialization in version 1.0 will fail. You will have to serialize it in version 1.1.

Shunt Compensator

The shunt compensator' model and its serialization has been entirely changed in this new IIDM-XML version.

Regulation

Shunt compensators can now be regulated. New attributes (regulation (boolean), targetV (double), targetDeadband (double) and regulatingTerminal (Terminal)) have been added to ShuntCompensator and can be set and accessed. However, to serialize or deserialize a shunt compensator with any of these attributes with a non-default value, IIDM-XML version 1.1 must be used. Otherwise, the serialization and deserialization will fail.

To know more about these attributes and their default values, go to the documentation page of ShuntCompensator.

Linear and Non-linear shunt compensator's models

TODO

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