powsybl · flo-dup · Jun 5, 2024 · May 29, 2024 · May 31, 2024 · May 31, 2024
diff --git a/docs/README.md b/docs/README.md
@@ -5,7 +5,7 @@ They are published on powsybl.readthedocs.io/ and pull requests are built and pr
 
 To build the docs locally, run the following commands:
 ~~~bash
-pip install -r docs/requirements.txt
-sphinx-build -a docs ./build-docs
+pip install -r requirements.txt
+sphinx-build -a . ../build-docs
 ~~~
-Then open `build-docs/index.html` in your browser.
+Then open `../build-docs/index.html` in your browser.
diff --git a/docs/grid_exchange_formats/ampl/export.md b/docs/grid_exchange_formats/ampl/export.md
@@ -3,7 +3,7 @@
 
 ## 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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) 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`.

diff --git a/docs/grid_exchange_formats/cgmes/export.md b/docs/grid_exchange_formats/cgmes/export.md
@@ -100,13 +100,13 @@ PowSybl [`VoltatgeLevels`](../../grid_model/network_subnetwork.md#voltage-level)
 
 ### Control areas
 
-PowSyBl [`ControlAreas`](../model/extensions.md#cim-cgmes-control-areas) are exported as CGMES `ControlAreas`.
+PowSyBl [`ControlAreas`](import.md#extensions) are exported as CGMES `ControlAreas`.
 
 <span style="color: red">TODO details</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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **iidm.export.cgmes.base-name**  
 Optional property that defines the base name of the exported files. Exported CGMES files' names will look like this:

diff --git a/docs/grid_exchange_formats/cgmes/import.md b/docs/grid_exchange_formats/cgmes/import.md
@@ -339,7 +339,7 @@ If the CGMES `Switch` has one of its end in the boundary area, it is mapped to a
 
 The CIM-CGMES format contains more information than what the `iidm` grid model needs for calculation. The additional data, that are needed to export a network in CIM-CGMES format, are stored in several extensions. 
 
-### CIM-CGMES control areas
+### CGMES control areas
 
 This extension models all the control areas contained in the network as modeled in CIM-CGMES.
 
@@ -362,7 +362,7 @@ It is possible to retrieve a control area by its ID. It is also possible to iter
 
 This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module.
 
-### CIM-CGMES dangling line boundary node
+### CGMES dangling line boundary node
 
 This extension is used to add some CIM-CGMES characteristics to dangling lines.
 
@@ -374,7 +374,7 @@ This extension is used to add some CIM-CGMES characteristics to dangling lines.
 
 This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module.
 
-### CIM-CGMES line boundary node
+### CGMES line boundary node
 
 This extension is used to add some CIM-CGMES characteristics to tie lines.
 
@@ -385,25 +385,23 @@ This extension is used to add some CIM-CGMES characteristics to tie lines.
 
 This extension is provided by the `com.powsybl:powsybl-cgmes-extensions` module.
 
-### CIM-CGMES Tap Changers
+### CGMES Tap Changers
 
 <span style="color: red">TODO</span>
 
-### CIM-CGMES SSH metadata
-
-<span style="color: red">TODO</span>
-
-### CIM-CGMES SV metadata
+### CGMES metadata model
 
 <span style="color: red">TODO</span>
 
 ### CIM characteristics
 
 <span style="color: red">TODO</span>
 
+### CGMES model
+
 ## 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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **iidm.import.cgmes.boundary-location**  
 Optional property that defines the directory path where the CGMES importer can find the boundary files (`EQBD` and `TPBD` profiles) if they are not present in the imported zip file. By default, its value is `<ITOOLS_CONFIG_DIR>/CGMES/boundary`.
@@ -459,7 +457,7 @@ Optional property that defines which CGMES profile is used to initialize tap pos
 Optional property that defines if IIDM IDs must be obtained from the CGMES `mRID` (master resource identifier) or the CGMES `rdfID` (Resource Description Framework identifier). The default value is `mRID`.
 
 **iidm.import.cgmes.store-cgmes-model-as-network-extension**    
-Optional property that defines if the whole CGMES model is stored in the imported IIDM network as an [extension](../model/extensions.md#cgmes-model). The default value is `true`.
+Optional property that defines if the whole CGMES model is stored in the imported IIDM network as an [extension](#). The default value is `true`.
 
 **iidm.import.cgmes.store-cgmes-conversion-context-as-network-extension**  
 Optional property that defines if the CGMES conversion context will be stored as an extension of the IIDM output network. It is useful for external validation of the mapping made between CGMES and IIDM. Its default value is `false`.

diff --git a/docs/grid_exchange_formats/iidm/export.md b/docs/grid_exchange_formats/iidm/export.md
@@ -3,7 +3,7 @@
 <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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **iidm.export.xml.indent**  
 The `iidm.export.xml.indent` property is an optional property that defines whether the XIIDM file generated by the XIIDM exporter will be indented or not. Its default value is `true`.

diff --git a/docs/grid_exchange_formats/iidm/import.md b/docs/grid_exchange_formats/iidm/import.md
@@ -3,7 +3,7 @@
 <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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **iidm.import.xml.throw-exception-if-extension-not-found**  
 The `iidm.import.xml.throw-exception-if-extension-not-found` property is an optional property that defines if the XIIDM importer throws an exception while trying to import an unknown or undeserializable extension or if it just ignores it. Its default value is `false`.

diff --git a/docs/grid_exchange_formats/iidm/index.md b/docs/grid_exchange_formats/iidm/index.md
@@ -12,15 +12,13 @@ IIDM is the internal format used in Powsybl because it is designed for running s
 Several exchange formats result from this internal format:
 - XIIDM, which corresponds to an XML export of IIDM,
 - JIIDM, which corresponds to a JSON export of IIDM,
-- BIIDM, which corresponds to a binary export (this is still a beta-feature). 
-
-## Examples
+- BIIDM, which corresponds to a binary export (this is still a beta-feature).
 
 Below are two export from a same network:
 - one XML export (XIIDM exchange format)
 - one JSON export (JIIDM exchange format)
 
-### XIIDM example
+## XIIDM
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <iidm:network xmlns:iidm="http://www.powsybl.org/schema/iidm/1_12" id="sim1" caseDate="2013-01-15T18:45:00.000+01:00" forecastDistance="0" sourceFormat="test" minimumValidationLevel="STEADY_STATE_HYPOTHESIS">
@@ -66,7 +64,7 @@ Below are two export from a same network:
 </iidm:network>
 ```
 
-### JIIDM example
+## JIIDM
 ```json
 {
   "version" : "1.12",

diff --git a/docs/grid_exchange_formats/psse/import.md b/docs/grid_exchange_formats/psse/import.md
@@ -8,7 +8,7 @@ The import module reads and converts a PSS®E power flow data file to the PowSyB
 First, input data is obtained by reading and parsing the input file and as result a PSS®E model is created in memory. This model can be viewed as a set of Java classes where each data block of the PSS®E model is associated with a specific Java class that describes all their attributes or data items. Then, some inconsistency checks are performed on this model. If the validation succeeds the PSS®E model is converted to a PowSyBl grid model.
 
 ## Options
-Parameters for the import can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md) module.
+Parameters for the import can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **psse.import.ignore-base-voltage**  
 The `psse.import.ignore-base-voltage` property is an optional property that defines if the importer should ignore the base voltage information present in the PSS®E file. The default value is `false`.

diff --git a/docs/grid_exchange_formats/ucte/export.md b/docs/grid_exchange_formats/ucte/export.md
@@ -3,7 +3,7 @@
 <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.
+These properties can be defined in the configuration file in the [import-export-parameters-default-value](../../user/configuration/import-export-parameters-default-value.md#import-export-parameters-default-value) module.
 
 **ucte.export.naming-strategy**  
 The `ucte.export.naming-strategy` property is an optional property that defines the naming strategy to be used for UCTE export.

diff --git a/docs/grid_features/import_post_processor.md b/docs/grid_features/import_post_processor.md
@@ -69,9 +69,8 @@ The following example prints meta-information from the network:
 print("Network " + network.getId() + " (" + network.getSourceFormat()+ ") is imported");
 ```
 
-
 ## LoadFlow post-processor
-Mathematically speaking, a [power flow](../../simulation/powerflow/index.md) result is fully defined by the complex voltages at each node. The consequence is that most load flow algorithms converge very fast if they are initialized with voltages. As a result, it happens that load flow results include only voltages and not flows on branches. This post-processors computes the flows given the voltages. The equations (Kirchhoff law) used are the same as the one used in the [load flow validation](../../user/itools/loadflow-validation.md#load-flow-results-validation) to compute $P_1^{\text{calc}}$, $Q_1^{\text{calc}}$, $P_2^{\text{calc}}$, $Q_2^{\text{calc}}$ for branches and $P_3^{\text{calc}}$, $Q_3^{\text{calc}}$ in addition for three-windings transformers.
+Mathematically speaking, a [load flow](../simulation/loadflow/loadflow.md) result is fully defined by the complex voltages at each node. The consequence is that most load flow algorithms converge very fast if they are initialized with voltages. As a result, it happens that load flow results include only voltages and not flows on branches. This post-processors computes the flows given the voltages. The equations (Kirchhoff law) used are the same as the one used in the [load flow validation](../user/itools/loadflow-validation.md#load-flow-results-validation) to compute $P_1^{\text{calc}}$, $Q_1^{\text{calc}}$, $P_2^{\text{calc}}$, $Q_2^{\text{calc}}$ for branches and $P_3^{\text{calc}}$, $Q_3^{\text{calc}}$ in addition for three-windings transformers.
 
 To use this post-processor, add the `com.powsybl:powsybl-loadflow-results-completion` to your classpath and enable it setting the `postProcessors` property of the `import` module.
 

diff --git a/docs/grid_model/extensions.md b/docs/grid_model/extensions.md
@@ -11,7 +11,7 @@ Note that some extensions provided by PowSyBl aren't supported in the [persisten
 Every extension is considered as serializable unless explicitly specified as non-serializable in XML-IIDM.
 
 ## Active power control
-This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/powerflow/index.md#balanceType) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery).
+This extension is used to configure the participation factor of the generator, typically in the case of a load flow computation with distributed slack enabled (with [balance type](../simulation/loadflow/loadflow.md#generic-parameters) on generator). This extension is attached to a [generator](network_subnetwork.md#generator) or a [battery](network_subnetwork.md#battery).
 
 | Attribute            | Type    | Unit                   | Required | Default value | Description                                  |
 |----------------------|---------|------------------------|----------|---------------|----------------------------------------------|
@@ -282,7 +282,7 @@ A load is described by its active power setpoint $P0$ and its reactive power set
 | variableReactivePower | double | MVar | yes      | -             | The part of the reactive power setpoint that is considered variable |
 | fixedReactivePower    | double | MVar | yes      | -             | The part of the reactive power setpoint that is considered constant |
 
-Here is how to add an load detail extension to a load:
+Here is how to add a load detail extension to a load:
 ```java
 load.newExtension(LoadDetailAdder.class)
     .withVariableActivePower(40)
@@ -328,7 +328,12 @@ This extensions is used for generators with a remote reactive control.
 
 ## Slack terminal
 
-This extension is attached to a [voltage level](network_subnetwork.md#voltage-level) and is used to define the slack bus of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis. Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter [`isReadSlackBus`](../simulation/powerflow/index.md#available-parameters). Use this extension after a computation to attach to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable default load flow parameter [`isWriteSlackBus`](../../simulation/powerflow/index.md#available-parameters).
+This extension is attached to a [voltage level](network_subnetwork.md#voltage-level) and is used to define the slack bus
+of a power flow calculation i.e. which bus will be used to balance the active and reactive power in load flow analysis.
+Use this extension before a computation to force the slack bus selection. You should enable default load flow parameter
+[`isReadSlackBus`](../simulation/loadflow/loadflow.md#generic-parameters). Use this extension after a computation to attach
+to the network the slack bus that has been selected by the load flow engine (one by connected component). You should enable
+default load flow parameter [`isWriteSlackBus`](../simulation/loadflow/loadflow.md#generic-parameters).
 
 The slack bus is defined through the terminal of a connectable that belongs to the bus. It is totally allowed to define a disconnected terminal as slack as the connectable could be reconnected during a grid study.
 

diff --git a/docs/grid_model/network_subnetwork.md b/docs/grid_model/network_subnetwork.md
@@ -260,7 +260,7 @@ In case the line is a boundary, a pairing key $pairingKey$ (in previous network
 
 **Available extensions**
 
-- [CGMES Dangling Line Boundary Node](extensions.md#cgmes-dangling-line-boundary-node)
+- [CGMES Dangling Line Boundary Node](../grid_exchange_formats/cgmes/import.md#cgmes-dangling-line-boundary-node)
 - [Connectable position](extensions.md#connectable-position)
 - [Discrete Measurements](extensions.md#discrete-measurements)
 - [Identifiable Short-Circuit](extensions.md#identifiable-short-circuit)
@@ -445,7 +445,7 @@ $$
 - [Connectable position](extensions.md#connectable-position)
 - [Branch Observability](extensions.md#branch-observability)
 - [Branch Status](extensions.md#branch-status)
-- [CGMES Line Boundary Node](extensions.md#cgmes-line-boundary-node)
+- [CGMES Line Boundary Node](../grid_exchange_formats/cgmes/import.md#cgmes-line-boundary-node)
 - [Discrete Measurements](extensions.md#discrete-measurements)
 - [Identifiable Short-Circuit](extensions.md#identifiable-short-circuit)
 - [Measurements](extensions.md#measurements)

diff --git a/docs/simulation/index.md b/docs/simulation/index.md
@@ -10,7 +10,7 @@ Below comes a description of the various types of simulation and supported solve
 maxdepth: 2
 ---
 
-loadflow/loadflow.md
+loadflow/index.md
 security/security.md
 sensitivity/sensitivity.md
 shortcircuit/index.md

diff --git a/docs/simulation/loadflow/index.md b/docs/simulation/loadflow/index.md
@@ -0,0 +1,9 @@
+# Load flow
+
+```{toctree}
+---
+maxdepth: 2
+---
+loadflow.md
+loadflow_validation.md
+```