Export#

There are two main use-cases supported:

  • Export IGM (Individual Grid Model) instance files. There is a single network and a unique CGMES modeling authority.

  • Export CGM (Common Grid Model) instance files. A network composed of multiple subnetworks, where each subnetwork is an IGM.

In both cases, the metadata model information in the exported files is built from metadata information read from the input files and stored in IIDM or received through parameters. Information received through parameters takes precedence over information available from original metadata models.

For a quick CGM export, the user may rely on the parameter iidm.export.cgmes.cgm_export to write in a single export multiple updated SSH files (one for each IGM) and a single SV for the whole common grid model. Specifics about this option are explained in the section below. If you need complete control over the exported files in a CGM scenario, you may prefer to iterate through the subnetworks and make multiple calls to the export function. This is described in detail in the section below.

Please note that when exporting equipment, PowSyBl always uses the CGMES node/breaker level of detail, without considering the topology level of the PowSyBl network.

The user can specify the profiles to be exported using the parameter iidm.export.cgmes.profiles. The list of currently supported export instance files are: EQ, SSH, SV, TP.

If the IIDM network has at least one voltage level with node/breaker topology level, and the SSH or SV is requested in the export, and the TP is not requested, an error will be logged, as there could be missing references in the SSH, SV files to Topological Nodes calculated automatically by IIDM that are not present in the output.

If the dependencies have to be updated automatically (see parameter iidm.export.cgmes.update-dependencies below), the exported instance files will contain metadata models where:

  • TP and SSH depend on EQ.

  • SV depends on TP and SSH.

  • EQ depends on EQ_BD (if present). EQ_BD is the profile for the boundary equipment definitions.

  • SV depends on TP_BD (if present). TP_BD is the profile for the boundary topology. Only for CGMES 2.4.

The output filenames will follow the pattern <baseName>_<profile>.xml. The basename is determined from the parameters, or the basename of the export data source or the main network name.

CGM (Common Grid Model) quick export#

When exporting a CGM, we need an IIDM network (CGM) that contains multiple subnetworks (one for each IGM). Only the CGMES instance files corresponding to SSH and SV profiles are exported: an updated SSH file for every subnetwork (for every IGM) and a single SV file for the main network that represents the CGM.

When exporting, it is verified that the main network and all subnetworks have the same scenario time (network case date). If they are different, an error is logged.

If a version number is given as a parameter, it is used for the exported files. If not, the versions of the input CGM SV and IGM SSHs are obtained from their metadata, and their maximum value calculated. The output version is then set to 1 + this maximum value.

The quick CGM export will always write updated SSH files for IGMs and a single SV for the CGM. The parameter for selecting which profiles to export is ignored in this kind of export.

If the dependencies have to be updated automatically (see parameter iidm.export.cgmes.update-dependencies below), the exported instance files will contain metadata models where:

  • Updated SSH for IGMs supersede the original ones, and depend on the original EQ from IGMs.

  • Updated SV for the CGM depends on the updated SSH from IGMs and on the original TP and TP_BD from IGMs.

The filenames of the exported instance files will follow the pattern:

  • For the CGM SV: <basename>_SV.xml.

  • For the IGM SSHs: <basename>_<IGM name>_SSH.xml. The IGM name is built from the country code of the first substation or the IIDM name if no country is present.

The basename is determined from the parameters, or the basename of the export data source or the main network name.

As an example, you can export one of the test configurations that have been provided by ENTSO-E. It is available in the cgmes-conformity module of the powsybl-core repository. If you run the following code:

Network cgmNetwork = Network.read(CgmesConformity1Catalog.microGridBaseCaseAssembled().dataSource());

Properties exportParams = new Properties();
exportParams.put(CgmesExport.EXPORT_BOUNDARY_POWER_FLOWS, true);
exportParams.put(CgmesExport.NAMING_STRATEGY, "cgmes");
exportParams.put(CgmesExport.CGM_EXPORT, true);
exportParams.put(CgmesExport.UPDATE_DEPENDENCIES, true);
exportParams.put(CgmesExport.MODELING_AUTHORITY_SET, "MAS1");

