Update documentation

Signed-off-by: Romain Courtier <[email protected]>

docs/grid_exchange_formats/cgmes/export.md

@@ -153,6 +153,62 @@ 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 is `MIXED_TOPOLOGY`
+
+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<br/>topology kind | Connectivity elements<br/>are written | CIM 16 Equipment Operation<br/>elements are written |
+|-------------|--------------------------|---------------------------------------|-----------------------------------------------------|
+| 16          | `NODE_BREAKER`           | Yes (*)                               | Yes                                                 |
+| 16          | `MIXED_TOPOLOGY`         | No                                    | No                                                  |
+| 16          | `BUS_BRANCH`             | No                                    | No                                                  |
+| 100         | `NODE_BREAKER`           | Yes (*)                               | Yes                                                 |
+| 100         | `MIXED_TOPOLOGY`         | Yes                                   | Yes                                                 |
+| 100         | `BUS_BRANCH`             | No                                    | Yes                                                 |
+
+As highlighted with above table, the `MIXED_TOPOLOGY` export topology kind is only relevant for a CIM 100/CGMES 3.0 case.
+If the version of the export is CIM 16/CGMES 2.4.15, a `MIXED_TOPOLOGY` network is exported as `BUS_BRANCH` since hybrid networks are not supported for that version.
+
+### Connectivity elements
+* A `NODE_BREAKER` export will always write the following elements:
+    * `ConnectivityNode`
+    * `BusbarSection`
+    * non-retained `Switch`
+
+  (*) If the VoltageLevel's connectivity level is `bus/breaker`, `ConnectivityNode` are exported from buses of the BusBreakerView.
+
+* A `BUS_BRANCH` export will never write above listed elements.
+
+* A `MIXED_TOPOLOGY` CIM 100 export will behave as a `NODE_BREAKER` export for VoltageLevel at `node/breaker` connectivity level
+  and as a `BUS_BRANCH` export for VoltageLevel at `bus/breaker` connectivity level.
+
+### CIM 16 Equipment Operation elements
+If the version is CIM 16, a `BUS_BRANCH` export is intrinsically linked to not writing the equipment operation profile.
+
+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 +422,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.