-
Notifications
You must be signed in to change notification settings - Fork 43
Migration guide v3.2.0
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 somethingReading XIIDM files in previous versions does not require any particular configuration.
The new features of IIDM/XIIDM 1.1 are:
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 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.
From this release, the network extensions' XML serializers are versionable. By default, network extensions will be exported in the most recent version supported by their XML serializer and compatible with the IIDM-XML version in which the network will be exported. If you want to export the extension in a specific previous version (X.Y.Z) supported by their XML serializer and compatible with the IIDM-XML version in which the network will be exported, you will have to update your configuration:
import-export-parameters-default-value:
iidm.export.xml.extensionName.version: "X.Y.Z"From this release, voltages and angles will not be expressed as attributes of the XML element iidm:busbarSection but in a new iidm:bus sub-element of iidm:nodeBreakerTopology.
Consequently, from XIIDM 1.1, the attributes v and angle will not be written nor read anymore and the attribute iidm:bus will be written for every electrical bus of the network with a defined voltage or a defined angle. It will be serialized as below:
<iidm:bus v="234.40912" angle="0.0" nodes="0,1,2,3,4"/>v and angle represent the voltage and angle of this bus while the list of nodes are all the voltage level's nodes in a same electrical bus.
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);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.
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-nameinstead of:
load-flow:
default: your-default-implementation-nameThe 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 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");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.
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).
The Xnode and ActivePowerControl extensions have been migrated to the new API.
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.