Skip to content

Migration guide v4.7.0

Jump to bottom
Anne Tilloy edited this page Mar 3, 2022 · 13 revisions

Additional clarifications on power flow inputs (SSH) and state values (SV)

Breaking change

During CGMES import, all target flows are now set by SSH profile and all calculated flows are set by SV profile.

Deprecated

In CGMES import, the parameter iidm.import.cgmes.profile-used-for-initial-state-values has been deprecated and now has the same behaviour as the new parameter iidm.import.cgmes.profile-for-initial-values-shunt-sections-tap-positions and only defines if shunt sections and tap positions are defined by SSH or SV profiles.

Delete CGMES update to only use CGMES full export

From this release, the CGMES update mechanism is not supported anymore. You are now able to generate CGMES files from any network by using the CGMES exporter. By default, all profiles are exported (EQ, TP, SSH and SV) but you can modify the configuration if you want to export specific profiles.

For example, if you wish to export only the SSH and SV profiles, add this to your configuration:

import-export-parameters-default-value:
   iidm.export.cgmes.profiles:
         - SSH
         - SV

You can also pass a Properties object containing this configuration:

Properties properties = new Properties();
properties.put("iidm.export.cgmes.profiles", List.of("SSH", "SV"));
new CgmesExport().export(network, properties, dataSource);

Redundant attribute in ObservabilityQuality is a boolean and not a Boolean anymore

Methods in BranchObservability and InjectionObservability setting the redundant attribute of ObservabilityQuality sub-objects, such as setQualityP1(double standardDeviation, boolean redundant), do not pass a Boolean anymore but a boolean, preventing null object to be passed.

Fix IIDM transformers substation check

Transformers created directly in the network (not in a substation) must now have all of their legs directly in the network as well (not in a substation). In parallel, transformers created in a substation must now have all of their legs in this substation. Transformers with part of their legs directly in the network and part of their legs in a substation are now forbidden.

Migrate to IIDM/XIIDM 1.7

At this release, IIDM has been changed to version 1.7. Consequently, if you are using a XIIDM converter from powsybl-core v4.7.0 and above to write IIDM network files in version 1.7, you should use a XIIDM converter from powsybl-core v4.7.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.0"

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

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

These new features and changes include:

Create powsybl-iidm-modification

A new artifact has been introduced in this release: powsybl-iidm-modification. The API ModificationTask in powsybl-contingency-api artifact has been renamed to NetworkModification and moved to this package. Besides, the ModificationTask::modify method has been renamed to NetworkModification::apply. Note that new apply methods have also been introduced, but with default implementations to ensure backward compatibility.

All inheriting classes of ModificationTask have been moved, from powsybl-action-util and from powsybl-contingency-api to that artifact. Some renaming occured at the same time, as the "task" keyword was removed but also for some classes to clarify the corresponding modification:

  • Contingency::toTask renamed into Contingency::toModification
  • ContingencyElement::toTask renamed into ContingencyElement::toModification (which returns a Tripping instead of an AbstractTrippingTask)
  • CompoundModificationTask renamed into NetworkModificationList
  • CloseSwitchTask renamed into CloseSwitch
  • OpenSwitchTask renamed into OpenSwitch
  • GeneratorModificationTask renamed into GeneratorModification
  • PhaseShifterOptimizerTask renamed into PhaseShifterOptimizeTap
  • PhaseShifterFixedTapTask renamed into PhaseShifterSetAsFixedTap
  • PhaseShifterTapTask renamed into PhaseShifterShiftTap
  • AbstractTrippingTask renamed into AbstractTripping
  • ContingencyTopologyTraverser renamed into TrippingTopologyTraverser

In groovy scripts used with powsybl-action, you can use the new keyword modifications instead of the previous tasks keyword, but tasks is still supported.

Replace simulShunt in LoadFlowParameters by shuntCompensatorVoltageControlOn

Breaking change

simulShunt and all associated methods in LoadFlowParameters have been replaced by shuntCompensatorVoltageControlOn.

Deprecated

All previous methods have been deprecated and call new methods.

Improvements on Security Analysis API

All SecurityAnalysis::runAsync and SecurityAnalysis::run methods with no ContingenciesProvider have been removed (a security analysis with no contingencies is of limited interest).

For a similar reason, the arguments order has been changed for methods SecurityAnalysis::runAsync and SecurityAnalysis::run:

  • from (Network, String, LimitViolationDetector, LimitViolationFilter, ComputationManager, SecurityAnalysisParameters, ContingenciesProvider, List<SecurityAnalysisInterceptor>, List<StateMonitor>) to (Network, String, ContingenciesProvider, SecurityAnalysisParameters, ComputationManager, LimitViolationFilter, LimitViolationDetector, List<SecurityAnalysisInterceptor>, List<StateMonitor>)
  • from (Network, String, LimitViolationDetector, LimitViolationFilter, ComputationManager, SecurityAnalysisParameters, ContingenciesProvider, List<SecurityAnalysisInterceptor>) to (Network, String, ContingenciesProvider, SecurityAnalysisParameters, ComputationManager, LimitViolationFilter, LimitViolationDetector, List<SecurityAnalysisInterceptor>)

Sensitivity Analysis API

A sensitivity analysis is based on a Network called network here.

Use SensitivityFactor class to describe a sensitivity factor you want to compute. For example, if you want to evaluate the impact of a generator targetP increase on the active power of a branch, without any contingency, you can simply write: SensitivityFactor factor = new SensitivityFactor(SensitivityFunctionType.BRANCH_ACTIVE_POWER, "NHV1_NHV2_1", SensitivityVariableType.INJECTION_ACTIVE_POWER, "GEN", false, ContingencyContext.none());
where NHV1_NHV2_1 is the id of the monitored branch and GEN the id of the generator. Note that boolean false just says if this factor is a variable set or not. A SensitivityVariableSet is used to describe what is usually called GLSK (Generation and Load Shift Keys). A SensitivityVariableSet is a simple class with an id (that cannot be already in the network) and a list of WeightedSensitivityVariable. A weighted variable only has an id that refers to the variable id (a load or a generator id for example) and a weight. As we can compute several variable sets, you should provide a list of SensitivityVariableSet, called variableSets here, that could be empty.

If you want to simulate contingencies, just provide a list of contingencies as List<Contingency>.

Then, to run a sensitivity analysis, just do:

SensitivityAnalysisResult result = SensitivityAnalysis.run(network, VariantManagerConstants.INITIAL_VARIANT_ID, List.of(factor), contingencies, variableSets, parameters, computationManager, Reporter.NO_OP);

Newly multi-variant extensions

The following extensions' attributes have been made multi-variant in iidm-impl:

  • targetQ and enabled in RemoteReactivePowerControl
  • droop and participate in ActivePowerControl
  • qPercent in CoordinatedReactiveControl
  • p0, droop and enabled in HvdcAngleDroopActivePowerControl
  • oprFromCS1toCS2 and oprFromCS2toCS1 in HvdcOperatorActivePowerRange

Please note that these attributes can now vary from one variant to another.

Clone this wiki locally