-
Notifications
You must be signed in to change notification settings - Fork 42
Migration guide v3.3.0
At this release, IIDM has been changed to version 1.2. For more information about the new features, please read the documentation page about IIDM/IIDM-XML 1.2 evolutions.
If you are using a custom implementation of IIDM API (different from the one available in powsybl-iidm-impl), please be sure to update your implementation in order not to throw UnsupportedOperationException when a new method is used.
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 somethingReading XIIDM files in previous versions does not require any particular configuration.
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)
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 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.
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.
- 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.
- A contingency context could be supplied to builder like:
builder.contingency(new Contingency("contingency1"), postResultContext)- A limit violation context could be supplied with:
builder.addViolation(violation, violationContext);This context will be passed directly to new method onLimitViolation() in SecurityAnalysisInterceptor.
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
}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.
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.
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.
The following extensions have been refactored to follow the new API, introduce in powsybl v3.2.0
- CoordinatedReactiveControl
- ActivePowerControl
Configured loadflow and security analysis parameters were already overridable with a JSON file passed to command line tools itools loadflow and itools security-analysis. However, the override behaviour was not correct for extensions : the whole extension objects were replaced, whereas we wanted to be able to override only some of their properties.
In order to fix this behaviour, which could be considered a bug of the JsonLoadFlowParameters.update and JsonSecurityAnalysisParameters.update methods, a new method has been added to extension JSON serializers to correctly support this feature. In order to use it, you will need to adapt your existing implementations:
@AutoService(JsonLoadFlowParameters.ExtensionSerializer.class)
public class ExtensionSerializer implements JsonLoadFlowParameters.ExtensionSerializer<MyExtension> {
//...Existing code
//new method to update an existing extension value
@Override
MyExtension deserializeAndUpdate(JsonParser jsonParser, DeserializationContext deserializationContext, MyExtension extension) throws IOException {
//Code to update the existing extension and return it
}
}If not provided, the behaviour will be the same as in powsybl 3.2.0 (extensions will be replaced instead of only updated with the subset of properties defined in JSON).
If you want an Extendable to use this feature, you can use the new provided method JsonUtil.updateExtensions, similar to the already existing JsonUtil.readExtensions.
The version of powsybl-math-native has been updated to v1.0.2 to fix a bug in the LU factorization. This native library is available for 64 bits OS only. Under Windows, you need to install the Visual C++ Runtime 2019 (64 bits).