CGMES: remove extension for Control Areas, use IIDM Area

[zamarrenolm]

Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

Does this PR already have an issue describing the problem?

What kind of change does this PR introduce?

Update

What is the current behavior?

Information from CGMES control areas is stored using an extension to the Network Model (CgmesControlArea).

What is the new behavior (if this is a feature change)?
Information from CGMES control areas is stored using native IIDM objects of class Area.
CGMES pTolerance attribute is stored as a property.
The ENTSO-E attribute IdentifiedObject.energyIdentCodeEic is stored as an alias.

For assembled models (CGM), the new behaviour has support for tie flows of a control area located at the boundary point of tie lines

Does this PR introduce a breaking change or deprecate an API?

• Yes
• No

If yes, please check if the following requirements are fulfilled

• The Breaking Change or Deprecated label has been added
• The migration steps are described in the following section

What changes might users need to make in their application due to this PR? (migration steps)

Import

During import, CGMES control areas (objects of class ControlArea) are now mapped directly to PowSyBl objects of type Area.
Here is a correspondance table to access to the control area data:

Data	Previously	Now
Location	CgmesControlArea extension	IIDM Area of type CgmesNames.CONTROL_AREA_TYPE_KIND_INTERCHANGE
ID	extension.getId()	area.getId()
Name	extension.getName()	area.getName()
Net interchange	extension.getNetInterchange()	area.getInterchangeTarget() .orElse(Double.NaN)
P tolerance	extension.getPTolerance()	Double.parseDouble(area.getProperty(CgmesNames.P_TOLERANCE, "NaN")
energyIdentCodeEic	extension.getEnergyIdentificationCodeEIC()	area.getAliasFromType(CgmesNames.ENERGY_IDENT_CODE_EIC) .orElse(null)
Terminals	extension.getTerminals()	area.getAreaBoundaryStream() .map(AreaBoundary::getTerminal) .filter(Optional::isPresent) .map(Optional::get) .toSet()
Boundaries	extension.getBoundaries()	area.getAreaBoundaryStream() .map(AreaBoundary::getBoundary) .filter(Optional::isPresent) .map(Optional::get) .toSet()

Export

Previously, during export, if the CgmesControlArea extension was not present in the exported network, a new one was created and a control area representing the whole network was added to it, with the terminals of all dangling lines defined as its tie flows. As a result, the CGMES export always had a control area of type interchange.

After this PR, no control area is automatically created during export. The export process itself will not add, remove or change the attributes of the objects in the IIDM model.

If the user wants to define a control area interchange based on the whole network, it can do it programmatically using the following line of code:

new CgmesExport().createDefaultControlAreaInterchange(network);

It is located in the CgmesExport exporter because the creation of a default area involves potential access to reference data (boundaries) and using some export parameters that the user may have already configured. The relevant data: the sourcing actor (that determines its region and the corresponding EIC code), the consideration of boundary nodes (and associated tie flows) as AC or DC. Also, the user can provide some of the parameters explicitly, if needed. As an example, including the final call to CGMES export:

Properties exportParams = new Properties();
exportParams.put(CgmesImport.BOUNDARY_LOCATION, "....");
exportParams.put(CgmesExport.NAMING_STRATEGY, NamingStrategyFactory.CGMES);

new CgmesExport().createDefaultControlAreaInterchange(network, exportParams);
network.write("CGMES", exportParams, outputPath);

Other information:

• Balancing adjustment mechanism is adapted in [CGMES balances adjustment] Migrate from cgmes.extensions.CgmesControlArea to iidm.network.Area powsybl-entsoe#178
• Backward compatibility for CgmesControlAreas extension deserialization is handled by Add backward compatibility for CgmesControlAreas extension deserialization  #3298

[olperr1]

Could you also update the doc about CGMES import?
It still references the CgmesControlArea extension here.

[zamarrenolm]

Could you also update the doc about CGMES import? It still references the CgmesControlArea extension here.

Updated. Thanks for the catch!

[olperr1]

Could you also update the doc about CGMES import? It still references the CgmesControlArea extension here.

Updated. Thanks for the catch!

I think that some lines should also be added (in the same page) about the imported IIDM Areas, in replacement of the deleted section.

[zamarrenolm]

Could you also update the doc about CGMES import? It still references the CgmesControlArea extension here.

Updated. Thanks for the catch!

I think that some lines should also be added (in the same page) about the imported IIDM Areas, in replacement of the deleted section.

Added a short description about the behaviour of the import for control areas.

[olperr1]

Could you also update the doc about CGMES import? It still references the CgmesControlArea extension here.

Updated. Thanks for the catch!

I think that some lines should also be added (in the same page) about the imported IIDM Areas, in replacement of the deleted section.

Added a short description about the behaviour of the import for control areas.

Thanks a lot @zamarrenolm!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
86.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud