Export

Networks can be exported in three IIDM formats:

  • XML: “XIIDM”

  • JSON: “JIIDM”

  • binary: “BIIDM”

Exporting with default values

To export a network using the default parameters, use:

Network n = ...;
String FORMAT = "XIIDM"; // or "BIIDM" or "JIIDM"
n.write(FORMAT, new Properties(), Path.of("/path/to/output.format"));

Exporting with custom properties

You can configure your export either with ExportOptions or with Properties.

From ExportOptions

Network n = ...;
ExportOptions options = new ExportOptions();
options.setVersion("1.13");
options.setFormat(TreeDataFormat.BIN); // or XML or JSON
NetworkSerDe.write(n, options, Path.of("/tmp/test.biidm"));

From config file

Network n = ...;
Properties prop = new Properties();
prop.load(new FileInputStream("/path/to/powsybl_config.yaml"));
String FORMAT = "XIIDM"; // or "BIIDM" or "JIIDM"
n.write(FORMAT, prop, Path.of("/path/to/output.format"));

With the config file containing at least:

import-export-parameters-default-value:
  iidm.export.xml.version: 1.12

This configuration allows to export to IIDM v1.12. Note that the parameter includes “xml” in the name, but it can be used for any IIDM format (including JIIDM and BIIDM). For more information about the config file, see import-export-parameters-default-value module, or the options below.

Options

These properties can be defined in the configuration file in the import-export-parameters-default-value module.

iidm.export.xml.indent
The iidm.export.xml.indent property is an optional property that defines whether the XIIDM file generated by the XIIDM exporter will be indented.

By default, the value is true.

iidm.export.xml.with-branch-state-variables
The iidm.export.xml.with-branch-state-variables property is an optional property that defines whether the network will be exported by the XIIDM exporter with branch state variables.

By default, the value is true.

iidm.export.xml.only-main-cc
The iidm.export.xml.only-main-cc property is an optional property that defines whether the XIIDM exporter should only export the main connected component of the network.

By default, the value is false.

iidm.export.xml.anonymised
The iidm.export.xml.anonymised property is an optional property that defines whether the XIIDM exporter anonymizes all equipment in the generated file.

By default, the value is false.

iidm.export.xml.topology-level
The iidm.export.xml.topology-level property is an optional property that defines the most detailed topology in which the XIIDM exporter can export the network. The topology level can be:

  • NODE_BREAKER: the voltage levels are exported using the Node/Breaker view. Voltage levels described in Bus/Breaker topology are exported using the Bus/Breaker view.

  • BUS_BREAKER: all voltage levels are all exported using the Bus/Breaker view

  • BUS_BRANCH: all voltage levels are exported using the Bus view

The default value is NODE_BREAKER to export all voltage levels in the same level of details than the one they are described.

iidm.export.xml.topology-level.voltage-levels.node-breaker
The iidm.export.xml.topology-level.voltage-levels.node-breaker property is an optional property that defines a list of voltage level IDs to be exported using the Node/Breaker view by the IIDM exporter. Note: if the voltage level is described using a lower detailed topology (Bus/Breaker or Bus/Branch), it will be exported using the Bus/Breaker (or Bus/Branch) view (Node/Breaker is not possible since the voltage level has not enough details).

iidm.export.xml.topology-level.voltage-levels.bus-breaker
The iidm.export.xml.topology-level.voltage-levels.bus-breaker property is an optional property that defines a list of voltage level IDs to be exported using the Bus/Breaker view by the IIDM exporter.

iidm.export.xml.topology-level.voltage-levels.bus-branch
The iidm.export.xml.topology-level.voltage-levels.bus-branch property is an optional property that defines a list of voltage level IDs to be exported using the Bus/Branch view by the IIDM exporter.

iidm.export.xml.throw-exception-if-extension-not-found
The iidm.export.xml.throw-exception-if-extension-not-found property is an optional property that defines whether the XIIDM exporter throws an exception if the network contains an unknown or unserializable extension or if it just ignores it.

By default, the value is false.

