Add documentation (CGMES import and export and IIDM modeling)

Signed-off-by: Romain Courtier <romain.courtier@rte-france.com>

docs/grid_exchange_formats/cgmes/export.md

@@ -387,6 +387,10 @@ the sums of active power and reactive power at the bus are higher than a thresho
 `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.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`.
 

docs/grid_exchange_formats/cgmes/import.md

@@ -304,8 +304,39 @@ Sections are created from the lowest CGMES `sectionNumber` to the highest and ea
 <span style="color: red">TODO regulation</span>
 
 (cgmes-operational_limit-import)=
-### OperationalLimit
-<span style="color: red">TODO</span>
+### OperationalLimits
+
+OperationalLimits model a specification of limits associated with equipments.
+
+#### OperationalLimitSet
+
+A CGMES `OperationalLimitSet` is a set of `OperationalLimit` associated with equipment or terminal. It is mapped to a PowSyBl [`OperationalLimitsGroup`](../../grid_model/additional.md#limit-group-collection).
+The `id` attribute is copied from CGMES `name`.
+
+Just like CGMES allows to attach multiple `OperationalLimitSet` on the same equipment or terminal, PowSyBl stores a collection of `OperationalLimitsGroup` for every 
+[`Line`](../../grid_model/network_subnetwork.md#line) (actually 2 collections for a Line: one for each side), [`DanglingLine`](../../grid_model/network_subnetwork.md#dangling-line) and [`ThreeWindingTransformer.Leg`](../../grid_model/network_subnetwork.md#three-winding-transformer-leg).
+
+In case of multiple `OperationalLimitSet` attached to the same end:
+- If the sets have different names, they are imported in different `OperationalLimitsGroup`. For instance, a `WINTER` set and a `SUMMER` set will be imported in two distinct groups.
+- If the sets have the same name, the sets are merged in the same `OperationalLimitsGroup`. For instance, a `WINTER` set of CurrentLimit and a `WINTER` set of ActivePowerLimit will be imported in the same group.
+
+If there is only one `OperationalLimitsGroup` on an end, it automatically gets to be selected (active). However, if there is multiple groups, none is selected: the user has to choose which set is active.
+
+#### OperationalLimit
+
+A CGMES `OperationalLimit` is an abstract class that represent different kinds of limits: current, active power or apparent power.  The collection of CGMES `OperationalLimit` in the set is mapped to a PowSyBl [`LoadingLimits`](../../grid_model/additional.md#loading-limits) as follows:
+- The set of CGMES `CurrentLimit` in the `OperationalLimitSet` are mapped to the `currentLimits` attribute of the PowSyBl `OperationalLimitsGroup` corresponding to the set. 
+- The set of CGMES `ActivePowerLimit` in the `OperationalLimitSet` are mapped to the `activePowerLimits` attribute of the PowSyBl `OperationalLimitsGroup` corresponding to the set. 
+- The set of CGMES `ApparentPowerLimit` in the `OperationalLimitSet` are mapped to the `apparentPowerLimits` attribute of the PowSyBl `OperationalLimitsGroup` corresponding to the set.
+
+A particular CGMES `OperationalLimit` is mapped differently depending on its associated CGMES `OperationalLimitType`:
+- A permanent limit (`OperationalLimitType.limitType` is `LimitTypeKind.patl`) is mapped as follows:
+    - PowSyBl `LoadingLimits.permanentLimit` is copied from CGMES `OperationalLimit.value`
+- A temporary limit (`OperationalLimitType.limitType` is `LimitTypeKind.tatl`) is mapped as follows:
+    - A new entry is created in PowSyBl `LoadingLimits.temporaryLimits`
+    - `name` is copied from `OperationalLimit.name`
+    - `value` is copied from `OperationalLimit.value`
+    - `acceptableDuration` is copied from `OperationalType.acceptableDuration`
 
 (cgmes-power-transformer-import)=
 ### PowerTransformer

docs/grid_model/additional.md

@@ -100,7 +100,7 @@ In PowSyBl, users can store a collection of limits:
 
 #### Examples
 
-Two examples are provided below, with their corresponding limits scheme, to show clearly how to create a new `CurrentLimits` instance.
+Three examples are provided below, with their corresponding limits scheme, to show clearly how to create new `CurrentLimits` instances.
 
 ##### First example
 This first example creates a `CurrentLimits` instance containing one permanent limit and two temporary limits.
@@ -147,6 +147,35 @@ CurrentLimits currentLimits = network.getDanglingLine("DL").newCurrentLimits()
 ![Current limits scheme_example2](img/current-limits-example2.svg){align=center class="only-light"}
 ![Current limits scheme_example2](img/dark_mode/current-limits-example2.svg){align=center class="only-dark"}
 
+##### Third example
+This third example shows how to create multiple OperationalLimitsGroup on the same end, and set one of these as the selected (active) one.
+```java
+Line line = network.getLine("Line");
+
+line.newOperationalLimitsGroup1("SUMMER")
+        .newCurrentLimits()
+        .setPermanentLimit(60)
+        .beginTemporaryLimit()
+        .setName("TATL-10")
+        .setValue(80)
+        .setAcceptableDuration(10 * 60)
+        .endTemporaryLimit()
+        .add();
+
+line.newOperationalLimitsGroup1("WINTER")
+        .newCurrentLimits()
+        .setPermanentLimit(100)
+        .beginTemporaryLimit()
+        .setName("TATL-10")
+        .setValue(120)
+        .setAcceptableDuration(10 * 60)
+        .endTemporaryLimit()
+        .add();
+
+line.setSelectedOperationalLimitsGroup1("WINTER");
+```
+In this example, there is two sets of limits on the same line side (1). The selected set is the winter one: the limits violations will be tested against this set.
+
 (phase-tap-changer)=
 ## Phase tap changer
 [![Javadoc](https://img.shields.io/badge/-javadoc-blue.svg)](https://javadoc.io/doc/com.powsybl/powsybl-core/latest/com/powsybl/iidm/network/PhaseTapChanger.html)