cgmNetwork.write("CGMES", exportParams, new FileDataSource(Path.of("/exampleFolder"), "exampleBase"));

You will obtain the following files in your exampleFolder:

exampleBase_BE_SSH.xml
exampleBase_NL_SSH.xml
exampleBase_SV.xml

where the updated SSH files will supersede the original ones and depend on the original EQs, and the SV will contain the correct dependencies of new SSH and original TPs and TP_BD.

CGM (Common Grid Model) manual export#

If you want to intervene in how the updated IGM SSH files or the CGM SV are exported, you can make multiple calls to the CGMES export function.

You can use the following code for reference:

Network cgmNetwork = Network.read(CgmesConformity1Catalog.microGridBaseCaseAssembled().dataSource());

// We decide which version we want to export
int exportedVersion = 18;

// Common export parameters
Properties exportParams = new Properties();
exportParams.put(CgmesExport.EXPORT_BOUNDARY_POWER_FLOWS, true);
exportParams.put(CgmesExport.NAMING_STRATEGY, "cgmes");
// We do not want a quick CGM export
exportParams.put(CgmesExport.CGM_EXPORT, false);
exportParams.put(CgmesExport.UPDATE_DEPENDENCIES, false);

Path outputPath = Path.of("/manualExampleFolder");
String basename = "manualExampleBasename";

// For each subnetwork, prepare the metadata for SSH and export it
for (Network n : cgmNetwork.getSubnetworks()) {
    String country = n.getSubstations().iterator().next().getCountry().orElseThrow().toString();
    CgmesMetadataModel sshModel = n.getExtension(CgmesMetadataModels.class).getModelForSubset(CgmesSubset.STEADY_STATE_HYPOTHESIS).orElseThrow();
        sshModel.clearDependencies()
                .addDependentOn("myDependency")
                .addSupersedes("mySupersede")
                .setVersion(exportedVersion)
                .setModelingAuthoritySet("myModellingAuthority");
        exportParams.put(CgmesExport.PROFILES, List.of("SSH"));
    n.write("CGMES", exportParams, new FileDataSource(outputPath, basename + "_" + country));
}

// In the main network, CREATE the metadata for SV and export it
cgmNetwork.newExtension(CgmesMetadataModelsAdder.class)
    .newModel()
        .setSubset(CgmesSubset.STATE_VARIABLES)
        .addProfile("http://entsoe.eu/CIM/StateVariables/4/1")
        .setId("mySvId")
        .setVersion(exportedVersion)
        .setModelingAuthoritySet("myModellinAuthority")
        .addDependentOn("mySvDependency1")
        .addDependentOn("mySvDependency2")
    .add()
    .add();
exportParams.put(CgmesExport.PROFILES, List.of("SV"));
cgmNetwork.write("CGMES", exportParams, new FileDataSource(outputPath, basename));

The file manualExampleBasename_BE_SSH.xml inside /manualExampleFolder will have the following contents for the metadata:

...
<md:Model.description>CGMES Conformity Assessment ...</md:Model.description>
<md:Model.version>18</md:Model.version>
<md:Model.DependentOn rdf:resource="myDependency"/>
<md:Model.Supersedes rdf:resource="mySupersede"/>
<md:Model.profile>http://entsoe.eu/CIM/SteadyStateHypothesis/1/1</md:Model.profile>
<md:Model.modelingAuthoritySet>myModellingAuthority</md:Model.modelingAuthoritySet>
...

And the file manualExampleBasename_SV.xml will contain:

...
<md:Model.version>18</md:Model.version>
<md:Model.DependentOn rdf:resource="mySvDependency1"/>
<md:Model.DependentOn rdf:resource="mySvDependency2"/>
<md:Model.profile>http://entsoe.eu/CIM/StateVariables/4/1</md:Model.profile>
<md:Model.modelingAuthoritySet>myModelingAuthority</md:Model.modelingAuthoritySet>
...

