Update documentation

Signed-off-by: lisrte <laurent.issertial@rte-france.com>

docs/dynamic_simulation/dynamic-models-dsl.md

@@ -4,25 +4,22 @@ layout: default
 
 # Dynamic Models DSL
 
-The Dynamic Models DSL is a domain specific language written in groovy for the association of dynamic models to each static equipment present in the network. If some equipment are not configured, Dynawo would use a default model and set of parameters.
+The Dynamic Models DSL is a domain specific language written in groovy for the creation dynamic models used by Dynawo, most of them associated with a static equipment present in the network.
+If some equipments are not configured, Dynawo would use a default model and set of parameters.
 
 * TOC
 {:toc}
 
 ## BlackBoxModel
-Most of the models supported are `BlackBoxModels`. This kind of dynamic models have three attributes:
-- `staticId` refers to the ID of the load in the network.
-- `dynamicModelId` is an optional attribute to identify this model. By default, it is equal to the `staticId`.
+All the models supported are `BlackBoxModel`. This kind of dynamic model have three attributes:
+- `lib` refers to the dynamic model library used in Dynawo.
+- `dynamicModelId` identifies the model.
 - `parameterSetId` refers a set of parameters for this model in one of the network parameters file.
 
-## Generators
-All the following models are [BlackBoxModels](#blackboxmodel) you can associate to an IIDM generator. To do so, you have to use their name as a keyword and define at least a `staticId` and a `parameterSetId`. Like every other `BlackBoxModel`, the `dynamicModelId` is optional and would be equal to the `staticId` if not set.
-
-Supported models are:
-- GeneratorSynchronousThreeWindings
-- GeneratorSynchronousThreeWindingsProportionalRegulations
-- GeneratorSynchronousFourWindings
-- GeneratorSynchronousFourWindingsProportionalRegulations
+## Equipment models
+These models are `BlackBoxModel` matching an IIDM equipment (generator, load, ...).
+To instantiate them with DSL, you have to use their model name as a keyword and define at least a `staticId` and a `parameterSetId`.
+The `dynamicModelId` is optional and would be equal to the `staticId` if not set.
 
 **Example**
 ```groovy
@@ -31,62 +28,72 @@ GeneratorSynchronousThreeWindings {
     dynamicModelId '<DYNAMIC_MODEL_ID>'
     parameterSetId '<PARAMETER_ID>'
 }
-GeneratorSynchronousThreeWindingsProportionalRegulations {
-    staticId '<GENERATOR_ID>'
-    dynamicModelId '<DYNAMIC_MODEL_ID>'
-    parameterSetId '<PARAMETER_ID>'
-}
-GeneratorSynchronousFourWindings {
-    staticId '<GENERATOR_ID>'
-    dynamicModelId '<DYNAMIC_MODEL_ID>'
-    parameterSetId '<PARAMETER_ID>'
-}
-GeneratorSynchronousFourWindingsProportionalRegulations {
-    staticId '<GENERATOR_ID>'
-    dynamicModelId '<DYNAMIC_MODEL_ID>'
-    parameterSetId '<PARAMETER_ID>'
-}
-```
-
-## Loads
-
-### LoadAlphaBeta
-This is a [BlackBoxModel](#blackboxmodel) you can associate to an IIDM load. To do so, you have to use the `LoadAlphaBeta` keyword and define at least a `staticId` and a `parameterSetId`. Like every other `BlackBoxModel`, the `dynamicModelId` is optional and would be equal to the `staticId` if not set.
-
-**Example**
-```groovy
 LoadAlphaBeta {
     staticId '<LOAD_ID>'
-    dynamicModelId '<DYNAMIC_MODEL_ID>'
     parameterSetId '<PARAMETER_ID>'
 }
 ```
 
-## Frequency models
-
-### OmegaRef
-This is a model shared by generators with the same frequency reference. To link a generator to the `OmegaRef` model, use the `OmegaRef` keyword and assign the `generatorModelId` attribute to its `dynamicModelId` value.
-
-**Example**
-```groovy
-OmegaRef {
-    generatorModelId '<DYNAMIC_MODEL_ID>'
-}
-```
-
-## Automatons
-
-### CurrentLimitAutomaton
-This is a [BlackBoxModel](#blackboxmodel) you can associate to an IIDM line or two windings transformer. To do so, you have to use the `CurrentLimitAutomaton` keyword and define at least a `staticId` and a `parameterSetId`. Like every other `BlackBoxModel`, the `dynamicModelId` is optional and would be equal to the `staticId` if not set.
+## Automation system models
+These models are `BlackBoxModel` of automation system without IIDM equipment.
 
-This model has also another required attribute to define which side is monitored.
+### OverloadManagementSystem
+This model connect to IIDM line or two windings transformer. Besides `dynamicModelId` and `parameterSetId` it needs:
+-  one control branch
+-  one measurement branch (can be the controlled one)
+-  which side is monitored.
 
 **Example**
 ```groovy
-CurrentLimitAutomaton {
-    staticId '<BRANCH_ID>'
-    dynamicModelId '<DYNAMIC_MODEL_ID>'
+OverloadManagementSystem {
+    dynamicModelId '<DYN_ID>'
     parameterSetId '<PARAMETER_ID>'
-    side '<SIDE>'
+    controlledBranch '<BRANCH_ID>'
+    iMeasurement '<BRANCH_ID>'
+    iMeasurementSide TwoSides.TWO
 }
 ```
+TODO: add all automation systems
+
+## Supported models
+Models are listed in [models.json](../../blob/main/dynawaltz/src/main/resources/models.json).  
+The list is divided in categories each linked to a dedicated builder.
+### Categories properties
+* `defaultLib` : name of the default library
+* `libs` : list of dynawo libraries supported for this category
+
+The list is statically loaded via [ModelConfigLoader](../../blob/main/dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfigLoader.java) services and thus can be extended.
+### Library properties
+* `lib`: library name used in dynawo
+* `alias`: name used in powsybl-dynawo instead of lib
+* `properties`: dynamic model properties (synchronized, dangling, etc.)
+* `internalModelPrefix`: used for dyd file creation
+
+## Dynamic model Builder List
+Ultimately, alls groovy scripts call dedicated builders that can be used directly by developers.
+### Equipments
+* BaseStaticVarCompensatorBuilder
+* HvdcPBuilder
+* HvdcVscBuilder
+* GeneratorFictitiousBuilder
+* SynchronizedGeneratorBuilder
+* SynchronousGeneratorBuilder
+* WeccBuilder
+* GridFormingConverterBuilder
+* LineBuilder
+* StandardBusBuilder
+* InfiniteBusBuilder
+* TransformerFixedRatioBuilder
+* BaseLoadBuilder
+* LoadOneTransformerBuilder
+* LoadTwoTransformersBuilder
+* LoadOneTransformerTapChangerBuilder
+* LoadTwoTransformersTapChangersBuilder
+### Automation Systems
+* TapChangerAutomationSystemBuilder
+* TapChangerBlockingAutomationSystemBuilder
+* UnderVoltageAutomationSystemBuilder
+* DynamicOverloadManagementSystemBuilder
+* DynamicTwoLevelsOverloadManagementSystemBuilder
+* PhaseShifterPAutomationSystemBuilder
+* PhaseShifterIAutomationSystemBuilder

docs/dynamic_simulation/dynawo-configuration.md

@@ -8,7 +8,7 @@ The `dynawo` module defines the required parameters to run with Dynawo.
 ## Properties
 
 **homeDir**  
-Use the `homeDir` property to defines the install directory of the dynawo simulator.
+Use the `homeDir` property to defines the installation directory of the dynawo simulator.
 
 **debug**  
 Use the `debug` property to specify if the temporary folder where the inputs are generated should be kept after the simulation.

docs/dynamic_simulation/dynawo-default-parameters.md

@@ -8,27 +8,55 @@ The `dynawo-default-parameters` module defines the default values for all specif
 ## Required properties
 
 **parametersFile**  
-The `parametersFile` property is a required property that defines the path of the main parameters file.
+`parametersFile` defines the path of the main parameters file. The default value is `models.par`.
 
 **network.parametersFile**  
-The `network.parametersFile` property is a required property that defines the path of the network parameters file
+`network.parametersFile` defines the path of the network parameters file. The default value is `network.par`.
 
 **solver.parametersFile**  
-The `solver.parametersFile` property is a required property that defines the path of the solver parameters file
+`solver.parametersFile` defines the path of the solver parameters file. The default value is `solvers.par`.
 
 ## Optional properties
 
 **network.parametersId**  
-The `network.parametersId` property is an optional property that defines the set of network parameters. The default value for this property is `NETWORK`.
+`network.parametersId` defines the network parameters set id stored in `network.parametersFile`. The default value for this property is `1`.
+
+**solver.parametersId**  
+`solver.parametersId` defines the solver parameters set id stored in `solver.parametersFile`. The default value is `1`.
 
 **solver.type**  
-The `solver.type` property is an optional property that defines the solver used in the simulation. The default value for this property is `SIM`. The available `com.powsybl.dynawo.simulator.DynawoSimulationParameters.SolverType`
-values are:
+`solver.type` defines the solver used in the simulation. The default value is `SIM`.
+The available `com.powsybl.dynawaltz.DynaWaltzParameters.SolverType` values are:
 - `SIM`: the simplified solver (fixed time step solver)
 - `IDA`: the IDA solver (variable time step solver)
 
-**solver.parametersId**  
-The `solver.parametersId` property is an optional property that defines the set of solver parameters. The default value for this property is `SIM`.
+**dump.export**
+`dump.export` defines if the dynamic simulation result should be exported as a dump. The default value is `FALSE`.
+
+**dump.useAsInput**
+`dump.useAsInput` defines if a previous simulation result dump should be used as input for the current simulation. The default value is `FALSE`.
+
+**dump.exportFolder**
+`dump.exportFolder` defines the folder name where the dump is exported. The default value is `null`.
+
+**dump.fileName**
+`dump.fileName` defines the dump file name. The default value is `null`.
+
+**useModelSimplifiers**
+`useModelSimplifiers` defines if simplifiers are used before macro connection computation //TODO add link. The default value is `FALSE`.
+
+**mergeLoads**
+`mergeLoads` defines if loads connected to the same bus are merged or not. The default value is `FALSE`.
+
+**timeline.exportMode**
+`timeline.exportMode` defines the file extension of the timeline export. The default value is `TXT`.
+The available `com.powsybl.dynawaltz.DynaWaltzParameters.ExportMode` values are:
+- `CSV`
+- `TXT`: same format as `CSV` but with `|` separator
+- `XML`
+
+**precision**
+`precision` defines the simulation step precision The default value is `1e-6`.
 
 ## Examples
 
@@ -37,10 +65,18 @@ The `solver.parametersId` property is an optional property that defines the set
 dynawo-default-parameters:
   parametersFile: /home/user/parametersFile
   network.parametersFile: /home/user/networkParametersFile
-  network.parametersId: NETWORK
+  network.parametersId: 1
   solver.type: SIM
   solver.parametersFile: /home/user/solverParametersFile
-  solver.parametersId: SIM
+  solver.parametersId: 1
+  dump.export: false
+  dump.useAsInput: false
+  dump.exportFolder: /home/user/dumps
+  dump.fileName: dump.dmp
+  useModelSimplifiers: false
+  mergeLoads: false
+  timeline.exportMode: XML
+  precision: 10e-6
 ```
 
 **XML configuration:**
@@ -52,5 +88,13 @@ dynawo-default-parameters:
   <solver.type>SIM</solver.type>
   <solver.parametersFile>/home/user/solverParametersFile</solver.parametersFile>
   <solver.parametersId>SIM</solver.parametersId>
+  <dump.export>false</dump.export>
+  <dump.useAsInput>false</dump.useAsInput> 
+  <dump.exportFolder>/home/user/dumps</dump.exportFolder>
+  <dump.fileName>dump.dmp</dump.fileName>
+  <useModelSimplifiers>false</useModelSimplifiers>
+  <mergeLoads>false</mergeLoads>
+  <timeline.exportMode>XML</timeline.exportMode>
+  <precision>10e-6</precision>
 </dynawo-default-parameters>
 ```

docs/dynamic_simulation/event-models-dsl.md

@@ -9,32 +9,22 @@ The Event Models DSL is a domain specific language written in groovy for the sim
 * TOC
 {:toc}
 
-## BlackBoxModel
-Most of the event models supported are `BlackBoxModels`. This kind of dynamic models have three attributes:
-- `staticId` refers to the ID of the load in the network.
-- `eventModelId` is an optional attribute to identify this model. By default, it is equal to the `staticId`.
-- `parameterSetId` refers a set of parameters for this model in one of the network parameters file.
+## Event Model
+- All the models supported are `BlackBoxModel`. This kind of event model have three attributes:
+- `lib` refers to the event model library used in Dynawo.
+- `staticId` identifies the equipment affected by the event
+- `startTime` defines when the event starts.
 
-## EventQuadripoleDisconnection
-Use this event to disconnect a line or a two windings transformer during the simulation. The `EventQuadripoleDisconnection` is a [BlackBoxModel](#blackboxmodel) of which the `staticId` refers to a line or a two windings transformer of the network.
+## Disconnect
+Use this event to disconnect a branch, injection or an HVDC line.
 
 **Example**
 ```groovy
-EventQuadripoleDisconnection {
-    staticId '<BRANCH_ID>'
-    eventModelId '<EVENT_MODEL_ID>'
-    parameterSetId '<PARAMETER_ID>'
+Disconnect {
+    staticId "GEN"
+    startTime 1
 }
 ```
 
-## EventSetPointBoolean
-Use this event to set or unset a boolean field of a dynamic model. At the moment, only generator disconnection is supported. The `EventSetPointBoolean` model is a [BlackBoxModel](#blackboxmodel) of which the `staticId` refers to a generator of the network.
-
-**Example**
-```groovy
-EventSetPointBoolean {
-    staticId '<GENERATOR_ID>'
-    eventModelId '<EVENT_MODEL_ID>'
-    parameterSetId '<PARAMETER_ID>'
-}
+TODO add events
 ```

docs/dynamic_simulation/index.md

@@ -33,6 +33,7 @@ dynawo-default-parameters:
     solver.parametersFile: <PATH_TO_SOLVER_PARAMETERS_FILE>
     solver.parametersId: id
 ```
+Main parameters are:
 
 **parametersFile**  
 This parameter defines the path of the main parameters file. This file is an XML file that provides, for each dynamic model the characteristics required that are not available in the static network.
@@ -55,23 +56,15 @@ As the `solver.parametersFile` can contain several sets of parameters, the `solv
 To go further, you should read the [Dynawo parameters](dynawo-default-parameters.md) reference page.
 
 ## Dynamic models DSL
-The dynamic models domain specific language helps user to associate a dynamic model to each static components of the network. The following models are supported:
-- LoadAlphaBeta
-- GeneratorSynchronousThreeWindings
-- GeneratorSynchronousThreeWindingsProportionalRegulations
-- GeneratorSynchronousFourWindings
-- GeneratorSynchronousFourWindingsProportionalRegulations
-- OmegaRef
-
-The following automatons models are supported:
-- CurrentLimitAutomaton
+The Dynamic Models DSL is a domain specific language written in groovy for the creation dynamic models used by Dynawo, most of them associated with a static equipment present in the network.
 
 To go further, you should read the [Dynamic Models DSL](dynamic-models-dsl.md) reference page.
 
 ## Event models DSL
 The event models domain specific language helps user to simulate events during the simulation, such as equipment disconnection... The following models are supported:
-- EventQuadripoleDisconnection
-- EventSetPointBoolean
+- Disconnect
+- Step
+- NodeFault
 
 To go further, you should read the [Event Models DSL](event-models-dsl.md) reference page.
 
@@ -119,7 +112,6 @@ curves {
 
 ```{toctree}
 ---
-caption: AA
 maxdepth: 2
 hidden: true
 ---