Update documentation

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

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<br/>topology kind | Connectivity elements<br/>are written | CIM 16 Equipment Operation<br/>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.