iidm.export.xml.included.extensions
The iidm.export.xml.included.extensions property is an optional property that defines the list of extensions that we will be exported by the XIIDM exporter. If set to an empty string, all extensions will be ignored during the export.

By default, all extensions will be exported.

iidm.export.xml.excluded.extensions
The iidm.export.xml.excluded.extensions property is an optional property that defines the list of extensions that will not be exported by the XIIDM exporter. When both iidm.export.xml.included.extensions and iidm.export.xml.excluded.extensions are defined a configuration exception is thrown.

By default, no extension is excluded from the export.

iidm.export.xml.sorted
The iidm.export.xml.sorted property is an optional property that defines whether the XIIDM file generated by the XIIDM exporter will be sorted or not for some objects. Depending on object types the following sorting key has been chosen :

  • the id for identifiables

  • the name for extensions

  • the name for temporary limits

  • node1 then node2 for internal connections

  • the name for properties of an identifiable

By default, the network components are not sorted.

iidm.export.xml.flatten
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
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.export.xml.with-automation-systems
The iidm.export.xml.with-automation-systems property is an optional property that defines if the automation systems are exported.

By default, the value is true, automation systems are exported.

iidm.export.xml.iidm-version-incompatibility-behavior
The iidm.export.xml.iidm-version-incompatibility-behavior property is an optional property that defines the behavior of the XIIDM exporter when there is a version incompatibility between the IIDM network and the XIIDM version in which the export is done. There are two possible behaviors:

  • LOG_ERROR: an error is logged when there is a version incompatibility

  • THROW_EXCEPTION: an exception is thrown when there is a version incompatibility

By default, this behavior is set as THROW_EXCEPTION

iidm.export.xml.bus-branch.voltage-level.incompatibility-behavior
The iidm.export.xml.bus-branch.voltage-level.incompatibility-behavior property is an optional property that defines the behavior of the XIIDM exporter when exporting a network in BUS_BRANCH topology with a voltage level that will be invalid due to a reference to a non-exported bus. There are two possible behaviors:

  • KEEP_ORIGINAL_TOPOLOGY: the problematic voltage level is exported keeping the original topology and a warning is logged

  • THROW_EXCEPTION: an exception is thrown when trying to export a network in BUS_BRANCH topology, and a problematic voltage level is detected.

By default, this behavior is set as THROW_EXCEPTION

iidm.export.xml.force-export-network-with-beta-features
The iidm.export.xml.force-export-network-with-beta-features property is an optional property that defines the behavior of the IIDM exporter when exporting a network containing beta features that do not have a serialization support yet. There are two possible behaviors:

  • false, if the exporter encounters a beta element that cannot be serialized, the export will immediately stop and throw an error.

  • true, the export will skip beta elements that cannot be serialized. Be aware that this might result in an unreadable network.

By default, this is set to false.

Removed properties

iidm.export.xml.export-mode
The iidm.export.xml.export-mode property is an optional property that defines the export mode of the XIIDM exporter. The export mode can be:

  • UNIQUE_FILE: Exports the network and its extensions in a unique file.

  • EXTENSIONS_IN_ONE_SEPARATED_FILE: Exports the network to a file and the extensions to another file. In this mode, if the network file name is network.xiidm, the extension file name must be network-ext.xiidm.

  • ONE_SEPARATED_FILE_PER_EXTENSION_TYPE: Exports the network to a file and each extension type to a separate file. In this mode, if the network file name is network.xiidm, each extension file name must be network-extensionName.xiidm. Example: if our network has two extensions loadFoo and loadBar, then the network will be exported to the network.xiidm file and loadFoo and loadBar will be exported respectively to network-loadFoo.xiidm and network-loadBar.xiidm.

The default value for this parameter is IidmImportExportMode.NO_SEPARATED_FILE_FOR_EXTENSIONS. This property has been removed in v3.3.0.

iidm.export.xml.skip-extensions
The iidm.export.xml.skip-extensions property is an optional property that defines whether the XIIDM exporter skips exporting the network extensions or not. Its default value is false.

This property has been deprecated since v2.4.0 before being removed in v3.3.0. Set the iidm.export.xml.extensions to an empty string instead.