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 (TO BE REWORKED)

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 being called, although this should be very fast and not be a problem.

more context with builder

Prior to 3.3.0, we could only supply one RunningContext for the result builder. Now we can have different SecurityAnalysisResultContext(see following section) supplied to builder for different steps.

1. A pre-contingency context could be supplied to builder like:

builder.preContingency(preResultContext);

in this case, the preResultContext would be used in creation N-situation result. Of course, the old method always exists, then the context passed in the constructor of builder would be used by default.

2. A contingency context could be supplied to builder like:

builder.contingency(new Contingency("contingency1"), postResultContext)

3. A limit violation context could be supplied with:

builder.addViolation(violation, violationContext);

This context will be passed directly to new method onLimitViolation() in SecurityAnalysisInterceptor.

SecurityAnalysisResultContext - new interface for builder and interceptor

This new class could be supplied to builder and consumed in new SecurityAnalysisInterceptor methods. You can create a specific context by inheritance a DefaultSecurityAnalysisResultContext. Then consume this context in a correspondent interceptor.

@Override
public void onPreContingencyResult(LimitViolationsResult preContingencyResult, SecurityAnalysisResultContext context) {
if (context instanceof MyContext) {
                MyContext myContext = (MyContext) context;
                // do something
}

New methods in interceptor

All the current interceptor's methods have been deprecated, but 5 more specific new methods are added in this version.

• 3 methods are invoked while creation results: pre-contingency result, contingency result, and final result
• 2 methods are invoked while adding violation with/without contingency

To adapt your security analysis implementation to new methods, you only need to change the order of arguments like

//onPreContingencyResult(runningContext, result); // the old way
onPreContingencyResult(result, runningContext);

You are encouraged to implement your own security analysis context as described above.

IIDM-XML files can only be exported in a unique file

Before this release, it was possible to export IIDM-XML files in separated files, one file for the core network and the other(s) for its extension(s). From this release, it will not be possible anymore. If you want to limit the exported extensions, configure the iidm.export.xml.extensions property as explained in the XML exporter documentation page.

Identifiable.getName() has been deprecated

From this release, the method getName() of Identifiable and its extending classes has been deprecated. Please replace it by getNameOrId() if you wish to keep the same behavior. You can also use getOptionalName().orElse(...) if you wish to have a default value different than the Identifiable's id.

New extension API

The following extensions have been refactored to follow the new API, introduce in powsybl v3.2.0

• CoordinatedReactiveControl