Remember that, in addition to setting the info for metadata models in the IIDM extensions, you could also rely on parameters passed to the export methods.

Conversion from PowSyBl grid model to CGMES#

The following sections describe in detail how each supported PowSyBl network model object is converted to CGMES network components.

Battery#

PowSyBl Battery is exported as SynchronousMachine with HydroGeneratingUnit.

TODO details

BusbarSection#

PowSyBl BusbarSection is exported as CGMES BusbarSection.

TODO details

DanglingLine#

PowSyBl DanglingLine is exported as several CGMES network objects. Each dangling line will be exported as one EquivalentInjection and one ACLineSegment.

TODO details

Generator#

PowSyBl Generator is exported as CGMES SynchronousMachine.

Regulating control#

If the network comes from a CIM-CGMES model and a generator initially has a RegulatingControl, it will still have one at export. Otherwise, a RegulatingControl is always exported for generators, except if it has no regulating capabilities because \(minQ = maxQ\).

A RegulatingControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.reactivePower when a generator has the extension RemoteReactivePowerControl with the enabled activated and the generator attribute voltageRegulatorOn set to false. In all other cases, a RegulatingControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.voltage.

HVDC line and HVDC converter stations#

A PowSyBl HVDCLine and its two HVDCConverterStations are exported as a DCLineSegment with two DCConverterUnits.

TODO details

Line#

PowSyBl Line is exported as ACLineSegment.

TODO details

Load#

PowSyBl Load is exported as ConformLoad, NonConformLoad or EnergyConsumer depending on the extension LoadDetail.

TODO details

Shunt compensator#

PowSyBl ShuntCompensator is exported as LinearShuntCompensator or NonlinearShuntCompensator depending on their models.

Regulating control#

If the network comes from a CIM-CGMES model and a shunt compensator initially has a RegulatingControl, it will still have one at export.

A shunt compensator with local voltage control (i.e., the regulating terminal is the same of the terminal of connection) and no valid voltage target will not have any exported regulating control. In all other cases, a RegulatingControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.voltage.

StaticVarCompensator#

PowSyBl StaticVarCompensator is exported as StaticVarCompensator.

Regulating control#

If the network comes from a CIM-CGMES model and a static VAR compensator initially has a RegulatingControl, it will still have one at export.

A static VAR compensator which voltage control is local (i.e., the regulating terminal is the same of the terminal of connection) and no valid voltage or reactive power target will not have any exported regulating control.

A RegulatingControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.reactivePower when the static VAR compensator mode is REACTIVE_POWER. A RegulatingControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.voltage when the static VAR compensator mode is VOLTAGE. When the static VAR compensator is OFF, the exported regulating control mode will be reactive power only if the voltage target is not valid but the reactive power target is. Otherwise, the exported mode will be voltage.

Substation#

PowSyBl Substation is exported as Substation.

TODO details

Switch#

PowSyBl Switch is exported as CGMES Breaker, Disconnector or LoadBreakSwitch depending on its SwitchKind.

TODO details

ThreeWindingsTransformer#

PowSyBl ThreeWindingsTransformer is exported as PowerTransformer with three PowerTransformerEnds.

Tap changer control#

If the network comes from a CIM-CGMES model and the tap changer has initially a TapChangerControl, it always has at export too. Otherwise, a TapChangerControl is exported for the tap changer if it is considered as defined. A RatioTapChanger is considered as defined if it has a valid regulation value, a valid target deadband and a non-null regulating terminal. A PhaseTapChanger is considered as defined if it has a regulation mode different of FIXED_TAP, a valid regulation value, a valid target deadband, and a non-null regulating terminal.

In a RatioTapChanger, the TapChangerControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.reactivePower when RatioTapChanger regulationMode is set to REACTIVE_POWER, and with RegulatingControl.mode set to RegulatingControlModeKind.voltage when RatioTapChanger regulationMode is set to VOLTAGE.

