From cba96a88aeb1bd856e700f11c0eca586bbbfcd5a Mon Sep 17 00:00:00 2001 From: Romain Courtier Date: Tue, 18 Feb 2025 17:14:33 +0100 Subject: [PATCH] Update documentation Signed-off-by: Romain Courtier --- docs/grid_exchange_formats/cgmes/export.md | 52 ++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md index 8178b8e6caa..6a90bc9754d 100644 --- a/docs/grid_exchange_formats/cgmes/export.md +++ b/docs/grid_exchange_formats/cgmes/export.md @@ -153,6 +153,53 @@ And the file `manualExampleBasename_SV.xml` will contain: 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. +## Topology kind + +The elements written in the exported files depend on the topology kind of the export and on the CIM version. +By default, the export topology kind is computed from the IIDM network's `VoltageLevel` [connectivity level](../../grid_model/network_subnetwork.md#voltage-level) as follows: +* If all `VoltageLevel` of the network are at `node/breaker` connectivity level, then the export topology kind is `NODE_BREAKER` +* If all `VoltageLevel` of the network are at `bus/breaker` connectivity level, then the export topology kind is `BUS_BRANCH` +* 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`. + +The various configurations and the differences in what's written are summarized in the following table: + +| CIM version | Export
topology kind | Connectivity elements
are written | CIM 16 Equipment Operation
elements are written | +|-------------|--------------------------|---------------------------------------|-----------------------------------------------------| +| 16 | `NODE_BREAKER` | Yes (*) | Yes | +| 16 | `BUS_BRANCH` | No | No | +| 100 | `NODE_BREAKER` | Yes (*) | Yes | +| 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 +* `ConnectivityNode` are: + * Never exported in the case of a CIM 16 `BUS_BRANCH` export + * (*) Always exported in the case of a `NODE_BREAKER` export. If the VoltageLevel's connectivity level is `node/breaker`, +they are exported from nodes, and if the VoltageLevel's connectivity level is `bus/breaker`, they are exported from buses + * (**) Exported from buses of the BusBreakerView in case of a CIM 100 `BUS_BRANCH` export + +### CIM 16 Equipment Operation elements +If the version is CIM 16, a `BUS_BRANCH` export is intrinsically linked to not writing the _operation_ stereotype elements. + +This means the following classes are not written: +* `ConnectivityNode` +* `StationSupply` +* `GroundDisconnector` +* `ActivePowerLimit` +* `ApparentPowerLimit` +* `LoadArea` +* `SubLoadArea` +* `SvStatus` + +As well as the following attributes: +* `LoadGroup.SubLoadArea` +* `ControlArea.EnergyArea` + +In CIM 100 these elements have been integrated in the core equipment profile and can be written even if the export is `BUS_BRANCH`. + ## 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. @@ -366,6 +413,11 @@ Optional property related to the naming strategy specified in `iidm.export.cgmes 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.topology-kind** +Optional property that defines the topology kind of the export. Allowed values are: `NODE_BREAKER` and `BUS_BRANCH`. +By default, the export topology kind reflects the network's voltage levels connectivity level detail: node/breaker, bus/breaker, mixed (CIM 100/CGMES 3.0 only). +This property is used to bypass the natural export topology kind and force a desired one (e.g. export as bus/branch a node/breaker network). + **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.