Add flatten in export options (#3680)

Add flatten in export options (#3680)

* Add flatten in export options
* Avoid modifying the exported network

---------

Signed-off-by: BOUHOURS Antoine <antoine.bouhours@rte-france.com>

Author: antoinebhs

docs/grid_exchange_formats/iidm/export.md

@@ -58,6 +58,9 @@ Depending on object types the following sorting key has been chosen :
 
 By default, the network components are not sorted.
 
+**iidm.export.xml.flatten**<br>
+The `iidm.export.xml.flatten` property is an optional property that defines whether the XIIDM exporter will flatten the network by merging subnetworks into the main network during export. When set to `true`, all subnetworks are integrated into a single flat network structure in the generated XIIDM file. If the network contains no subnetworks, setting this property to `true` has no effect. Its default value is `false`.
+
 **iidm.export.xml.version**<br>
 The `iidm.export.xml.version` property is an optional property that defines the XIIDM version to use for the exported file. If the chosen version is not compatible with the network to write, an error occurs. This is typically the case when an attribute appeared in a version more recent than the target one, and its value is not the default one (importing back the file will lead to a different network). By default, the export is done in the more recent version that is supported.
 

iidm/iidm-serde/src/main/java/com/powsybl/iidm/serde/AbstractTreeDataExporter.java

@@ -116,6 +116,7 @@ public abstract class AbstractTreeDataExporter implements Exporter {
     public static final String EXTENSIONS_INCLUDED_LIST = "iidm.export.xml.included.extensions";
     public static final String EXTENSIONS_EXCLUDED_LIST = "iidm.export.xml.excluded.extensions";
     public static final String SORTED = "iidm.export.xml.sorted";
+    public static final String FLATTEN = "iidm.export.xml.flatten";
     public static final String VERSION = "iidm.export.xml.version";
     public static final String WITH_AUTOMATION_SYSTEMS = "iidm.export.xml.with-automation-systems";
     public static final String VOLTAGE_LEVELS_NODE_BREAKER = "iidm.export.xml.topology-level.voltage-levels.node-breaker";
@@ -142,6 +143,7 @@ public abstract class AbstractTreeDataExporter implements Exporter {
             "The list of extensions that will be excluded during export", null,
             EXTENSIONS_SUPPLIER.get().getProviders().stream().map(ExtensionProvider::getExtensionName).collect(Collectors.toList()));
     private static final Parameter SORTED_PARAMETER = new Parameter(SORTED, ParameterType.BOOLEAN, "Sort export output file", Boolean.FALSE);
+    private static final Parameter FLATTEN_PARAMETER = new Parameter(FLATTEN, ParameterType.BOOLEAN, "Flatten network containing subnetworks", Boolean.FALSE);
     private static final Parameter VERSION_PARAMETER = new Parameter(VERSION, ParameterType.STRING, "IIDM version in which files will be generated", IidmSerDeConstants.CURRENT_IIDM_VERSION.toString("."),
             Arrays.stream(IidmVersion.values()).map(v -> v.toString(".")).collect(Collectors.toList()));
     private static final Parameter WITH_AUTOMATION_SYSTEMS_PARAMETER = new Parameter(WITH_AUTOMATION_SYSTEMS, ParameterType.BOOLEAN,
@@ -156,7 +158,7 @@ public abstract class AbstractTreeDataExporter implements Exporter {
             ONLY_MAIN_CC_PARAMETER, ANONYMISED_PARAMETER, IIDM_VERSION_INCOMPATIBILITY_BEHAVIOR_PARAMETER,
             TOPOLOGY_LEVEL_PARAMETER, THROW_EXCEPTION_IF_EXTENSION_NOT_FOUND_PARAMETER, EXTENSIONS_INCLUDED_LIST_PARAMETER,
             EXTENSIONS_EXCLUDED_LIST_PARAMETER, SORTED_PARAMETER, VERSION_PARAMETER, WITH_AUTOMATION_SYSTEMS_PARAMETER,
-            VOLTAGE_LEVELS_NODEBREAKER_PARAMETER, VOLTAGE_LEVELS_BUSBREAKER_PARAMETER, VOLTAGE_LEVELS_BUSBRANCH_PARAMETER);
+            VOLTAGE_LEVELS_NODEBREAKER_PARAMETER, VOLTAGE_LEVELS_BUSBREAKER_PARAMETER, VOLTAGE_LEVELS_BUSBRANCH_PARAMETER, FLATTEN_PARAMETER);
     private final ParameterDefaultValueConfig defaultValueConfig;
 
     protected AbstractTreeDataExporter(PlatformConfig platformConfig) {
@@ -249,6 +251,7 @@ private ExportOptions createExportOptions(Properties parameters) {
                 .setTopologyLevel(TopologyLevel.valueOf(Parameter.readString(getFormat(), parameters, TOPOLOGY_LEVEL_PARAMETER, defaultValueConfig)))
                 .setThrowExceptionIfExtensionNotFound(Parameter.readBoolean(getFormat(), parameters, THROW_EXCEPTION_IF_EXTENSION_NOT_FOUND_PARAMETER, defaultValueConfig))
                 .setSorted(Parameter.readBoolean(getFormat(), parameters, SORTED_PARAMETER, defaultValueConfig))
+                .setFlatten(Parameter.readBoolean(getFormat(), parameters, FLATTEN_PARAMETER, defaultValueConfig))
                 .setVersion(Parameter.readString(getFormat(), parameters, VERSION_PARAMETER, defaultValueConfig))
                 .setFormat(getTreeDataFormat())
                 .setBusBranchVoltageLevelIncompatibilityBehavior(ExportOptions.BusBranchVoltageLevelIncompatibilityBehavior.valueOf(

iidm/iidm-serde/src/main/java/com/powsybl/iidm/serde/ExportOptions.java

@@ -49,6 +49,8 @@ public enum BusBranchVoltageLevelIncompatibilityBehavior {
 
     private BusBranchVoltageLevelIncompatibilityBehavior busBranchVoltageLevelIncompatibilityBehavior = BusBranchVoltageLevelIncompatibilityBehavior.THROW_EXCEPTION;
 
+    private boolean flatten = false;
+
     private String version;
 
     private IidmVersionIncompatibilityBehavior iidmVersionIncompatibilityBehavior = IidmVersionIncompatibilityBehavior.THROW_EXCEPTION;
@@ -93,6 +95,12 @@ public ExportOptions(boolean withBranchSV, boolean indent, boolean onlyMainCc, T
 
     public ExportOptions(boolean withBranchSV, boolean indent, boolean onlyMainCc, TopologyLevel topologyLevel, boolean throwExceptionIfExtensionNotFound, boolean sorted, String version,
                          IidmVersionIncompatibilityBehavior iidmVersionIncompatibilityBehavior) {
+        this(withBranchSV, indent, onlyMainCc, topologyLevel, throwExceptionIfExtensionNotFound, sorted, version, iidmVersionIncompatibilityBehavior, false);
+
+    }
+
+    public ExportOptions(boolean withBranchSV, boolean indent, boolean onlyMainCc, TopologyLevel topologyLevel, boolean throwExceptionIfExtensionNotFound, boolean sorted, String version,
+                         IidmVersionIncompatibilityBehavior iidmVersionIncompatibilityBehavior, boolean flatten) {
         this.withBranchSV = withBranchSV;
         this.indent = indent;
         this.onlyMainCc = onlyMainCc;
@@ -101,6 +109,7 @@ public ExportOptions(boolean withBranchSV, boolean indent, boolean onlyMainCc, T
         this.sorted = sorted;
         this.version = version;
         this.iidmVersionIncompatibilityBehavior = Objects.requireNonNull(iidmVersionIncompatibilityBehavior);
+        this.flatten = flatten;
     }
 
     public boolean isWithBranchSV() {
@@ -258,4 +267,13 @@ public ExportOptions setWithAutomationSystems(boolean withAutomationSystems) {
         this.withAutomationSystems = withAutomationSystems;
         return this;
     }
+
+    public boolean isFlatten() {
+        return flatten;
+    }
+
+    public ExportOptions setFlatten(boolean flatten) {
+        this.flatten = flatten;
+        return this;
+    }
 }

iidm/iidm-serde/src/main/java/com/powsybl/iidm/serde/NetworkSerDe.java

@@ -369,7 +369,9 @@ private static void writeBaseNetwork(Network n, NetworkSerializerContext context
         AliasesSerDe.write(n, NETWORK_ROOT_ELEMENT_NAME, context);
         PropertiesSerDe.write(n, context);
 
-        IidmSerDeUtil.runFromMinimumVersion(IidmVersion.V_1_11, context, () -> writeSubnetworks(n, context, extensionsSupplier));
+        if (supportSubnetworksExport(context)) {
+            writeSubnetworks(n, context, extensionsSupplier);
+        }
 
         writeDcDetailed(n, context);
         writeVoltageLevels(n, context);
@@ -569,7 +571,7 @@ private static boolean isElementWrittenInsideNetwork(Identifiable<?> element, Ne
     }
 
     private static boolean supportSubnetworksExport(NetworkSerializerContext context) {
-        return context.getVersion().compareTo(IidmVersion.V_1_11) >= 0;
+        return context.getVersion().compareTo(IidmVersion.V_1_11) >= 0 && !context.getOptions().isFlatten();
     }
 
     private static NetworkSerializerContext createContext(Network n, ExportOptions options, TreeDataWriter writer) {

iidm/iidm-serde/src/test/java/com/powsybl/iidm/serde/ExportOptionsTest.java

@@ -105,6 +105,7 @@ void defaultExportOptionsTest() {
         testDefaultExportOptions(new ExportOptions(Boolean.TRUE, Boolean.TRUE, Boolean.FALSE, TopologyLevel.NODE_BREAKER, Boolean.FALSE, null));
         testDefaultExportOptions(new ExportOptions(Boolean.TRUE, Boolean.TRUE, Boolean.FALSE, TopologyLevel.NODE_BREAKER, Boolean.FALSE, Boolean.FALSE, null));
         testDefaultExportOptions(new ExportOptions(Boolean.TRUE, Boolean.TRUE, Boolean.FALSE, TopologyLevel.NODE_BREAKER, Boolean.FALSE, Boolean.FALSE, null, THROW_EXCEPTION));
+        testDefaultExportOptions(new ExportOptions(Boolean.TRUE, Boolean.TRUE, Boolean.FALSE, TopologyLevel.NODE_BREAKER, Boolean.FALSE, Boolean.FALSE, null, THROW_EXCEPTION, Boolean.FALSE));
     }
 
     private void testDefaultExportOptions(ExportOptions options) {
@@ -119,6 +120,7 @@ private void testDefaultExportOptions(ExportOptions options) {
         assertEquals(THROW_EXCEPTION, options.getIidmVersionIncompatibilityBehavior());
         assertEquals(StandardCharsets.UTF_8, options.getCharset());
         assertEquals(Boolean.TRUE, options.isWithAutomationSystems());
+        assertEquals(Boolean.FALSE, options.isFlatten());
     }
 
 }

iidm/iidm-serde/src/test/java/com/powsybl/iidm/serde/NetworkSerDeTest.java

@@ -358,4 +358,34 @@ void emptySourceFormatTest() {
             assertEquals("", readNetwork.getSourceFormat());
         });
     }
+
+    @Test
+    void testExportWithFlatten() {
+        Network n1 = createNetwork(1);
+        Network n2 = createNetwork(2);
+        Path xmlFile = tmpDir.resolve("flattenedNetwork.xml");
+
+        Network merged = Network.merge("Merged", n1, n2);
+
+        ExportOptions options = new ExportOptions().setFlatten(true);
+        NetworkSerDe.write(merged, options, xmlFile);
+        Network readNetwork = NetworkSerDe.validateAndRead(xmlFile);
+        assertEquals(2, merged.getSubnetworks().size());
+        assertEquals(0, readNetwork.getSubnetworks().size());
+    }
+
+    @Test
+    void testExportWithoutFlatten() {
+        Network n1 = createNetwork(1);
+        Network n2 = createNetwork(2);
+        Path xmlFile = tmpDir.resolve("networkWithSubnetworks.xml");
+
+        Network merged = Network.merge("Merged", n1, n2);
+
+        ExportOptions options = new ExportOptions();
+        NetworkSerDe.write(merged, options, xmlFile);
+        Network readNetwork = NetworkSerDe.validateAndRead(xmlFile);
+        assertEquals(2, merged.getSubnetworks().size());
+        assertEquals(2, readNetwork.getSubnetworks().size());
+    }
 }

iidm/iidm-serde/src/test/java/com/powsybl/iidm/serde/XMLExporterTest.java

@@ -91,7 +91,7 @@ void exportXiidmWithAnotherPrefixTest() throws IOException {
     @Test
     void paramsTest() {
         var xmlExporter = new XMLExporter();
-        assertEquals(15, xmlExporter.getParameters().size());
+        assertEquals(16, xmlExporter.getParameters().size());
         assertEquals("IIDM XML v" + CURRENT_IIDM_VERSION.toString(".") + " exporter", xmlExporter.getComment());
     }