In a PhaseTapChanger, the TapChangerControl is exported with RegulatingControl.mode set to RegulatingControlModeKind.activePower when PhaseTapChanger regulationMode is set to ACTIVE_POWER_CONTROL, and with RegulatingControl.mode set to RegulatingControlModeKind.currentFlow when PhaseTapChanger regulationMode is set to CURRENT_LIMITER.

TwoWindingsTransformer#

PowSyBl TwoWindingsTransformer is exported as PowerTransformer with two PowerTransformerEnds.

Tap changer controls for two-winding transformers are exported following the same rules explained in the previous section about three-winding transformers. See tap changer control.

Voltage level#

PowSyBl VoltageLevel is exported as VoltageLevel.

TODO details

Extensions#

Control areas#

PowSyBl ControlAreas are exported as several ControlArea.

TODO details

Options#

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

Note that if you are exporting a network that does not come from CGMES, you can use the iidm.import.cgmes.boundary-location property to define the location of the boundary files to use as reference.

iidm.export.cgmes.base-name
Optional property that defines the base name of the exported files. Exported CGMES files’ names will look like this:

<base_name>_EQ.xml
<base_name>_TP.xml
<base_name>_SSH.xml
<base_name>_SV.xml

By default, the base name is the network’s name if it exists, or else the network’s ID.

iidm.export.cgmes.boundary-eq-id
Optional property that defines the ID of the EQ-BD model if there is any. Its default value is null: we consider there is no EQ-BD model to consider. If this property is defined, then this ID will be written in the header of the exported EQ file.

iidm.export.cgmes.boundary-tp-id
Optional property that defines the ID of the TP-BD model if there is any. Its default value is null: we consider there is no TP-BD model to consider. If this property is defined, then this ID will be written in the header of the exported SV file.

iidm.export.cgmes.cim-version
Optional property that defines the CIM version number in which the user wants the CGMES files to be exported. CIM versions 14, 16 and 100 are supported i.e. its valid values are 14, 16 and 100. If not defined, and the network has the extension CimCharacteristics, the CIM version will be the one indicated in the extension. If not, its default value is 16. CIM version 16 corresponds to CGMES 2.4.15. CIM version 100 corresponds to CGMES 3.0.

iidm.export.cgmes.encode-ids
Optional property that must be used if IIDM IDs that are not compliant with CGMES requirements are to be used as CGMES IDs. true by default. Used for debugging purposes.

iidm.export.cgmes.export-boundary-power-flows
Optional property that defines if power flows at boundary nodes are to be exported in the SV file or not. true by default.

iidm.export.cgmes.export-power-flows-for-switches
Optional property that defines if power flows of switches are exported in the SV file. true by default.

idm.export.cgmes.naming-strategy
Optional property that defines which naming strategy is used to transform IIDM identifiers to CGMES identifiers. It can be:

  • identity: CGMES IDs are the same as IIDM IDs.

  • cgmes: new CGMES IDs (new master resource identifiers, cim:mRID) are created for IIDM Identifiables if the IIDM IDs are not compliant with CGMES requirements.

  • cgmes-fix-all-invalid-ids: ensures that all CGMES IDs in the export will comply with CGMES requirements, for IIDM Identifiablesand also for its related objects (tap changers, operational limits, regulating controls, reactive capability outputVariables, …). Its default value is identity.

iidm.export.cgmes.uuid-namespace
Optional property related to the naming strategy specified in iidm.export.cgmes.naming-strategy. When new CGMES IDs have to be generated, a mechanism that ensures creation of new, stable identifiers based on IIDM IDs is used (see RFC 4122). These new IDs are guaranteed to be unique inside a namespace given by this UUID. By default, it is the name-based UUID fo the text “powsybl.org” in the empty namespace.

iidm.export.cgmes.profiles
Optional property that determines which instance files will be exported. By default, it is a full CGMES export: the instance files for the profiles EQ, TP, SSH and SV are exported.

