Skip to content

Migration guide v6.4.0

Jump to bottom
Olivier Perrin edited this page Jun 28, 2024 · 30 revisions

Breaking Change Breaking changes for all users

Zero values for loading limits

This is not really a breaking change, but you should be aware that LoadingLimits can now be imported/created with a zero value for permanent or temporary limits. As a consequence, you can now have a Double.NaN if you divide something by one of these limits.

Ref interface

Starting from this release the Ref interface and its implementations RefObj and RefChain are now in powsybl-commons artifact, in com.powsybl.commons.ref package.

The Ref interface was an internal utility class of powsybl-iidm-impl but its visibility was nonetheless public. If you were using this interface or one of its implementation, you need to replace the import clauses (e.g. the import com.powsybl.iidm.network.impl.util.RefObj; with com.powsybl.commons.ref.RefObj;), and include powsybl-commons artifact in your pom.xml file.

ReportNode

  • Starting from this release, the ReportNode JSON files from API v2.0 cannot be read anymore. Please switch to JSON files generated with API V2.1.
  • ReportConstants.REPORT_SEVERITY_KEY has been renamed into ReportConstants.SEVERITY_KEY
  • When a root ReportNode was included in another ReportNode, only its children were added. This was fixed and now the ReportNode is "unrooted" and included itself. If you had made a workaround to recreate the root, you can revert it.

Security analysis

Security analysis runner parameters

For SecurityAnalysisProvider implementations, replace

run(Network, String workingStateId, LimitViolationDetector, LimitViolationFilter, ComputationManager, SecurityAnalysisParameters, ContingenciesProvider, List<SecurityAnalysisInterceptor>, List<OperatorStrategy>, List<Action>, List<StateMonitor>, List<LimitReduction>, ReportNode)

with

run(Network, String workingStateId, ContingenciesProvider, SecurityAnalysisRunParameters)

For SecurityAnalysis API, the various run and runAsync methods overloads are now limited to:

  • run(Network, String workingStateId, ContingenciesProvider, SecurityAnalysisRunParameters)
  • runAsync(Network, List<Contingency>, SecurityAnalysisRunParameters)
  • runAsync(Network, List<Contingency>)

LimitViolationDetector removed from SecurityAnalysis API

Starting from this release the LimitViolationDetector is removed from security analysis API. The default implementations remains available, and the DefaultSecurityAnalysis default implementation still handles a LimitViolationDetector parameter through its constructor, although it is now becoming nullable. The DefaultSecurityAnalysisProvider now builds a DefaultSecurityAnalysis with a null LimitViolationDetector.

If you want to still use the LimitViolationDetector you need to pass one to your security analysis (or to the DefaultSecurityAnalysis). Hence, you cannot use directly the DefaultSecurityAnalysisProvider anymore. It is thus not possible to call SecurityAnalysis.find() to create the SecurityAnalysis.Runner anymore. Instead, you should declare your own SecurityAnalysisProvider (which may or not extends DefaultSecurityAnalysisProvider) which will create a DefaultSecurityAnalysis using the constructor taking a LimitViolationDetector. As a consequence, the provider won't be retrieved dynamically from the default-impl-name property of the configuration file.

IIDM Validation Util rework

The ValidationUtil utility class was reworked to ensure that the validation is well performed using a validation level. The impacts are the following:

