[Shortcircuit] Add new parameters (#2638)

Signed-off-by: Coline PILOQUET <coline.piloquet@rte-france.com>

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java

@@ -7,26 +7,36 @@
 package com.powsybl.shortcircuit;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.powsybl.commons.PowsyblException;
 import com.powsybl.commons.json.JsonUtil;
 import com.powsybl.shortcircuit.json.ShortCircuitAnalysisJsonModule;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.io.UncheckedIOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Objects;
 
+import static com.powsybl.shortcircuit.VoltageRange.checkVoltageRange;
+
 /**
  * @author Thomas Adam <tadam at silicom.fr>
  */
 public class FaultParameters {
 
+    private static final Logger LOGGER = LoggerFactory.getLogger(FaultParameters.class);
+
     // VERSION = 1.0 withLimitViolations, withVoltageMap, withFeederResult, studyType and minVoltageDropProportionalThreshold
     // VERSION = 1.1 withVoltageMap -> withFortescueResult and withVoltageResult
-    public static final String VERSION = "1.1";
+    // VERSION = 1.2 subTransientCoefficient, withLoads, withShuntCompensators, withVSCConverterStations, withNeutralPosition,
+    //                initialVoltageProfileMode, voltageRanges
+    public static final String VERSION = "1.2";
 
     private final String id;
 
@@ -42,6 +52,20 @@ public class FaultParameters {
 
     private final double minVoltageDropProportionalThreshold;
 
+    private final double subTransientCoefficient;
+
+    private final boolean withLoads;
+
+    private final boolean withShuntCompensators;
+
+    private final boolean withVSCConverterStations;
+
+    private final boolean withNeutralPosition;
+
+    private final InitialVoltageProfileMode initialVoltageProfileMode;
+
+    private final List<VoltageRange> voltageRanges;
+
     /** Fault id */
     public String getId() {
         return id;
@@ -77,20 +101,85 @@ public double getMinVoltageDropProportionalThreshold() {
         return minVoltageDropProportionalThreshold;
     }
 
+    /** Override general parameter subTransientCoefficient from {@link ShortCircuitParameters} */
+    public double getSubTransientCoefficient() {
+        return subTransientCoefficient;
+    }
+
+    /** Override general parameter withLoads from {@link com.powsybl.shortcircuit.ShortCircuitParameters} */
+    public boolean isWithLoads() {
+        return withLoads;
+    }
+
+    /** Override general parameter withShuntCompensators from {@link com.powsybl.shortcircuit.ShortCircuitParameters} */
+    public boolean isWithShuntCompensators() {
+        return withShuntCompensators;
+    }
+
+    /** Override general parameter withVSCConverterStations from {@link com.powsybl.shortcircuit.ShortCircuitParameters} */
+    public boolean isWithVSCConverterStations() {
+        return withVSCConverterStations;
+    }
+
+    /** Override general parameter withNeutralPosition from {@link com.powsybl.shortcircuit.ShortCircuitParameters} */
+    public boolean isWithNeutralPosition() {
+        return withNeutralPosition;
+    }
+
+    /** Override general parameter initialVoltageProfileMode from {@link com.powsybl.shortcircuit.ShortCircuitParameters} */
+    public InitialVoltageProfileMode getInitialVoltageProfileMode() {
+        return initialVoltageProfileMode;
+    }
+
+    /** Override general parameter voltageRanges from {@link ShortCircuitParameters}*/
+    public List<VoltageRange> getVoltageRanges() {
+        return voltageRanges;
+    }
+
     public FaultParameters(String id,
                            boolean withLimitViolations,
                            boolean withVoltageResult,
                            boolean withFeederResult,
                            StudyType studyType,
                            double minVoltageDropProportionalThreshold,
-                           boolean withFortescueResult) {
+                           boolean withFortescueResult,
+                           double subTransientCoefficient,
+                           boolean withLoads,
+                           boolean withShuntCompensators,
+                           boolean withVSCConverterStations,
+                           boolean withNeutralPosition,
+                           InitialVoltageProfileMode initialVoltageProfileMode,
+                           List<VoltageRange> voltageRanges) {
         this.id = Objects.requireNonNull(id);
         this.withLimitViolations = withLimitViolations;
         this.withVoltageResult = withVoltageResult;
         this.withFeederResult = withFeederResult;
         this.studyType = studyType;
         this.minVoltageDropProportionalThreshold = minVoltageDropProportionalThreshold;
         this.withFortescueResult = withFortescueResult;
+        this.subTransientCoefficient = checkSubTransientCoefficient(subTransientCoefficient);
+        this.withLoads = withLoads;
+        this.withShuntCompensators = withShuntCompensators;
+        this.withVSCConverterStations = withVSCConverterStations;
+        this.withNeutralPosition = withNeutralPosition;
+        this.initialVoltageProfileMode = initialVoltageProfileMode;
+        this.voltageRanges = new ArrayList<>();
+        if (voltageRanges != null) {
+            if (initialVoltageProfileMode == InitialVoltageProfileMode.CONFIGURED) {
+                checkVoltageRange(voltageRanges);
+                this.voltageRanges.addAll(voltageRanges);
+            } else {
+                LOGGER.warn("Nominal voltage ranges with associated coefficient are defined but InitialVoltageProfileMode is not CONFIGURED: they are ignored");
+            }
+        }
+        this.validate();
+    }
+
+    private double checkSubTransientCoefficient(double subTransientCoefficient) {
+        if (subTransientCoefficient > 1) {
+            throw new PowsyblException("subTransientCoefficient > 1");
+        }
+        return subTransientCoefficient;
     }
 
     @Override
@@ -108,12 +197,22 @@ public boolean equals(Object o) {
                 Objects.equals(withFeederResult, that.withFeederResult) &&
                 Objects.equals(studyType, that.studyType) &&
                 Objects.equals(minVoltageDropProportionalThreshold, that.minVoltageDropProportionalThreshold) &&
-                Objects.equals(withFortescueResult, that.withFortescueResult);
+                Objects.equals(withFortescueResult, that.withFortescueResult) &&
+                Objects.equals(subTransientCoefficient, that.subTransientCoefficient) &&
+                Objects.equals(withLoads, that.withLoads) &&
+                Objects.equals(withShuntCompensators, that.withShuntCompensators) &&
+                Objects.equals(withVSCConverterStations, that.withVSCConverterStations) &&
+                Objects.equals(withNeutralPosition, that.withNeutralPosition) &&
+                Objects.equals(initialVoltageProfileMode, that.initialVoltageProfileMode) &&
+                Objects.equals(voltageRanges, that.voltageRanges);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(id, withLimitViolations, withVoltageResult, withFeederResult, studyType, minVoltageDropProportionalThreshold, withFortescueResult);
+        return Objects.hash(id, withLimitViolations, withVoltageResult, withFeederResult, studyType,
+                minVoltageDropProportionalThreshold, withFortescueResult, subTransientCoefficient,
+                withLoads, withShuntCompensators, withVSCConverterStations, withNeutralPosition,
+                initialVoltageProfileMode, voltageRanges);
     }
 
     @Override
@@ -126,6 +225,13 @@ public String toString() {
                 ", studyType=" + studyType +
                 ", minVoltageDropProportionalThreshold=" + minVoltageDropProportionalThreshold +
                 ", withFortescueResult=" + withFortescueResult +
+                ", subTransientCoefficient=" + subTransientCoefficient +
+                ", withLoads=" + withLoads +
+                ", withShuntCompensators=" + withShuntCompensators +
+                ", withVSCConverterStations=" + withVSCConverterStations +
+                ", withNeutralPosition=" + withNeutralPosition +
+                ", initialVoltageProfileMode=" + initialVoltageProfileMode +
+                ", voltageRanges=" + voltageRanges +
                 '}';
     }
 
@@ -148,4 +254,10 @@ public static List<FaultParameters> read(Path jsonFile) {
             throw new UncheckedIOException(e);
         }
     }
+
+    public void validate() {
+        if (initialVoltageProfileMode == InitialVoltageProfileMode.CONFIGURED && (voltageRanges == null || voltageRanges.isEmpty())) {
+            throw new PowsyblException("Configured initial voltage profile but nominal voltage ranges with associated coefficients are missing.");
+        }
+    }
 }

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2023, RTE (http://www.rte-france.com)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+package com.powsybl.shortcircuit;
+
+/**
+ * @author Coline Piloquet <coline.piloquet at rte-france.com>
+ */
+public enum InitialVoltageProfileMode {
+    NOMINAL,
+    CONFIGURED, // Voltage profile given by the user
+    PREVIOUS_VALUE // Voltage profile from the loadflow
+
+}

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitAnalysis.java

@@ -54,6 +54,7 @@ public CompletableFuture<ShortCircuitAnalysisResult> runAsync(Network network,
             Objects.requireNonNull(computationManager, NOT_NULL_COMPUTATION_MANAGER_MESSAGE);
             Objects.requireNonNull(parameters, NOT_NULL_PARAMETERS_MESSAGE);
             Objects.requireNonNull(reporter, "Reporter should not be null");
+            validateParameters(parameters);
             return provider.run(network, faults, parameters, computationManager, faultParameters, reporter);
         }
 
@@ -66,9 +67,14 @@ public CompletableFuture<ShortCircuitAnalysisResult> runAsync(Network network,
             Objects.requireNonNull(faults, NOT_NULL_FAULT_MESSAGE);
             Objects.requireNonNull(computationManager, NOT_NULL_COMPUTATION_MANAGER_MESSAGE);
             Objects.requireNonNull(parameters, NOT_NULL_PARAMETERS_MESSAGE);
+            validateParameters(parameters);
             return provider.run(network, faults, parameters, computationManager, faultParameters);
         }
 
+        private void validateParameters(ShortCircuitParameters shortCircuitParameters) {
+            shortCircuitParameters.validate();
+        }
+
         public ShortCircuitAnalysisResult run(Network network, List<Fault> faults,
                                               ShortCircuitParameters parameters,
                                               ComputationManager computationManager,

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitAnalysisResult.java

@@ -19,7 +19,7 @@
 public class ShortCircuitAnalysisResult extends AbstractExtendable<ShortCircuitAnalysisResult> {
 
     // VERSION = 1.0 faultResults
-    // VERSION = 1.0 status in faultResult
+    // VERSION = 1.1 status in faultResult
     public static final String VERSION = "1.1";
 
     private final Map<String, FaultResult> resultByFaultId = new TreeMap<>();

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/ShortCircuitConstants.java

@@ -20,4 +20,10 @@ private ShortCircuitConstants() {
     public static final boolean DEFAULT_WITH_FEEDER_RESULT = true;
     public static final double DEFAULT_MIN_VOLTAGE_DROP_PROPORTIONAL_THRESHOLD = 0.0;
     public static final boolean DEFAULT_WITH_FORTESCUE_RESULT = true;
+    public static final double DEFAULT_SUB_TRANSIENT_COEFFICIENT = 0.7;
+    public static final boolean DEFAULT_WITH_LOADS = true;
+    public static final boolean DEFAULT_WITH_SHUNT_COMPENSATORS = true;
+    public static final boolean DEFAULT_WITH_VSC_CONVERTER_STATIONS = true;
+    public static final boolean DEFAULT_WITH_NEUTRAL_POSITION = false;
+    public static final InitialVoltageProfileMode DEFAULT_INITIAL_VOLTAGE_PROFILE_MODE = InitialVoltageProfileMode.NOMINAL;
 }