iidm.export.cgmes.modeling-authority-set
Optional property allowing to write a custom modeling authority set in the exported file headers. powsybl.org by default. If a Boundary set is given with the property iidm.import.cgmes.boundary-location and the network sourcing actor is found inside it, then the modeling authority set will be obtained from the boundary file without the need to set this property. The sourcing actor can be specified using the parameter iidm.export.cgmes.sourcing-actor.

iidm.export.cgmes.model-description
Optional property allowing to write a custom model description in the file headers. By default, the model description is EQ model for the EQ file, TP model for the TP file, SSH model for the SSH file and SV model for the SV file.

iidm.export.cgmes.export-transformers-with-highest-voltage-at-end1
Optional property defining whether the transformers should be exported with the highest voltage at end 1, even if it might not be the case in the IIDM model. This property is set to false by default.

iidm.export.cgmes.export-load-flow-status
Optional property that indicates whether the load flow status (converged or diverged) should be written for the TopologicalIslands in the SV file. If true, the status will be computed by checking, for every bus, if the voltage and angle are valid, and if the bus is respecting Kirchhoff’s first law. For the latter, we check that the sums of active power and reactive power at the bus are higher than a threshold defined by the properties iidm.export.cgmes.max-p-mismatch-converged and iidm.export.cgmes.max-q-mismatch-converged. This property is set to true by default.

iidm.export.cgmes.export-all-limits-group Optional property that defines whether all OperationalLimitsGroup should be exported, or only the selected (active) ones. This property is set to true by default, which means all groups are exported (not only the active ones).

iidm.export.cgmes.export-generators-in-local-regulation-mode Optional property that allows to export voltage regulating generators in local regulation mode. This doesn’t concern reactive power regulating generators. If set to true, the generator’s regulating terminal is set to the generator’s own terminal and the target voltage is rescaled accordingly. This property is set to false by default.

iidm.export.cgmes.max-p-mismatch-converged
Optional property that defines the threshold below which a bus is considered to be balanced for the load flow status of the TopologicalIsland in active power. If the sum of all the active power of the terminals connected to the bus is greater than this threshold, then the load flow is considered to be divergent. Its default value is 0.1, and it should be used only if the iidm.export.cgmes.export-load-flow-status property is set to true.

iidm.export.cgmes.max-q-mismatch-converged
Optional property that defines the threshold below which a bus is considered to be balanced for the load flow status of the TopologicalIsland in reactive power. If the sum of all the reactive power of the terminals connected to the bus is greater than this threshold, then the load flow is considered to be divergent. Its default value is 0.1, and it should be used only if the iidm.export.cgmes.export-load-flow-status property is set to true.

iidm.export.cgmes.export-sv-injections-for-slacks
Optional property to specify if the total mismatch left after power flow calculation at IIDM slack buses should be exported as an SvInjection. This property is set to true by default.

iidm.export.cgmes.sourcing-actor
Optional property allowing to specify a custom sourcing actor. If a Boundary set with reference data is provided for the export through the parameter iidm.import.cgmes.boundary-location, the value of this property will be used to look for the modeling authority set and the geographical region to be used in the export. No default value is given. If this property is not given, the export process will still try to determine the sourcing actor from the IIDM network if it only contains one country.

iidm.export.cgmes.model-version
Optional property defining the version of the exported CGMES file. It will be used if the version is not already available in the network. The version will be written in the header of each exported file and will also be used to generate a unique UUID for the FullModel field. Its default value is 1.

iidm.export.cgmes.business-process
The business process in which the export takes place. This is used to generate unique UUIDs for the EQ, TP, SSH and SV file FullModel. Its default value is 1D.

iidm.export.cgmes.cgm_export Optional property to specify the export use-case: IGM (Individual Grid Model) or CGM (Common Grid Model). To export instance files of a CGM, set the value to True. The default value is False to export network as an IGM.

iidm.export.cgmes.update-dependencies Optional property to determine if dependencies in the exported instance files should be managed automatically. The default value is True.