Fix BUS_BRANCH export failure with keepOriginalTopology

[cphili]

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)
• A PR or issue has been opened in all impacted repositories (if any)

Does this PR already have an issue describing the problem?
#3851

What kind of change does this PR introduce?
Bug fix

What is the current behavior?
When exporting a network in IIDM format with BUS_BRANCH topology level and BUS_BRANCH_VOLTAGE_LEVEL_INCOMPATIBILITY_BEHAVIOR = KEEP_ORIGINAL_TOPOLOGY,
the export may fail in some cases where the chosen topology leads to an invalid IIDM configuration. In particular, when a voltage level originally in NODE_BREAKER topology is exported in BUS_BRANCH, some terminal references may become invalid (e.g. referencing elements that are not representable in BUS_BRANCH), leading to a runtime exception during serialization.

What is the new behavior (if this is a feature change)?
The export logic now consistently relies on checkVoltageLevelExportTopology to detect invalid BUS_BRANCH configurations. When such an incompatibility is detected:
If the behavior is THROW_EXCEPTION, an exception is still thrown
If the behavior is KEEP_ORIGINAL_TOPOLOGY, the export automatically falls back to the original topology (typically NODE_BREAKER)

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

• Yes
• No

What changes might users need to make in their application due to this PR? (migration steps)
None. The change is backward-compatible and only affects cases that previously resulted in invalid exports or runtime exceptions.

Other information:

[olperr1]

These tests succeed also directly on main (without the TopologyLevelUtil changes). Therefore none of them covers the new case.

[olperr1]

This is not the right place to add your new check. It should be added to checkVoltageLevelExportTopology.

You can change the first condition of this method to look like:

if (topologyLevel == TopologyLevel.BUS_BRANCH && nodeBreakerWithBusBarSection(vl)) {

With

private static boolean withNullConnectableBus(VoltageLevel vl) {
    return vl.getConnectableStream()
        .map(Connectable::getTerminals)
        .flatMap(List<Terminal>::stream)
        .anyMatch(t -> t.getBusView().getConnectableBus() == null);
    }

Then you can update it with your additional condition:

if (topologyLevel == TopologyLevel.BUS_BRANCH
    && (nodeBreakerWithBusBarSection(vl) || requiresNodeBreakerExport(vl)) {

[cphili]

The issue cannot be easily fixed in TopologyLevelUtil, since the error (a terminalRef linked to a busbar) cannot be detected at that stage. To properly fall back to exporting the original topology (NODE_BREAKER), these cases would need to be identified before serialization through a network pre-processing step, which adds complexity.
As an alternative, we can ensure that the export process does not fail, even if such inconsistencies are present.

[olperr1]

The alternative is not viable: the export does not fail, but the exported file cannot be imported.

[olperr1]

This is not a suitable name. There are other cases when we need to export in node/breaker.

[olperr1]

The exception mentioned by the issue indicates that there's a terminalRef pointing to a busbar section.
If the VL is in node/breaker and has busbar section but no terminalRef pointing to them, the export is possible in bus/branch.

For instance, fictitiousSwitchRef.xml has a VL in node/breaker with a busbar section (vl="C", busbarSection="D") and can be exported in bus/branch (see fictitiousSwitchRef-bbr.xml). Since no terminalRef references "D", there's no problem.

[olperr1]

Note that the example is covered by the testConversion() unit test (by last line of testConversion(Network network)).
With this PR current code, the test succeed because the behavior is not set to KEEP_ORIGINAL_TOPOLOGY, then else branch is executed. since no error was detected with the previous check, the VL is exported in bus/branch as expected by the unit test.
This demonstrates that requiresNodeBreakerExport(VoltageLevel vl) detects as problematic situations that are not.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[olperr1]

I have not tested it, but I think you can simply check if there is at least one busbar section referenced with this method:

    private static boolean isBusbarTerminalRefIssue(VoltageLevel vl) {
        if (vl.getTopologyKind() != TopologyKind.NODE_BREAKER) {
            return false;
        }
        return vl.getNodeBreakerView().getBusbarSectionStream()
                .anyMatch(bbs -> !bbs.getTerminal().getReferrers().isEmpty());
    }

Note that it would be better to have a more descriptive name for the method. Maybe something like "hasReferencedBusbarSections"?

[cphili]

Thanks for the suggestion.
I tried this approach and added a test, but it fails: getReferrers() is still empty in this scenario.
This seems to indicate that the terminalRef relationships are not populated yet and this method cannot reliably detect the issue at this stage.