Except the validate(…) method, all the methods having boolean throwException as a parameter are no more accessible. Instead, you should use the method taking the parameters ValidationLevel validation, ReportNode reportNode. The validation level (which generally corresponds to the network's minimal validation level) will determine if, in case of error, it should be reported in reportNode or if an exception should be thrown. Furthermore, methods having only the ValidationLevel validationLevel parameter now take ReportNode reportNode as an additional parameter.

For instance, you could not use the following methods anymore:

  • checkActivePowerSetpoint(Validable validable, double activePowerSetpoint, boolean throwException)
  • checkActivePowerSetpoint(Validable validable, double activePowerSetpoint, ValidationLevel validationLevel)

Instead, you should use:

  • checkActivePowerSetpoint(Validable validable, double activePowerSetpoint, ValidationLevel validationLevel, ReportNode reportNode)

In addition, the following methods were removed or are no more accessible:

  • throwExceptionOrLogError(…)
  • checkConnected(…)
  • checkTemporaryLimits(…)

Active power control extension

Differences from version 6.4.0-RC2

To migrate from the 6.4.0-RC2 (there is nothing to do for previous versions), you should replace:

  • ActivePowerControl.getMinPOverride() by ActivePowerControl.getMinTargetP();
  • ActivePowerControl.getMaxPOverride() by ActivePowerControl.getMaxTargetP();
  • ActivePowerControl.setMinPOverride(double) by ActivePowerControl.setMinTargetP(double);
  • ActivePowerControl.setMaxPOverride(double) by ActivePowerControl.setMaxTargetP(double);
  • ActivePowerControlAdder.withMinPOverride(double) by ActivePowerControlAdder. withMinTargetP(double);
  • ActivePowerControlAdder.withMaxPOverride(double) by ActivePowerControlAdder. withMaxTargetP(double);

Serialized IIDM networks with "activePowerControl" v1.2 extension (only possible from the 6.4.0-RC2) can no more be deserialized (unless you edit them to replace "minPOverride" by "minTargetP" and "maxPOverride" by "maxTargetP").

Code cleanup

In this release, an effort was made to reduce the project's technical debt. This work introduced some breaking changes.

Jackson

To avoid unsafe Jackson deserialization (see https://rules.sonarsource.com/java/RSPEC-4544/ ), classes implementing the interface BusRef now have to add the Jackson annotation @JsonTypeName(".<ClassName>") (with <ClassName> replaced by the class name. Note the presence of the . before the class name.). For instance IdBasedBusRef is annotated with @JsonTypeName(".IdBasedBusRef").

Removal of deprecated methods, and its impact

Following deprecated methods have been deleted:

Removed method Replacement
PlatformConfig.setDefaultConfig Directly pass PlatformConfig instance to the code you want to test.
PlatformConfig.moduleExists Test the result of PlatformConfig.getOptionalModuleConfig instead.
PlatformConfig.getModuleConfig Use PlatformConfig.getOptionalModuleConfig instead.
PlatformConfigNamedProvider.findBackwardsCompatible Use PlatformConfigNamedProvider.find instead.
PlatformConfigNamedProvider.findDefaultBackwardsCompatible Use PlatformConfigNamedProvider.findDefault instead.
StandbyAutomaton.getHighVoltageSetPoint Use StandbyAutomaton.getHighVoltageSetpoint instead.
StandbyAutomaton.setHighVoltageSetPoint Use StandbyAutomaton.setHighVoltageSetpoint instead.
StandbyAutomaton.getLowVoltageSetPoint Use StandbyAutomaton.setLowVoltageSetpoint instead.
StandbyAutomaton.setLowVoltageSetPoint Use StandbyAutomaton.setLowVoltageSetpoint instead.
StandbyAutomatonAdder.withHighVoltageSetPoint Use StandbyAutomatonAdder.withHighVoltageSetpoint instead.
StandbyAutomatonAdder.withLowVoltageSetPoint Use StandbyAutomatonAdder.withLowVoltageSetpoint instead.
UndirectedGraph.getMaxVertex If you override this method, rename it as getVertexCapacity().

⚠️ Because of the PlatformConfigNamedProvider. ...BackwardsCompatible methods' deprecation, "default" keyword will not be supported anymore in configuration files. Thus check that you use "default-impl-name" instead of "default" in your configuration, especially in load-flow and dynamic-simulation sections.

Behavior changes

The list returned by CandidateComputations.getComputationsNames() is now immutable.

Test methods renamed

Following methods were renamed in ComparisonUtils:

  • compareBytes to assertBytesEquals;
  • compareTxt to assertTxtEquals;
  • compareXml to assertXmlEquals.

This allows Sonar to detect these methods as assertions in the unit tests.


Custom IIDM Impl Notice for custom IIDM implementations maintainers

IIDM

Generic area model

If you had defined your own IIDM implementation, you should implement the following methods:

  • in your Network implementations:
    • Iterable<String> getAreaTypes();
    • Stream<String> getAreaTypeStream();
    • int getAreaTypeCount();
    • AreaAdder newArea();
    • Iterable<Area> getAreas();
    • Stream<Area> getAreaStream();
    • Area getArea(String id);
    • int getAreaCount();
  • in your VoltageLevel implementations:
    • Iterable<Area> getAreas();
    • Stream<Area> getAreasStream();
    • Optional<Area> getArea(String areaType);
    • void addArea(Area area);
    • void removeArea(Area area);

Connectable connection/disconnection

Custom IIDM implementation maintainers should define these new methods for Connectable implementations:

  • boolean connect(Predicate<Switch> isTypeSwitchToOperate, ThreeSides side);
  • boolean disconnect(Predicate<Switch> isSwitchOpenable, ThreeSides side)

They should act as their counterparts without the side parameter, but only on the specified side.

Three-winding transformers

In ThreeWindingsTransformer.Leg interface, each implementations must add a getTransformer() method that gives the transformer associated to a leg. In ThreeWindingsTransformerToBeEstimatedAdder, two new methods must be implemented:

  • withRatioTapChangerStatus(ThreeSides side, boolean toBeEstimated) and
  • withPhaseTapChangerStatus(ThreeSides side, boolean toBeEstimated).

LoadingLimits

If you had defined your own IIDM implementation, you should now allow 0 as a value for permanent and temporary limits.

TCK

New TCK feature

This is not a breaking change, but we thought that this feature needed a special notice for IIDM implementation's maintainers.

When a new test class is added to the TCK ("The IIDM Technology Compatibility Kit"), its tests are not launched with your custom IIDM implementation unless you create a test class implementing it. But with the previous versions, nothing told you that new tests were added and you may though that your IIDM implementation was fully tested.

Starting from this release, a special TCK class was added to test that all other TCK tests are extended. To enable it, you need to create a new test class implementing AbstractTckSuiteExhaustivityTest in your IIDM implementation's test directory:

class TckSuiteExhaustivityTest extends AbstractTckSuiteExhaustivityTest {}

This test will fail if any other TCK test is not extended in your own IIDM implementation's TCK test suite.

New TCK dependency

Custom IIDM implementation maintainers should add the following dependency in their TCK implementation's pom.xml:

<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <scope>test</scope>
</dependency>
Clone this wiki locally