Migration guide v3.3.0

Migrate to IIDM/XIIDM 1.2

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

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

... // do something
ExportOptions options = new ExportOptions().setVersion("1.1");
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 about IIDM/IIDM-XML 1.2 evolutions.

LoadFlowParameters version has been changed to version 1.1

The attribute specificCompatibility has been renamed. specificCompatibility is now t2wtSplitShuntAdmittance

The isSpecificCompatibility and setSpecificCompatibility methods are now isT2wtSplitShuntAdmittance and setT2wtSplitShuntAdmittance

The previous methods isSpecificCompatibility and setSpecificCompatibility have been kept as deprecated.

The current behavior is:
JSON configuration files recorded with previous version (1.0) and previous attribute tag (specificCompatiility) are supported and read.
JSON configuration files will always serialize using the current version (1.1) and the current attribute (t2wtSplitShuntAdmittance)

Deletion of voltageLevel.setNodeCount(int) method and deprecated voltageLevel.getNodeCount() method

From this release, it is not possible to pre-create vertices in a node/breaker voltage level's graph anymore. Vertices are created on the fly as network components are attached to the network.

Consequently, the method voltageLevel.setNodeCount(int) has been deleted. The method voltageLevel.getNodeCount(), returning the count of attached nodes in a node/breaker voltage level has been deprecated as it is not really useful anymore. Check in your cases if it could not be replaced by the new method voltageLevel.getMaximumNodeIndex() which returns the maximum index of attached nodes.

SecurityAnalysisResultBuilder Improvements

SecurityAnalysisResultBuilder was not thread safe. The API has been changed to make it threadsafe when adding the violations to each contingency from different threads: The addViolation method is moved from SecurityAnalysisResultBuilder to a builder returned for this contingency. If you used a full fluent style, you don't have to do anything. If you stored intermediate results of the chained method calls, you have to update the types:

// before
SecurityAnalysisResultBuilder resultBuilder = ...;
resultBuilder.contingency(contingency).setComputationOk(lfResult.isOk());
if (lfResult.isOk()) {
    violationDetector.checkAll(contingency, network, resultBuilder::addViolation);
}
resultBuilder.endContingency();

// after
SecurityAnalysisResultBuilder resultBuilder = ...;
SecurityAnalysisResultBuilder.PostContingencyResultBuilder builder =  resultBuilder.contingency(contingency).setComputationOk(lfResult.isOk());
if (lfResult.isOk()) {
    violationDetector.checkAll(contingency, network, builder::addViolation);
}
builder.endContingency();

Note that adding multiple violations for one given contingency is still not thread safe, but this is rarely done in parallel. the endContingency() method of the newly returned builders is where synchronization happens and will block if the endContingency of another builder is beeing called, although this should be very fast and not be a problem.