CGMES export: Add a parameter to export as bus branch #3315

rcourtier · 2025-02-07T15:36:41Z

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?

No.

What kind of change does this PR introduce?

New feature.

Does this PR introduce a new Powsybl Action implying to be implemented in simulators or pypowsybl?

Yes, the corresponding issue is here
No

What is the current behavior?

CGMES export's topology kind depends on the network's topology kind computation. A network with at least one node/breaker voltage level will be exported as NODE_BREAKER, and a full bus/breaker network will always be exported as BUS_BRANCH.

What is the new behavior (if this is a feature change)?

The network topology kind computation has been revised. The network has to be a full node/breaker to be exported in CGMES as NODE_BREAKER, likewise it has to be a full bus/breaker to be exported in CGMES as BUS_BRANCH. In case of a hybrid (mixed topology) network, the computed topology kind depends on the CIM version for export: it is BUS_BRANCH in case of a CIM 16 export and NODE_BREAKER for a CIM 100 export.

A new parameter has been added to override the computed export topology kind and force a desired one. It allows for example to export a node/breaker network as BUS_BRANCH. The allowed values for this parameter are NODE_BREAKER and BUS_BRANCH.

The differences in the various configurations of CIM version and topology kind are:

In case of a CIM 16 BUS_BRANCH export:
- ConnectivityNode are not exported
- non-retained Switch are not exported
In case of a CIM 100 BUS_BRANCH export,
- ConnectivityNode are exported from buses of the BusBreakerView
- non-retained Switch are not exported
In case of a NODE_BREAKER export:
- ConnectivityNode are always exported, either from nodes if the VoltageLevel is at node/breaker connectivity level, or from buses if the VoltageLevel is at bus/breaker connectivity level.
- non-retained Switch are always exported.

Also, there is a specificity for the CIM 16 BUS_BRANCH export where this export intrinsically means not writting the equipment operation profile. This means the following classes won't be written:

ConnectivityNode
StationSupply
GroundDisconnector
ActivePowerLimit
ApparentPowerLimit
LoadArea
SubLoadArea
SvStatus

As well as the following attributes:

LoadGroup.LoadArea
LoadGroup.SubLoadArea
ControlArea.EnergyArea

Note: the CGMES EquipmentOperation profile contains more elements, but they don't exist in PowSyBl and are already not exported.

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)

In case of a network with mixed topology, that is with some VoltageLevel in node/breaker topology kind and some other VoltageLevel in bus/breaker topology kind, the CGMES export without this feature was always a NODE_BREAKER one. The change introduced here is that the export will now be a BUS_BRANCH one if the CIM version for export is 16 (default value).
In order to restore a NODE_BREAKER export for a mixed-topology network, one has to set the TOPOLOGY_KIND CgmesExport parameter as follows:

Network network = ...;

// Export to CGMES as node-breaker
Properties exportParameters = new Properties();
exportParameters.put(CgmesExport.TOPOLOGY_KIND, "NODE_BREAKER");
network.write("CGMES", exportParameters, Path.of("cgmes_file"));

Other information:

Signed-off-by: Romain Courtier <[email protected]>

…S_BRANCH export Signed-off-by: Romain Courtier <[email protected]>

Signed-off-by: Romain Courtier <[email protected]>

sonarqubecloud · 2025-03-05T14:19:01Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

olperr1 · 2025-03-06T13:51:37Z

cgmes/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/CgmesExport.java

