Add DynaFlow Security Analysis Parameters

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
 ```

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)**:
@@ -80,12 +76,14 @@ Available values **(TODO: describe them)**:
 
 The default value is a list of all of them.
 
+(timeStepDef)= 
+
 **timeStep**  
-**(TODO: description)**  
+`timeStep` defines the maximum time solver step value (in s).
 The default value is `10`.
 
 **mergeLoads**  
-`mergeLoads` is used to indicates if loads connected to the same bus are merged.  
+`mergeLoads` indicates if loads connected to the same bus are merged.  
 The default value is `TRUE`.
 
 **startingPointMode**  
@@ -115,7 +113,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 +138,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,

docs/security_analysis/configuration.md

@@ -0,0 +1,29 @@
+# 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.
+If the start time occurs between two [time steps](timeStepDef) the contingencies will start on the next time step.
+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>
+```

docs/security_analysis/index.md

@@ -0,0 +1,12 @@
+# 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.

dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowParameters.java

@@ -6,8 +6,6 @@
  */
 package com.powsybl.dynaflow;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.fasterxml.jackson.core.JsonGenerator;
 import com.google.common.base.MoreObjects;
 import com.powsybl.commons.config.ModuleConfig;
 import com.powsybl.commons.config.PlatformConfig;
@@ -24,59 +22,19 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import java.io.IOException;
 import java.util.*;
 import java.util.function.BiConsumer;
 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> {
 
-    private static final Logger LOGGER = LoggerFactory.getLogger(DynaFlowParameters.class);
-
-    /**
-     * Inner class dedicated to Security Analysis (SA) namespace
-     */
-    public static class Sa {
-        private static final String SECURITY_ANALYSIS = "sa"; //Security analysis
-        private static final double DEFAULT_TIME_OF_EVENT = 10d;
-        protected static final String TIME_OF_EVENT = "timeOfEvent";
-
-        private Double timeOfEvent = DEFAULT_TIME_OF_EVENT;
-
-        public Double getTimeOfEvent() {
-            return timeOfEvent;
-        }
-
-        public void setTimeOfEvent(Double timeOfEvent) {
-            this.timeOfEvent = timeOfEvent;
-        }
-
-        @Override
-        public String toString() {
-            return MoreObjects.toStringHelper("").omitNullValues()
-                    .add(TIME_OF_EVENT, timeOfEvent).toString();
-        }
-
-        public static void writeJson(JsonGenerator jsonGenerator, DynaFlowParameters dynaFlowParameters) throws IOException {
-            if (dynaFlowParameters.getSa().isSerializable()) {
-                jsonGenerator.writeObjectFieldStart("sa");
-                jsonGenerator.writeNumberField("TimeOfEvent", dynaFlowParameters.getTimeOfEvent());
-                jsonGenerator.writeEndObject();
-            }
-        }
-
-        @JsonIgnore
-        public boolean isSerializable() {
-            return timeOfEvent != null;
-        }
-    }
+    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";
     private static final String SHUNT_REGULATION_ON = "shuntRegulationOn";
@@ -122,7 +80,6 @@ private static <E extends Enum<E>> List<Object> getEnumPossibleValues(Class<E> e
             new Parameter(START_TIME, ParameterType.DOUBLE, "Start time", DEFAULT_START_TIME),
             new Parameter(STOP_TIME, ParameterType.DOUBLE, "Stop time", DEFAULT_STOP_TIME),
             new Parameter(PRECISION_NAME, ParameterType.DOUBLE, "Precision", DEFAULT_PRECISION),
-            new Parameter(Sa.TIME_OF_EVENT, ParameterType.DOUBLE, "Time of event", Sa.DEFAULT_TIME_OF_EVENT),
             new Parameter(CHOSEN_OUTPUTS, ParameterType.STRING_LIST, "Chosen outputs", DEFAULT_CHOSEN_OUTPUTS.stream().map(OutputTypes::name).toList(), getEnumPossibleValues(OutputTypes.class), ParameterScope.TECHNICAL),
             new Parameter(TIME_STEP, ParameterType.DOUBLE, "Time step", DEFAULT_TIME_STEP),
             new Parameter(STARTING_POINT_MODE, ParameterType.STRING, "Starting point mode", DEFAULT_STARTING_POINT_MODE.name(), getEnumPossibleValues(StartingPointMode.class)),
@@ -138,7 +95,6 @@ private static <E extends Enum<E>> List<Object> getEnumPossibleValues(Class<E> e
     private double startTime = DEFAULT_START_TIME;
     private double stopTime = DEFAULT_STOP_TIME;
     private Double precision = null;
-    private Sa securityAnalysis = null;
     private EnumSet<OutputTypes> chosenOutputs = DEFAULT_CHOSEN_OUTPUTS;
     private double timeStep = DEFAULT_TIME_STEP;
     private StartingPointMode startingPointMode = DEFAULT_STARTING_POINT_MODE;
@@ -234,19 +190,6 @@ public DynaFlowParameters setPrecision(Double precision) {
         return this;
     }
 
-    @JsonIgnore
-    public Double getTimeOfEvent() {
-        return securityAnalysis == null ? null : securityAnalysis.getTimeOfEvent();
-    }
-
-    public DynaFlowParameters setTimeOfEvent(Double timeOfEvent) {
-        if (this.securityAnalysis == null) {
-            securityAnalysis = new Sa();
-        }
-        securityAnalysis.setTimeOfEvent(timeOfEvent);
-        return this;
-    }
-
     public Set<OutputTypes> getChosenOutputs() {
         return chosenOutputs;
     }
@@ -279,15 +222,6 @@ public DynaFlowParameters setStartingPointMode(StartingPointMode startingPointMo
         return this;
     }
 
-    public Sa getSa() {
-        return this.securityAnalysis;
-    }
-
-    public DynaFlowParameters setSa(Sa securityAnalysis) {
-        this.securityAnalysis = securityAnalysis;
-        return this;
-    }
-
     public boolean isMergeLoads() {
         return mergeLoads;
     }
@@ -315,7 +249,6 @@ public String toString() {
                 .add(START_TIME, startTime)
                 .add(STOP_TIME, stopTime)
                 .add(PRECISION_NAME, precision)
-                .add(Sa.SECURITY_ANALYSIS, securityAnalysis)
                 .add(CHOSEN_OUTPUTS, chosenOutputs)
                 .add(TIME_STEP, timeStep)
                 .add(STARTING_POINT_MODE, startingPointMode)
@@ -326,10 +259,8 @@ public String toString() {
     public static DynaFlowParameters load(PlatformConfig platformConfig) {
         Objects.requireNonNull(platformConfig);
         DynaFlowParameters parameters = new DynaFlowParameters();
-
         platformConfig.getOptionalModuleConfig(MODULE_SPECIFIC_PARAMETERS)
                 .ifPresent(config -> load(parameters, config));
-
         return parameters;
     }
 
@@ -341,6 +272,12 @@ public static DynaFlowParameters load(ModuleConfig config) {
         return parameters;
     }
 
+    public static DynaFlowParameters load(Map<String, String> properties) {
+        DynaFlowParameters parameters = new DynaFlowParameters();
+        parameters.update(properties);
+        return parameters;
+    }
+
     private static void load(DynaFlowParameters parameters, ModuleConfig config) {
         config.getOptionalBooleanProperty(SVC_REGULATION_ON).ifPresent(parameters::setSvcRegulationOn);
         config.getOptionalBooleanProperty(SHUNT_REGULATION_ON).ifPresent(parameters::setShuntRegulationOn);
@@ -352,7 +289,6 @@ private static void load(DynaFlowParameters parameters, ModuleConfig config) {
         config.getOptionalDoubleProperty(START_TIME).ifPresent(parameters::setStartTime);
         config.getOptionalDoubleProperty(STOP_TIME).ifPresent(parameters::setStopTime);
         config.getOptionalDoubleProperty(PRECISION_NAME).ifPresent(parameters::setPrecision);
-        config.getOptionalDoubleProperty(Sa.TIME_OF_EVENT).ifPresent(parameters::setTimeOfEvent);
         config.getOptionalEnumSetProperty(CHOSEN_OUTPUTS, OutputTypes.class).ifPresent(parameters::setChosenOutputs);
         config.getOptionalDoubleProperty(TIME_STEP).ifPresent(parameters::setTimeStep);
         config.getOptionalStringProperty(STARTING_POINT_MODE).map(StartingPointMode::fromString).ifPresent(parameters::setStartingPointMode);
@@ -390,12 +326,6 @@ public void update(Map<String, String> properties) {
         Optional.ofNullable(properties.get(START_TIME)).ifPresent(prop -> setStartTime(Double.parseDouble(prop)));
         Optional.ofNullable(properties.get(STOP_TIME)).ifPresent(prop -> setStopTime(Double.parseDouble(prop)));
         Optional.ofNullable(properties.get(PRECISION_NAME)).ifPresent(prop -> setPrecision(Double.parseDouble(prop)));
-        Optional.ofNullable(properties.get(Sa.TIME_OF_EVENT)).ifPresent(prop -> {
-            if (securityAnalysis == null) {
-                securityAnalysis = new Sa();
-            }
-            securityAnalysis.setTimeOfEvent(Double.parseDouble(prop));
-        });
         Optional.ofNullable(properties.get(CHOSEN_OUTPUTS)).ifPresent(prop ->
                 setChosenOutputs(Stream.of(prop.split(CHOSEN_OUTPUT_STRING_DELIMITER)).map(o -> OutputTypes.valueOf(o.trim())).collect(Collectors.toSet())));
         Optional.ofNullable(properties.get(TIME_STEP)).ifPresent(prop -> setTimeStep(Double.parseDouble(prop)));
@@ -417,7 +347,6 @@ public Map<String, String> createMapFromParameters() {
         addNotNullEntry(START_TIME, startTime, parameters::put);
         addNotNullEntry(STOP_TIME, stopTime, parameters::put);
         addNotNullEntry(PRECISION_NAME, precision, parameters::put);
-        addNotNullEntry(Sa.TIME_OF_EVENT, getTimeOfEvent(), parameters::put);
         if (!chosenOutputs.isEmpty()) {
             parameters.put(CHOSEN_OUTPUTS, String.join(CHOSEN_OUTPUT_STRING_DELIMITER, chosenOutputs.stream().map(OutputTypes::name).toList()));
         }
@@ -432,10 +361,4 @@ private void addNotNullEntry(String key, Object value, BiConsumer<String, String
             adder.accept(key, Objects.toString(value));
         }
     }
-
-    public static DynaFlowParameters load(Map<String, String> properties) {
-        DynaFlowParameters parameters = new DynaFlowParameters();
-        parameters.update(properties);
-        return parameters;
-    }
 }

dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowProvider.java

@@ -39,8 +39,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;
@@ -74,10 +72,10 @@ public static Command getVersionCommand(DynaFlowConfig config) {
                 .build();
     }
 
-    private static DynaFlowParameters getParametersExt(LoadFlowParameters parameters) {
+    static DynaFlowParameters getParametersExt(LoadFlowParameters parameters) {
         DynaFlowParameters parametersExt = parameters.getExtension(DynaFlowParameters.class);
         if (parametersExt == null) {
-            parametersExt = new DynaFlowParameters();
+            return new DynaFlowParameters();
         }
         return parametersExt;
     }
@@ -140,7 +138,7 @@ public List<Parameter> getSpecificParameters() {
 
     @Override
     public Optional<ModuleConfig> getModuleConfig(PlatformConfig platformConfig) {
-        return platformConfig.getOptionalModuleConfig(MODULE_SPECIFIC_PARAMETERS);
+        return platformConfig.getOptionalModuleConfig(DynaFlowParameters.MODULE_SPECIFIC_PARAMETERS);
     }
 
     @Override

dynaflow/src/main/java/com/powsybl/dynaflow/DynaFlowSecurityAnalysisHandler.java

@@ -106,15 +106,9 @@ private static void writeContingencies(List<Contingency> contingencies, Path wor
     private static void writeParameters(SecurityAnalysisParameters securityAnalysisParameters, Path workingDir) throws IOException {
         // TODO(Luma) Take into account also Security Analysis parameters
         LoadFlowParameters loadFlowParameters = securityAnalysisParameters.getLoadFlowParameters();
-        DynaFlowParameters dynaFlowParameters = getParametersExt(loadFlowParameters);
-        DynaFlowConfigSerializer.serialize(loadFlowParameters, dynaFlowParameters, Path.of("."), workingDir.resolve(CONFIG_FILENAME));
-    }
-
-    private static DynaFlowParameters getParametersExt(LoadFlowParameters parameters) {
-        DynaFlowParameters parametersExt = parameters.getExtension(DynaFlowParameters.class);
-        if (parametersExt == null) {
-            parametersExt = new DynaFlowParameters();
-        }
-        return parametersExt;
+        DynaFlowParameters dynaFlowParameters = DynaFlowProvider.getParametersExt(loadFlowParameters);
+        DynaFlowSecurityAnalysisParameters dynaFlowSecurityAnalysisParameters = DynaFlowSecurityAnalysisProvider.getParametersExt(securityAnalysisParameters);
+        DynaFlowConfigSerializer.serialize(loadFlowParameters, dynaFlowParameters, dynaFlowSecurityAnalysisParameters,
+                Path.of("."), workingDir.resolve(CONFIG_FILENAME));
     }
 }