Migration guide v6.3.0

Breaking changes for all users

Reporter new API: ReportNode

Starting from this release, Reporter and Report interfaces have been merged into a ReportNode interface, which contains the same features. The com.powsybl.commons.reporter package has been renamed into com.powsybl.commons.report, hence the corresponding imports are impacted.

• The root ReportNode can be build thanks to the builder provided by ReportNode.newRootReportNode(),
• A ReportNode can be added within another ReportNode thanks to the adder provided by reportNode.newReportNode().

The mentioned adder and builder share the same methods, with the following correspondence to former ReportBuilder methods:

• withMessageTemplate(String messageKey, String messageTemplate) corresponds to reportBuilder.withKey(messageKey).withDefaultMessage(messageTemplate)
• the withTypedValue(key, value, type) methods keep the same signature as in the former ReportBuilder
• the withUntypedValue(key, value, type) methods corresponds to reportBuilder.withValue(key, value, type)
• withSeverity(TypedValue severity), which corresponds to reportBuilder.withSeverity(TypedValue severity)
• withSeverity(String severity), which corresponds to reportBuilder.withSeverity(new TypedValue(severity, TypedValue.SEVERITY)

Here are some replacement examples to help you migrate:

Previously adding a report with a builder, now adding a child ReportNode with an adder

reporter.report(Report.builder()
        .withKey("keyId")
        .withDefaultMessage("New report with typed value ${typedValue}, untyped value ${untypedValue} and severity ${reportSeverity}")
        .withTypedValue("typedValue", 20, "type")
        .withValue("untypedValue", 3.)
        .withSeverity(TypedValue.INFO_SEVERITY)
        .build());

with

ReportNode childReportNode = reportNode.newReportNode()
        .withMessageTemplate("keyId", "New report with typed value ${typedValue}, untyped value ${untypedValue} and severity ${reportSeverity}")
        .withTypedValue("typedValue", 20, "type")
        .withUntypedValue("untypedValue", 3.)
        .withSeverity(TypedValue.INFO_SEVERITY)
        .add();

Include an existing reporter / reportNode in another one

reporter.report(reportNode);

with

reporter.include(reportNode);

Note that the included ReportNode needs to be a root.

Previously adding a report / sub-reporter with createSubReporter / report, now adding a child ReportNode with an adder

Replace

Reporter subReporter = reporter.createSubReporter(taskKey, defaultName);

or

reporter.report(reportKey, defaultMessage);

with

ReportNode childReportNode = reportNode.newReportNode()
        .withMessageTemplate(reportKey, defaultMessage)
        .add();

The replacements are similar for the other Reporter::createSubReporter and Reporter::report methods.

Create a root Reporter / ReportNode

Replace the root creation

Reporter reporter = new ReporterModel(taskKey, defaultName, Maps.of(valueKey, new TypedValue(value, type)));

with

ReportNode rootReportNode = ReportNode.newRootReportNode()
        .withMessageTemplate(taskKey, defaultName)
        .withTypedValue(valueKey, value, type)
        .build();

ReporterContext changes

As a side-effect, the ReporterContext interface has been renamed into ReportNodeContext, and all the methods have been renamed. You need to replace the call to

• ReporterContext::peekReporter by ReportNodeContext::peekReportNode
• ReporterContext::getReporter by ReportNodeContext::getReportNode
• ReporterContext::pushReporter by ReportNodeContext::pushReportNode
• ReporterContext::popReportNode by ReportNodeContext::popReportNode

The implementations have also been renamed:

• SimpleReporterContext into SimpleReportNodeContext
• MultiThreadReporterContext into MultiThreadReportNodeContext

Lastly, Networks::allowReporterContextMultiThreadAccess has therefore been renamed into Networks::allowReportNodeContextMultiThreadAccess.

LoadFlow

In the LoadFlowParameters, the default value of writeSlackBus parameter is now true. This is a functional change, that could lead to differences during unit and integration tests.

Contingencies

New module powsybl-iidm-criteria

Some criteria used for contingency definition were moved in a dedicated new module: powsybl-iidm-criteria.

If you used the following classes, you should add the new module in your project dependencies and update your import statements:

• previously in the com.powsybl.contingency.contingency.list.criterion package, now in com.powsybl.iidm.criteria:
  • Criterion
  • PropertyCriterion
  • RegexCriterion
  • SingleCountryCriterion
  • SingleNominalVoltageCriterion
  • ThreeNominalVoltageCriterion
  • TwoCountriesCriterion
  • TwoNominalVoltageCriterion
• previously in the com.powsybl.contingency.json package, now in com.powsybl.iidm.criteria.json:
  • CriterionDeserializer
  • CriterionSerializer

Security analysis

Limit reduction

SecurityAnalysisProvider.run(…) now takes an additional parameter: List<LimitReduction> limitReductions. You need to add this parameter to your own SecurityAnalysisProvider implementations.

When you used the constructor with all the parameters to create a "LimitReduction", you should use the builder. Default values for the characteristics are:

• monitoringOnly: false;
• contingencyContext: ContingencyContext.all();
• networkElementCriteria: Collections.emptyList();
• limitDurationCriteria: Collections.emptyList().

Thus, you can omit setting one of the characteristics if you used its default value.

For instance:

       LimitReduction limitReduction = new LimitReduction(LimitType.APPARENT_POWER, 0.5, false,
                ContingencyContext.all(),
                Collections.emptyList(),
                List.of(durationCriterion1, durationCriterion2));

could be rewritten in

       LimitReduction limitReduction = LimitReduction.builder(LimitType.APPARENT_POWER, 0.5)
                .withLimitDurationCriteria(durationCriterion1, durationCriterion2)
                .build();

Note:

• monitoringOnly, networkElementCriteria and contingencyContext are not specified as their default values are used;
• the with...Criteria(...) methods take either a List or varArgs. You could thus omit the encapsulating List.of() for ease of use. But in either case, the previously definied criteria are replaced by the given ones.

Limit reduction value

• LimitViolation.getLimitReduction now returns a double instead of a float;
• If you have defined your own IIDM implementation, you should change the type of the limitReductionValue parameter from float to double in the checkPermanentLimit… and checkTemporaryLimit… methods of your Branch's and ThreeWindingTransformer's implementations;
• If you have a custom LimitViolationDetector's implementation, you should change the type of the limitReductionValue parameter from float to double in the checkPermanentLimit and checkTemporaryLimit methods;
• AbstractBranchActionExpressionNode.getLimitReduction() now returns a double instead of a float.

New modules for actions

The actions previously spread out in powsybl-core have been regrouped into the module powsybl-action. If you were using either one of them, you will have to change your imports and dependencies accordingly:

• Package com.powsybl.security.action moved to com.powsybl.action in the new module powsybl-action-api;
• Package com.powsybl.security.json.action moved to com.powsybl.action.json;
• The action part of SecurityAnalysisJsonModule has been relocated to the class ActionJsonModule and moved from com.powsybl.security.json to com.powsybl.action.json. The rest of SecurityAnalysisJsonModule stays the same;
• Module with artifactId powsybl-action renamed powsybl-action-ial;
• Module with artifactId powsybl-action-dsl renamed powsybl-action-ial-dsl and packages moved accordingly;
• Module with artifactId powsybl-action-dsl-spi renamed powsybl-action-ial-dsl-spi and packages moved accordingly;
• Module with artifactId powsybl-action-simulator renamed powsybl-action-ial-simulator and packages moved accordingly;
• Module with artifactId powsybl-action-util renamed powsybl-action-ial-util and packages moved accordingly.

Sensitivity analysis

Bus reactive power

New BUS_REACTIVE_POWER sensitivity function type has been added in sensitivity factor. You need to add a default behavior in switch cases or add a behavior to the new enum value.

Breaking changes for custom IIDM implementations maintainers

IIDM

Pairing key setter for dangling lines

If you have defined your own IIDM implementation, you should implement the following methods in your DanglingLine implementations: DanglingLine setPairingKey(String pairingKey). Note that in the in-memory implementation, setting the paring key is allowed only for unpaired dangling lines. An exception is thrown otherwise.