Add docs

Rename timeOfEvent to contingenciesStartTime Remove timeOfEvent from DynaFlowParameters Signed-off-by: lisrte <[email protected]>
powsybl · Oct 18, 2024 · 68eaf7c · 68eaf7c
1 parent 8bd4d67
commit 68eaf7c
Show file tree

Hide file tree

Showing 17 changed files with 73 additions and 49 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -8,6 +8,7 @@ Powsybl-dynawo is an interface between PowSyBl and [Dynaωo](https://dynawo.gith
 ```{toctree}
 :hidden:
 load_flow/index.md
+security_analysis/index.md
 dynamic_simulation/index.md
 dynamic_security_analysis/index.md
 ```
diff --git a/docs/load_flow/configuration.md b/docs/load_flow/configuration.md
@@ -66,10 +66,6 @@ The default value is `100`.
 **(TODO: description)**  
 The default value is `Nan`.
 
-**timeOfEvent**  
-**(TODO: description)**  
-The default value is `10`.
-
 **chosenOutputs**  
 **(TODO: description)**   
 Available values **(TODO: describe them)**:
@@ -115,7 +111,6 @@ dynaflow-default-parameters:
     startTime: 0.0
     stopTime: 100.0
     precision: 1.0
-    timeOfEvent: 10.0
     chosenOutputs: [ "STEADYSTATE", "LOSTEQ", "TIMELINE", "CONSTRAINTS" ]
     timeStep: 2.6
     mergeLoads: true
@@ -141,9 +136,6 @@ Alternatively, you can provide parameters as a JSON file where supported
       "startTime" : 0.0,
       "stopTime" : 100.0,
       "precision" : 1.0,
-      "sa" : {
-        "timeOfEvent" : 10.0
-      },
       "chosenOutputs" : [ "STEADYSTATE", "LOSTEQ", "TIMELINE", "CONSTRAINTS" ],
       "timeStep" : 2.6,
       "mergeLoads" : true,

diff --git a/docs/security_analysis/configuration.md b/docs/security_analysis/configuration.md
@@ -0,0 +1,28 @@
+# Configuration
+
+The security analysis reuse the `dynaflow` [module](../load_flow/configuration.md#dynaflow-configuration)
+and the `dynaflow-default-parameters` [module](../load_flow/configuration.md#default-parameters).
+
+## Default parameters
+The `dynaflow-security-analysis-default-parameters` module defines the default values for all specific parameters of a security analysis run with DynaFlow.  
+
+### Optional parameters
+
+**contingenciesStartTime**  
+`contingenciesStartTime` defines when the contingencies start, in seconds.  
+The default value of this property is 10.
+
+### Examples
+
+**YAML configuration:**
+```yaml
+dynaflow-security-analysis-default-parameters:
+  contingenciesStartTime: 20
+```
+
+**XML configuration:**
+```xml
+<dynaflow-security-analysis-default-parameters>
+  <contingenciesStartTime>20</contingenciesStartTime>
+</dynaflow-security-analysis-default-parameters>
+```
diff --git a/docs/security_analysis/index.md b/docs/security_analysis/index.md
@@ -0,0 +1,12 @@
+# Dynamic security analysis
+
+```{toctree}
+:hidden:
+configuration.md
+```
+
+PowSyBl provides an implementation of the [SecurityAnalysis API from powsybl-core](inv:powsyblcore:*:*#simulation/security/index) with [DynaFlow](https://dynawo.github.io/about/dynaflow).
+
+## Installation
+
+Read this [documentation page](https://dynawo.github.io/about/dynaflow) to learn how to install and configure DynaFlow.
diff --git a/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowParameters.java b/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowParameters.java
@@ -27,13 +27,13 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-import static com.powsybl.dynaflow.DynaFlowProvider.MODULE_SPECIFIC_PARAMETERS;
-
 /**
  * @author Guillaume Pernin {@literal <guillaume.pernin at rte-france.com>}
  */
 public class DynaFlowParameters extends AbstractExtension<LoadFlowParameters> {
 
+    public static final String MODULE_SPECIFIC_PARAMETERS = "dynaflow-default-parameters";
+
     private static final Logger LOGGER = LoggerFactory.getLogger(DynaFlowParameters.class);
     private static final String CHOSEN_OUTPUT_STRING_DELIMITER = ",";
     private static final String SVC_REGULATION_ON = "svcRegulationOn";

diff --git a/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowProvider.java b/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowProvider.java
@@ -36,8 +36,6 @@
 @AutoService(LoadFlowProvider.class)
 public class DynaFlowProvider implements LoadFlowProvider {
 
-    public static final String MODULE_SPECIFIC_PARAMETERS = "dynaflow-default-parameters";
-
     private static final String WORKING_DIR_PREFIX = "dynaflow_";
 
     private final Supplier<DynaFlowConfig> configSupplier;

diff --git a/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisParameters.java b/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisParameters.java
@@ -18,25 +18,25 @@
 import java.util.Objects;
 import java.util.Optional;
 
-import static com.powsybl.dynaflow.DynaFlowSecurityAnalysisProvider.MODULE_SPECIFIC_PARAMETERS;
-
 /**
  * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
  */
 public class DynaFlowSecurityAnalysisParameters extends AbstractExtension<SecurityAnalysisParameters> {
 
-    private static final double DEFAULT_TIME_OF_EVENT = 10d;
-    private static final String TIME_OF_EVENT = "timeOfEvent";
-    public static final List<String> SPECIFIC_PARAMETER_NAMES = List.of(TIME_OF_EVENT);
+    public static final String MODULE_SPECIFIC_PARAMETERS = "dynaflow-security-analysis-default-parameters";
+
+    private static final double DEFAULT_CONTINGENCIES_START_TIME = 10d;
+    private static final String CONTINGENCIES_START_TIME = "contingenciesStartTime";
+    public static final List<String> SPECIFIC_PARAMETER_NAMES = List.of(CONTINGENCIES_START_TIME);
 
-    private Double timeOfEvent = DEFAULT_TIME_OF_EVENT;
+    private Double contingenciesStartTime = DEFAULT_CONTINGENCIES_START_TIME;
 
-    public Double getTimeOfEvent() {
-        return timeOfEvent;
+    public Double getContingenciesStartTime() {
+        return contingenciesStartTime;
     }
 
-    public DynaFlowSecurityAnalysisParameters setTimeOfEvent(Double timeOfEvent) {
-        this.timeOfEvent = timeOfEvent;
+    public DynaFlowSecurityAnalysisParameters setContingenciesStartTime(Double contingenciesStartTime) {
+        this.contingenciesStartTime = contingenciesStartTime;
         return this;
     }
 
@@ -48,7 +48,7 @@ public String getName() {
     @Override
     public String toString() {
         return MoreObjects.toStringHelper("").omitNullValues()
-                .add(TIME_OF_EVENT, timeOfEvent).toString();
+                .add(CONTINGENCIES_START_TIME, contingenciesStartTime).toString();
     }
 
     public static DynaFlowSecurityAnalysisParameters load(PlatformConfig platformConfig) {
@@ -74,11 +74,11 @@ public static DynaFlowSecurityAnalysisParameters load(Map<String, String> proper
     }
 
     private static void load(DynaFlowSecurityAnalysisParameters parameters, ModuleConfig config) {
-        config.getOptionalDoubleProperty(TIME_OF_EVENT).ifPresent(parameters::setTimeOfEvent);
+        config.getOptionalDoubleProperty(CONTINGENCIES_START_TIME).ifPresent(parameters::setContingenciesStartTime);
     }
 
     public void update(Map<String, String> properties) {
         Objects.requireNonNull(properties);
-        Optional.ofNullable(properties.get(TIME_OF_EVENT)).ifPresent(prop -> setTimeOfEvent(Double.parseDouble(prop)));
+        Optional.ofNullable(properties.get(CONTINGENCIES_START_TIME)).ifPresent(prop -> setContingenciesStartTime(Double.parseDouble(prop)));
     }
 }
diff --git a/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisProvider.java b/dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisProvider.java
@@ -41,7 +41,6 @@
 @AutoService(SecurityAnalysisProvider.class)
 public class DynaFlowSecurityAnalysisProvider implements SecurityAnalysisProvider {
 
-    public static final String MODULE_SPECIFIC_PARAMETERS = "dynaflow-security-analysis-default-parameters";
     private static final Logger LOG = LoggerFactory.getLogger(DynaFlowSecurityAnalysisProvider.class);
     private static final String WORKING_DIR_PREFIX = "dynaflow_sa_";
     private final Supplier<DynaFlowConfig> configSupplier;

diff --git a/dynaflow/src/main/java/com/powsybl/dynaflow/json/DynaFlowConfigSerializer.java b/dynaflow/src/main/java/com/powsybl/dynaflow/json/DynaFlowConfigSerializer.java
@@ -102,7 +102,7 @@ private static void serialize(LoadFlowParameters lfParameters, JsonGenerator jso
 
     private static void serialize(DynaFlowSecurityAnalysisParameters saParameters, JsonGenerator jsonGenerator) throws IOException {
         jsonGenerator.writeObjectFieldStart("sa");
-        jsonGenerator.writeNumberField("TimeOfEvent", saParameters.getTimeOfEvent());
+        jsonGenerator.writeNumberField("TimeOfEvent", saParameters.getContingenciesStartTime());
         jsonGenerator.writeEndObject();
     }
 

diff --git a/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowParametersTest.java b/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowParametersTest.java
@@ -27,7 +27,7 @@
 import java.util.*;
 
 import static com.powsybl.commons.test.ComparisonUtils.assertTxtEquals;
-import static com.powsybl.dynaflow.DynaFlowProvider.MODULE_SPECIFIC_PARAMETERS;
+import static com.powsybl.dynaflow.DynaFlowParameters.MODULE_SPECIFIC_PARAMETERS;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -64,7 +64,6 @@ void checkParameters() {
         double startTime = 0.;
         double stopTime = 100.;
         double precision = 15.45;
-        double timeOfEvent = 14.;
         List<String> chosenOutputs = List.of(OutputTypes.STEADYSTATE.name(), OutputTypes.TIMELINE.name());
         double timeStep = 0;
         StartingPointMode startingPointMode = StartingPointMode.FLAT;
@@ -81,7 +80,6 @@ void checkParameters() {
         moduleConfig.setStringProperty("startTime", Double.toString(startTime));
         moduleConfig.setStringProperty("stopTime", Double.toString(stopTime));
         moduleConfig.setStringProperty("precision", Double.toString(precision));
-        moduleConfig.setStringProperty("timeOfEvent", Double.toString(timeOfEvent));
         moduleConfig.setStringListProperty("chosenOutputs", chosenOutputs);
         moduleConfig.setStringProperty("timeStep", Double.toString(timeStep));
         moduleConfig.setStringProperty("startingPointMode", startingPointMode.getName());
@@ -144,7 +142,6 @@ void checkAllParametersAssignedToString() {
         double startTime = 0.;
         double stopTime = 100.;
         double precision = 15.45;
-        double timeOfEvent = 10.;
         List<String> chosenOutputs = Arrays.asList(OutputTypes.STEADYSTATE.name(), OutputTypes.TIMELINE.name());
         double timeStep = 0;
         StartingPointMode startingPointMode = StartingPointMode.WARM;
@@ -161,7 +158,6 @@ void checkAllParametersAssignedToString() {
         properties.put("startTime", Double.toString(startTime));
         properties.put("stopTime", Double.toString(stopTime));
         properties.put("precision", Double.toString(precision));
-        properties.put("timeOfEvent", Double.toString(timeOfEvent));
         properties.put("chosenOutputs", OutputTypes.STEADYSTATE.name() + "," + OutputTypes.TIMELINE.name());
         properties.put("timeStep", Double.toString(timeStep));
         properties.put("startingPointMode", startingPointMode.name());
@@ -254,7 +250,6 @@ void loadMapDynaflowParameters() {
         double startTime = 0.;
         double stopTime = 100.;
         double precision = 15.45;
-        double timeOfEvent = 10.;
         Set<OutputTypes> chosenOutputs = Set.of(OutputTypes.STEADYSTATE, OutputTypes.TIMELINE);
         double timeStep = 0;
         StartingPointMode startingPointMode = StartingPointMode.WARM;
@@ -271,7 +266,6 @@ void loadMapDynaflowParameters() {
         properties.put("startTime", Double.toString(startTime));
         properties.put("stopTime", Double.toString(stopTime));
         properties.put("precision", Double.toString(precision));
-        properties.put("timeOfEvent", Double.toString(timeOfEvent));
         properties.put("chosenOutputs", "STEADYSTATE, TIMELINE");
         properties.put("timeStep", Double.toString(timeStep));
         properties.put("startingPointMode", startingPointMode.getName());

diff --git a/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisParametersTest.java b/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisParametersTest.java
@@ -25,7 +25,7 @@
 import java.util.Map;
 
 import static com.powsybl.commons.test.ComparisonUtils.assertTxtEquals;
-import static com.powsybl.dynaflow.DynaFlowSecurityAnalysisProvider.MODULE_SPECIFIC_PARAMETERS;
+import static com.powsybl.dynaflow.DynaFlowSecurityAnalysisParameters.MODULE_SPECIFIC_PARAMETERS;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 
@@ -51,18 +51,18 @@ public void tearDown() throws IOException {
 
     @Test
     void checkParameters() {
-        double timeOfEvent = 24.;
+        double contingenciesStartTime = 24.;
         MapModuleConfig moduleConfig = platformConfig.createModuleConfig(MODULE_SPECIFIC_PARAMETERS);
-        moduleConfig.setStringProperty("timeOfEvent", Double.toString(timeOfEvent));
+        moduleConfig.setStringProperty("contingenciesStartTime", Double.toString(contingenciesStartTime));
         DynaFlowSecurityAnalysisParameters saParam = DynaFlowSecurityAnalysisParameters.load(moduleConfig);
-        assertEquals(timeOfEvent, saParam.getTimeOfEvent());
+        assertEquals(contingenciesStartTime, saParam.getContingenciesStartTime());
     }
 
     @Test
     void checkAllParametersAssignedToString() {
         DynaFlowSecurityAnalysisParameters saParam = new DynaFlowSecurityAnalysisParameters();
-        saParam.update(Map.of("timeOfEvent", Double.toString(23d)));
-        assertEquals("{timeOfEvent=23.0}", saParam.toString());
+        saParam.update(Map.of("contingenciesStartTime", Double.toString(23d)));
+        assertEquals("{contingenciesStartTime=23.0}", saParam.toString());
     }
 
     @Test
@@ -85,7 +85,7 @@ void defaultParametersSerialization() throws IOException {
     @Test
     void parametersSerialization() throws IOException {
         DynaFlowSecurityAnalysisParameters saParam = new DynaFlowSecurityAnalysisParameters()
-                .setTimeOfEvent(20d);
+                .setContingenciesStartTime(20d);
         Path workingDir = fileSystem.getPath("dynaflow_sa/workingDir");
         Path parameterFile = fileSystem.getPath(DynaFlowConstants.CONFIG_FILENAME);
         DynaFlowConfigSerializer.serialize(LoadFlowParameters.load(platformConfig),

diff --git a/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisTest.java b/dynaflow/src/test/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisTest.java
@@ -140,12 +140,12 @@ void testCallingBadVersionDynawo() throws IOException {
     @Test
     void loadDynaflowParameters() {
         DynaFlowSecurityAnalysisProvider provider = new DynaFlowSecurityAnalysisProvider();
-        Map<String, String> properties = Map.of("timeOfEvent", Double.toString(23d));
+        Map<String, String> properties = Map.of("contingenciesStartTime", Double.toString(23d));
         assertThat(provider.loadSpecificParameters(properties))
                 .isNotEmpty()
                 .get()
                 .isInstanceOf(DynaFlowSecurityAnalysisParameters.class)
-                .hasFieldOrPropertyWithValue("timeOfEvent", 23.);
+                .hasFieldOrPropertyWithValue("contingenciesStartTime", 23.);
 
     }
 

diff --git a/dynaflow/src/test/java/com/powsybl/dynaflow/json/JsonDynaFlowSaParametersSerializerTest.java b/dynaflow/src/test/java/com/powsybl/dynaflow/json/JsonDynaFlowSaParametersSerializerTest.java
@@ -29,7 +29,7 @@ void roundTripParameters() throws IOException {
         InMemoryPlatformConfig platformConfig = new InMemoryPlatformConfig(fileSystem);
         SecurityAnalysisParameters parameters = SecurityAnalysisParameters.load(platformConfig);
         DynaFlowSecurityAnalysisParameters params = new DynaFlowSecurityAnalysisParameters()
-                .setTimeOfEvent(23.);
+                .setContingenciesStartTime(23.);
         parameters.addExtension(DynaFlowSecurityAnalysisParameters.class, params);
 
         roundTripTest(parameters, JsonSecurityAnalysisParameters::write,
@@ -50,6 +50,6 @@ void update() {
         JsonSecurityAnalysisParameters.update(parameters, getClass().getResourceAsStream("/dynaflow_sa_update.json"));
         DynaFlowSecurityAnalysisParameters dynaFlowSaParameters = parameters.getExtension(DynaFlowSecurityAnalysisParameters.class);
         assertNotNull(dynaFlowSaParameters);
-        assertEquals(14., dynaFlowSaParameters.getTimeOfEvent());
+        assertEquals(14., dynaFlowSaParameters.getContingenciesStartTime());
     }
 }
diff --git a/dynaflow/src/test/resources/dynaflow_sa_default_serialization.json b/dynaflow/src/test/resources/dynaflow_sa_default_serialization.json
@@ -44,7 +44,7 @@
   },
   "extensions" : {
     "DynaFlowSecurityAnalysisParameters" : {
-      "timeOfEvent" : 10.0
+      "contingenciesStartTime" : 10.0
     }
   }
 }
diff --git a/dynaflow/src/test/resources/dynaflow_sa_parameters_set_serialization.json b/dynaflow/src/test/resources/dynaflow_sa_parameters_set_serialization.json
@@ -44,7 +44,7 @@
   },
   "extensions" : {
     "DynaFlowSecurityAnalysisParameters" : {
-      "timeOfEvent" : 23.0
+      "contingenciesStartTime" : 23.0
     }
   }
 }
diff --git a/dynaflow/src/test/resources/dynaflow_sa_update.json b/dynaflow/src/test/resources/dynaflow_sa_update.json
@@ -29,7 +29,7 @@
   },
   "extensions" : {
     "DynaFlowSecurityAnalysisParameters" : {
-      "timeOfEvent" : 14.0
+      "contingenciesStartTime" : 14.0
     }
   }
 }
diff --git a/dynawo-integration-tests/src/test/java/com/powsybl/dynawo/it/DynaFlowTest.java b/dynawo-integration-tests/src/test/java/com/powsybl/dynawo/it/DynaFlowTest.java
@@ -62,7 +62,7 @@ void setUp() throws Exception {
         securityAnalysisParameters = new SecurityAnalysisParameters();
         loadFlowParameters.addExtension(DynaFlowParameters.class, new DynaFlowParameters());
         securityAnalysisParameters.addExtension(DynaFlowSecurityAnalysisParameters.class,
-                new DynaFlowSecurityAnalysisParameters().setTimeOfEvent(15.));
+                new DynaFlowSecurityAnalysisParameters().setContingenciesStartTime(15.));
     }
 
     @Test