+    private static final Parameter TOPOLOGY_KIND_PARAMETER = new Parameter(
+            TOPOLOGY_KIND,
+            ParameterType.STRING,
+            "The topology kind of the export",


Suggested change

"The topology kind of the export",

"Force the topology kind for the export (disable automatic detection)",

olperr1 · 2025-03-06T15:40:05Z

...s/cgmes-conversion/src/main/java/com/powsybl/cgmes/conversion/export/CgmesExportContext.java

@@ -159,12 +159,25 @@ public ReferenceDataProvider getReferenceDataProvider() {
    }

    private CgmesTopologyKind networkTopologyKind(Network network) {


Can you rename this method to detectNetworkTopologyKind?
It doesn't consider the parameters, but only the network, so it should not be used to get the topology kind. With this name, it's maybe clearer.

olperr1 · 2025-03-06T15:49:34Z

cgmes/cgmes-conversion/src/test/java/com/powsybl/cgmes/conversion/test/ConversionUtil.java

@@ -130,4 +130,11 @@ public static String getElement(String xmlFile, String className, String rdfId)
        Pattern pattern = Pattern.compile(regex, Pattern.DOTALL);
        return getFirstMatch(xmlFile, pattern);
    }
+
+    public static long getElementCount(String xmlFile, String className) {
+        String regex = "(<cim:" + className + " (rdf:ID=\"_|rdf:about=\"#_).*?\")>";


.*? can be replaced by .+.

olperr1 · 2025-03-06T16:06:52Z

docs/grid_exchange_formats/cgmes/export.md

+| 100         | `BUS_BRANCH`             | Yes (**)                              | Yes                                                 |
+
+### Connectivity elements
+* non-retained `Switch` are always written in the case of a `NODE_BREAKER` export, and never written in the case of a `BUS_BRANCH` export


Suggested change

* non-retained `Switch` are always written in the case of a `NODE_BREAKER` export, and never written in the case of a `BUS_BRANCH` export

* Non-retained `Switch` are always written in the case of a `NODE_BREAKER` export, and never written in the case of a `BUS_BRANCH` export

olperr1 · 2025-03-06T16:11:23Z

docs/grid_exchange_formats/cgmes/export.md

+* If some `VoltageLevel` of the network are at `node/breaker` and some other at `bus/breaker` connectivity level, then the export's topology kind depends on the CIM version for export: 
+it is `BUS_BRANCH` for CIM 16 and `NODE_BREAKER` for CIM 100
+
+It is however possible to ignore the computed export topology kind and force it to be `NODE_BREAKER` or `BUS_BRANCH` by setting the parameter `iidm.export.cgmes.topology-kind`.


Suggested change

It is however possible to ignore the computed export topology kind and force it to be `NODE_BREAKER` or `BUS_BRANCH` by setting the parameter `iidm.export.cgmes.topology-kind`.

It is however possible to ignore the computed export topology kind and force it to be `NODE_BREAKER` or `BUS_BRANCH` by setting the parameter [`iidm.export.cgmes.topology-kind`](#options).

rcourtier self-assigned this Feb 7, 2025

rcourtier added CGMES Feature labels Feb 7, 2025

rcourtier requested review from zamarrenolm, olperr1 and colinepiloquet February 7, 2025 16:13

rcourtier changed the title ~~CGMES export: Add a parameter to export a network as bus branch~~ CGMES export: Add a parameter to export as bus branch Feb 7, 2025

rcourtier force-pushed the refactor_cgmesnamespace_interface branch from 30aef81 to 1e8fdfd Compare February 18, 2025 15:05

rcourtier force-pushed the bus_branch_export branch 6 times, most recently from 534fe97 to bec824f Compare February 20, 2025 10:01

rcourtier added the Breaking Change API is broken label Feb 20, 2025

rcourtier force-pushed the refactor_cgmesnamespace_interface branch from 1e8fdfd to 09cc8ac Compare February 25, 2025 13:30

rcourtier force-pushed the bus_branch_export branch 4 times, most recently from 30b97d9 to cba96a8 Compare February 26, 2025 10:37

olperr1 added the Release 03/2025 label Mar 3, 2025

rcourtier mentioned this pull request Mar 5, 2025

Refactor CgmesNamespace interface #3307

Merged

9 tasks

rcourtier force-pushed the refactor_cgmesnamespace_interface branch from c72e70d to 55af22e Compare March 5, 2025 09:37

rcourtier force-pushed the bus_branch_export branch from cba96a8 to 321044c Compare March 5, 2025 10:03

rcourtier mentioned this pull request Mar 5, 2025

A network with mixed topology kind (node-breaker and bus-breaker) should be exported to CGMES as bus-branch. #3318

Open

Base automatically changed from refactor_cgmesnamespace_interface to main March 5, 2025 13:26

rcourtier added 4 commits March 5, 2025 15:06

Add a parameter to force a NODE_BREAKER or BUS_BRANCH export

bb6c599

Signed-off-by: Romain Courtier <[email protected]>

Change network topology kind computation

69e4ada

Signed-off-by: Romain Courtier <[email protected]>

Don't write connectivity elements in case of a BUS_BRANCH export

f91b1b9

Signed-off-by: Romain Courtier <[email protected]>

Don't write CIM 16 Equipment Operation elements in case of a CIM16 BU…

df9eb1d

…S_BRANCH export Signed-off-by: Romain Courtier <[email protected]>

rcourtier added 2 commits March 5, 2025 15:06

Add unit tests

1448ed7

Signed-off-by: Romain Courtier <[email protected]>

Update documentation

cca2fbd

Signed-off-by: Romain Courtier <[email protected]>

rcourtier force-pushed the bus_branch_export branch from 321044c to cca2fbd Compare March 5, 2025 14:07

olperr1 requested changes Mar 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CGMES export: Add a parameter to export as bus branch #3315

CGMES export: Add a parameter to export as bus branch #3315

rcourtier commented Feb 7, 2025 •

edited

Loading

sonarqubecloud bot commented Mar 5, 2025

olperr1 Mar 6, 2025

olperr1 Mar 6, 2025

olperr1 Mar 6, 2025

olperr1 Mar 6, 2025

olperr1 Mar 6, 2025

	"The topology kind of the export",
	"Force the topology kind for the export (disable automatic detection)",

		@@ -159,12 +159,25 @@ public ReferenceDataProvider getReferenceDataProvider() {
		}

		private CgmesTopologyKind networkTopologyKind(Network network) {

	* non-retained `Switch` are always written in the case of a `NODE_BREAKER` export, and never written in the case of a `BUS_BRANCH` export
	* Non-retained `Switch` are always written in the case of a `NODE_BREAKER` export, and never written in the case of a `BUS_BRANCH` export

	It is however possible to ignore the computed export topology kind and force it to be `NODE_BREAKER` or `BUS_BRANCH` by setting the parameter `iidm.export.cgmes.topology-kind`.
	It is however possible to ignore the computed export topology kind and force it to be `NODE_BREAKER` or `BUS_BRANCH` by setting the parameter [`iidm.export.cgmes.topology-kind`](#options).

CGMES export: Add a parameter to export as bus branch #3315

Are you sure you want to change the base?

CGMES export: Add a parameter to export as bus branch #3315

Conversation

rcourtier commented Feb 7, 2025 • edited Loading

sonarqubecloud bot commented Mar 5, 2025

Quality Gate passed

olperr1 Mar 6, 2025

Choose a reason for hiding this comment

olperr1 Mar 6, 2025

Choose a reason for hiding this comment

olperr1 Mar 6, 2025

Choose a reason for hiding this comment

olperr1 Mar 6, 2025

Choose a reason for hiding this comment

olperr1 Mar 6, 2025

Choose a reason for hiding this comment

rcourtier commented Feb 7, 2025 •

edited

Loading