Documentation: grid formats + itools convert-network (#3034)

Signed-off-by: Olivier Perrin <olivier.perrin@rte-france.com>

.gitignore

@@ -30,3 +30,6 @@ powsybl.log
 # Maven wrapper jar
 .mvn/wrapper/*.jar
 
+# Generated readthedocs pages
+build-docs/
+

docs/grid_exchange_formats/ampl/example.md

@@ -0,0 +1,8 @@
+# Example
+
+```text
+#Branches
+#"variant" "num" "bus1" "bus2" "p1 (MW)" "p2 (MW)" "q1 (MVar)" "q2 (MVar)"
+1 1 -1 -1 -100.000 -200.000 -110.000 -120.000
+1 4 -1 -1 -100.000 -200.000 -110.000 -120.000
+```

docs/grid_exchange_formats/ampl/export.md

@@ -0,0 +1,14 @@
+# Export
+<span style="color: red">TODO</span>
+
+## Options
+
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md) module.
+
+**iidm.export.ampl.export-ratio-tap-changer-voltage-target**  
+The `iidm.export.ampl.export-ratio-tap-changer-voltage-target` property is an optional property that defines whether the AMPL exporter exports the ratio tap changer voltage setpoint or not. Its default value is `false`.
+
+### Deprecated properties
+
+**iidm.export.ampl.exportRatioTapChangerVoltageTarget**  
+The `iidm.export.ampl.exportRatioTapChangerVoltageTarget` property is deprecated since V2.4.0. Use the `iidm.export.ampl.export-ratio-tap-changer-voltage-target` property instead.

docs/grid_exchange_formats/ampl/import.md

@@ -0,0 +1,3 @@
+# Import
+
+The import of PowSyBl networks to AMPL format is not supported.

docs/grid_exchange_formats/ampl/index.md

@@ -0,0 +1,12 @@
+# AMPL
+
+```{toctree}
+:hidden:
+import.md
+export.md
+example.md
+```
+
+The [AMPL](https://ampl.com/) (**A** **M**athematical **P**rogramming **L**anguage) format is an algebraic modeling language to describe and solve high-complexity problems for large-scale mathematical computing (i.e. large-scale optimization and scheduling-type problems).
+
+IIDM networks can be converted in flat text files easy to read in AMPL, each of which describing one type of the network equipments (batteries, generators, loads, branches, buses, etc.).

docs/grid_exchange_formats/ieee/ieee.md

@@ -1 +1,3 @@
-# IEEE
+# IEEE CDF
+
+<span style="color: red">TODO</span>

docs/grid_exchange_formats/index.md

@@ -9,11 +9,11 @@ or network simulation via different tools: check them out below.
 maxdepth: 2
 ---
 
-ampl/ampl.md
+ampl/index.md
 cgmes/index.md
 ieee/ieee.md
-matpower/matpower.md
-psse/psse.md
-ucte/ucte.md
+matpower/index.md
+psse/index.md
+ucte/index.md
 xiidm/xiidm.md
 ```

docs/grid_exchange_formats/matpower/export.md

@@ -0,0 +1,3 @@
+# Export
+
+The export of PowSyBl networks to Matpower format is not supported.

docs/grid_exchange_formats/matpower/import.md

@@ -0,0 +1,25 @@
+# Import
+There is a lot of Matpower open source cases available all over the internet. Most of the time, those cases are provided  as a `.m` file. This is Matlab code and only Matlab can interpret this kind of data. PowSyBl converter can only import `.mat` file which is a binary serialization of Matlab case data structure created from `.m` file.
+
+## Matpower cases conversions
+To import a Matpower cases, they have to be converted to `.mat` files first. This can be done using Matlab of course, but it is also possible to use [Octave](https://www.gnu.org/software/octave/), an open source scientific programming language which is mostly compatible with Matlab. Matpower toolbox can be installed with Octave.
+
+### Octave and Matpower installation
+To install Octave, please follow the installation guide for your operating system, available on their [wiki](https://wiki.octave.org/Category:Installation).
+
+Then, you can download and install Matpower toolbox, following the instructions of the [getting started](https://matpower.org/about/get-started/).
+
+### Matpower case conversion
+In this example, we'll use the `case6515rte.m` case file found on [Matpower GitHub](https://github.com/MATPOWER/matpower/blob/master/data/case6515rte.m).
+
+Run Octable in the `traditional` mode, meaning the mode with the maximal compatibility with Matlab especially for binary serializations.
+```shell
+$> octave --traditional
+```
+
+To convert the `case6515rte.m` to `case6515rte.mat`, execute the two following lines:
+```matlab
+mpc = loadcase('case6515rte.m');
+savecase("case6515rte.mat", mpc);
+```
+Note that the `loadcase` and `savecase` are functions provided by the Matpower toolbox.

docs/grid_exchange_formats/matpower/index.md

@@ -0,0 +1,9 @@
+# Matpower
+
+```{toctree}
+:hidden:
+import.md
+export.md
+```
+
+[Matpower](https://matpower.org/) is a free and open-source Matlab toolbox for power system simulation and optimization. It is widely used by academics for research purposes.

docs/grid_exchange_formats/psse/examples.md

@@ -0,0 +1,73 @@
+# Examples
+
+A minimum network model is included as an example in version 35 of both formats RAW and RAWX.
+
+```text
+ 0,      100.0, 35, 0, 0, 60.00       / October 27, 2020 18:37:53
+ PSS(R)E Minimum RAW Case
+
+0 / END OF SYSTEM-WIDE DATA, BEGIN BUS DATA
+    1,'Slack-Bus   ', 138.0000,3
+    2,'Load-Bus    ', 138.0000,1
+0 / END OF BUS DATA, BEGIN LOAD DATA
+    2,'1 ',1,,,   40.000,    15.000
+0 / END OF LOAD DATA, BEGIN FIXED SHUNT DATA
+0 / END OF FIXED SHUNT DATA, BEGIN GENERATOR DATA
+    1,'1 ',   40.350,   10.870
+0 / END OF GENERATOR DATA, BEGIN BRANCH DATA
+    1,     2,'1 ', 0.01938, 0.05917,0.05280
+0 / END OF BRANCH DATA, BEGIN SYSTEM SWITCHING DEVICE DATA
+0 / END OF SYSTEM SWITCHING DEVICE DATA, BEGIN TRANSFORMER DATA
+0 / END OF TRANSFORMER DATA, BEGIN AREA DATA
+0 / END OF AREA DATA, BEGIN TWO-TERMINAL DC DATA
+0 / END OF TWO-TERMINAL DC DATA, BEGIN VOLTAGE SOURCE CONVERTER DATA
+0 / END OF VOLTAGE SOURCE CONVERTER DATA, BEGIN IMPEDANCE CORRECTION DATA
+0 / END OF IMPEDANCE CORRECTION DATA, BEGIN MULTI-TERMINAL DC DATA
+0 / END OF MULTI-TERMINAL DC DATA, BEGIN MULTI-SECTION LINE DATA
+0 / END OF MULTI-SECTION LINE DATA, BEGIN ZONE DATA
+0 / END OF ZONE DATA, BEGIN INTER-AREA TRANSFER DATA
+0 / END OF INTER-AREA TRANSFER DATA, BEGIN OWNER DATA
+0 / END OF OWNER DATA, BEGIN FACTS CONTROL DEVICE DATA
+0 / END OF FACTS CONTROL DEVICE DATA, BEGIN SWITCHED SHUNT DATA
+0 / END OF SWITCHED SHUNT DATA, BEGIN GNE DEVICE DATA
+0 / END OF GNE DEVICE DATA, BEGIN INDUCTION MACHINE DATA
+0 / END OF INDUCTION MACHINE DATA, BEGIN SUBSTATION DATA
+0 / END OF SUBSTATION DATA
+Q
+```
+
+```json
+{
+     "network":{
+         "caseid":{
+             "fields":["ic", "sbase", "rev", "xfrrat", "nxfrat", "basfrq", "title1"],
+             "data":[0, 100.00, 35, 0, 0, 60.00, "PSS(R)E Minimum RAWX Case"]
+         },
+         "bus":{
+             "fields":["ibus", "name", "baskv", "ide"],
+             "data":[
+                 [1, "Slack-Bus", 138.0, 3],
+                 [2, "Load-Bus", 138.0 1]
+             ]
+         },
+         "load":{
+             "fields":["ibus", "loadid", "stat", "pl", "ql"],
+             "data":[
+                 [2, "1", 1, 40.0, 15.0]
+             ]
+         },
+         "generator":{
+             "fields":["ibus", "machid", "pg", "qg"],
+             "data":[
+                 [1, "1", "40.35", "10.87"]
+             ]
+         },
+         "acline":{
+             "fields":["ibus", "jbus", "ckt", "rpu", "xpu", "bpu"],
+             "data":[
+                 [1, 2, "1", 0.01938, 0.05917, 0.05280]
+             ]
+         }
+    }
+}
+```

docs/grid_exchange_formats/psse/export.md

@@ -0,0 +1,3 @@
+# Export
+
+The export of PowSyBl networks to PSS®E format is not supported.