Create rescale mode for flow decomposition

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/CsvExporter.java

@@ -85,7 +85,8 @@ private void printHeaderRow(Set<String> loopFlowKeys, CSVPrinter printer) {
         failSilentlyPrint(printer, DecomposedFlow.INTERNAL_COLUMN_NAME);
         failSilentlyPrint(printer, DecomposedFlow.PST_COLUMN_NAME);
         loopFlowKeys.stream().sorted().forEach(loopFlowKey -> failSilentlyPrint(printer, loopFlowKey));
-        failSilentlyPrint(printer, DecomposedFlow.AC_REFERENCE_FLOW_COLUMN_NAME);
+        failSilentlyPrint(printer, DecomposedFlow.AC_REFERENCE_FLOW_1_COLUMN_NAME);
+        failSilentlyPrint(printer, DecomposedFlow.AC_REFERENCE_FLOW_2_COLUMN_NAME);
         failSilentlyPrint(printer, DecomposedFlow.DC_REFERENCE_FLOW_COLUMN_NAME);
         failSilentlyPrintLn(printer);
     }
@@ -100,7 +101,8 @@ private void printContentRow(String xnecId, DecomposedFlow decomposedFlow, Set<S
         failSilentlyPrint(printer, decomposedFlow.getInternalFlow());
         failSilentlyPrint(printer, decomposedFlow.getPstFlow());
         allLoopFlowKeys.stream().sorted().forEach(loopFlowKey -> failSilentlyPrint(printer, decomposedFlow.getLoopFlows().getOrDefault(loopFlowKey, NO_FLOW)));
-        failSilentlyPrint(printer, decomposedFlow.getAcReferenceFlow());
+        failSilentlyPrint(printer, decomposedFlow.getAcTerminal1ReferenceFlow());
+        failSilentlyPrint(printer, decomposedFlow.getAcTerminal2ReferenceFlow());
         failSilentlyPrint(printer, decomposedFlow.getDcReferenceFlow());
         failSilentlyPrintLn(printer);
     }

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlow.java

@@ -19,33 +19,36 @@ public class DecomposedFlow {
     private final String contingencyId;
     private final Country country1;
     private final Country country2;
-    private final double acReferenceFlow;
+    private final double acTerminal1ReferenceFlow;
+    private final double acTerminal2ReferenceFlow;
     private final double dcReferenceFlow;
     private final double allocatedFlow;
     private final double xNodeFlow;
     private final double pstFlow;
     private final double internalFlow;
     private final Map<String, Double> loopFlowsMap = new TreeMap<>();
     static final double NO_FLOW = 0.;
-    static final String AC_REFERENCE_FLOW_COLUMN_NAME = "Reference AC Flow";
+    static final String AC_REFERENCE_FLOW_1_COLUMN_NAME = "Reference AC Flow 1";
+    static final String AC_REFERENCE_FLOW_2_COLUMN_NAME = "Reference AC Flow 2";
     static final String DC_REFERENCE_FLOW_COLUMN_NAME = "Reference DC Flow";
     static final String ALLOCATED_COLUMN_NAME = "Allocated Flow";
     static final String XNODE_COLUMN_NAME = "Xnode Flow";
     static final String PST_COLUMN_NAME = "PST Flow";
     static final String INTERNAL_COLUMN_NAME = "Internal Flow";
 
-    protected DecomposedFlow(String branchId, String contingencyId, Country country1, Country country2, double acReferenceFlow, double dcReferenceFlow, double allocatedFlow, double xNodeFlow, double pstFlow, double internalFlow, Map<String, Double> loopFlowsMap) {
-        this.branchId = branchId;
-        this.contingencyId = contingencyId;
-        this.country1 = country1;
-        this.country2 = country2;
-        this.acReferenceFlow = acReferenceFlow;
-        this.dcReferenceFlow = dcReferenceFlow;
-        this.allocatedFlow = allocatedFlow;
-        this.xNodeFlow = xNodeFlow;
-        this.pstFlow = pstFlow;
-        this.internalFlow = internalFlow;
-        this.loopFlowsMap.putAll(loopFlowsMap);
+    protected DecomposedFlow(DecomposedFlowBuilder builder) {
+        this.branchId = builder.branchId;
+        this.contingencyId = builder.contingencyId;
+        this.country1 = builder.country1;
+        this.country2 = builder.country2;
+        this.acTerminal1ReferenceFlow = builder.acTerminal1ReferenceFlow;
+        this.acTerminal2ReferenceFlow = builder.acTerminal2ReferenceFlow;
+        this.dcReferenceFlow = builder.dcReferenceFlow;
+        this.allocatedFlow = builder.allocatedFlow;
+        this.xNodeFlow = builder.xNodeFlow;
+        this.pstFlow = builder.pstFlow;
+        this.internalFlow = builder.internalFlow;
+        this.loopFlowsMap.putAll(builder.loopFlowsMap);
     }
 
     public String getBranchId() {
@@ -68,8 +71,12 @@ public Country getCountry2() {
         return country2;
     }
 
-    public double getAcReferenceFlow() {
-        return acReferenceFlow;
+    public double getAcTerminal1ReferenceFlow() {
+        return acTerminal1ReferenceFlow;
+    }
+
+    public double getAcTerminal2ReferenceFlow() {
+        return acTerminal2ReferenceFlow;
     }
 
     public double getDcReferenceFlow() {
@@ -112,14 +119,19 @@ public double getTotalFlow() {
         return getAllocatedFlow() + getXNodeFlow() + getPstFlow() + getInternalFlow() + getTotalLoopFlow();
     }
 
+    public double getMaxAbsAcFlow() {
+        return Math.max(Math.abs(acTerminal1ReferenceFlow), Math.abs(acTerminal2ReferenceFlow));
+    }
+
     @Override
     public String toString() {
         return String.format("branchId: %s, contingencyId: %s, decomposition: %s", branchId, contingencyId, getAllKeyMap());
     }
 
     private TreeMap<String, Double> getAllKeyMap() {
         TreeMap<String, Double> localDecomposedFlowMap = new TreeMap<>();
-        localDecomposedFlowMap.put(AC_REFERENCE_FLOW_COLUMN_NAME, getAcReferenceFlow());
+        localDecomposedFlowMap.put(AC_REFERENCE_FLOW_1_COLUMN_NAME, getAcTerminal1ReferenceFlow());
+        localDecomposedFlowMap.put(AC_REFERENCE_FLOW_2_COLUMN_NAME, getAcTerminal2ReferenceFlow());
         localDecomposedFlowMap.put(DC_REFERENCE_FLOW_COLUMN_NAME, getDcReferenceFlow());
         localDecomposedFlowMap.put(ALLOCATED_COLUMN_NAME, getAllocatedFlow());
         localDecomposedFlowMap.put(XNODE_COLUMN_NAME, getXNodeFlow());

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlowBuilder.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2022, 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/.
+ */
+package com.powsybl.flow_decomposition;
+
+import com.powsybl.iidm.network.Country;
+
+import java.util.Map;
+
+/**
+ * @author Caio Luke {@literal <caio.luke at artelys.com>}
+ * @author Sebastien Murgey {@literal <sebastien.murgey at rte-france.com>}
+ * @author Hugo Schindler {@literal <hugo.schindler at rte-france.com>}
+ */
+public class DecomposedFlowBuilder {
+    protected String branchId;
+    protected String contingencyId;
+    protected Country country1;
+    protected Country country2;
+    protected double acTerminal1ReferenceFlow;
+    protected double acTerminal2ReferenceFlow;
+    protected double dcReferenceFlow;
+    protected double allocatedFlow;
+    protected double xNodeFlow;
+    protected double pstFlow;
+    protected double internalFlow;
+    protected Map<String, Double> loopFlowsMap;
+
+    public DecomposedFlowBuilder() {
+        // empty constructor
+    }
+
+    public DecomposedFlowBuilder addBranchId(String branchId) {
+        this.branchId = branchId;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addContingencyId(String contingencyId) {
+        this.contingencyId = contingencyId;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addCountry1(Country country1) {
+        this.country1 = country1;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addCountry2(Country country2) {
+        this.country2 = country2;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addAcTerminal1ReferenceFlow(double acTerminal1ReferenceFlow) {
+        this.acTerminal1ReferenceFlow = acTerminal1ReferenceFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addAcTerminal2ReferenceFlow(double acTerminal2ReferenceFlow) {
+        this.acTerminal2ReferenceFlow = acTerminal2ReferenceFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addDcReferenceFlow(double dcReferenceFlow) {
+        this.dcReferenceFlow = dcReferenceFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addAllocatedFlow(double allocatedFlow) {
+        this.allocatedFlow = allocatedFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addXNodeFlow(double xNodeFlow) {
+        this.xNodeFlow = xNodeFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addPstFlow(double pstFlow) {
+        this.pstFlow = pstFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addInternalFlow(double internalFlow) {
+        this.internalFlow = internalFlow;
+        return this;
+    }
+
+    public DecomposedFlowBuilder addLoopFlowsMap(Map<String, Double> loopFlowsMap) {
+        this.loopFlowsMap = loopFlowsMap;
+        return this;
+    }
+
+    public DecomposedFlow build() {
+        return new DecomposedFlow(this);
+    }
+}

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlowRescaler.java

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2024, 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.flow_decomposition;
+
+/**
+ * @author Sebastien Murgey {@literal <sebastien.murgey at rte-france.com>}
+ * @author Hugo Schindler {@literal <hugo.schindler at rte-france.com>}
+ * @author Caio Luke {@literal <caio.luke at artelys.com>}
+ */
+public interface DecomposedFlowRescaler {
+    DecomposedFlow rescale(DecomposedFlow decomposedFlow);
+}

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlowsRescaler.java → flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlowRescalerAcerMethodology.java

@@ -1,8 +1,9 @@
-/*
- * Copyright (c) 2022, RTE (http://www.rte-france.com)
+/**
+ * Copyright (c) 2024, 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.flow_decomposition;
 
@@ -14,9 +15,12 @@
 /**
  * @author Sebastien Murgey {@literal <sebastien.murgey at rte-france.com>}
  * @author Hugo Schindler {@literal <hugo.schindler at rte-france.com>}
+ * @author Caio Luke {@literal <caio.luke at artelys.com>}
  */
-final class DecomposedFlowsRescaler {
-    private DecomposedFlowsRescaler() {
+public class DecomposedFlowRescalerAcerMethodology implements DecomposedFlowRescaler {
+
+    public DecomposedFlowRescalerAcerMethodology() {
+        // empty constructor
     }
 
     private static double reLU(double value) {
@@ -27,34 +31,48 @@ private static double rescaleValue(double initialValue, double delta, double sum
         return initialValue + delta * reLU(initialValue) / sumOfReLUFlows;
     }
 
-    static DecomposedFlow rescale(DecomposedFlow decomposedFlow) {
+    @Override
+    public DecomposedFlow rescale(DecomposedFlow decomposedFlow) {
+        double acTerminal1ReferenceFlow = decomposedFlow.getAcTerminal1ReferenceFlow();
+        if (Double.isNaN(acTerminal1ReferenceFlow)) {
+            return decomposedFlow;
+        }
+
         String branchId = decomposedFlow.getBranchId();
         String contingencyId = decomposedFlow.getContingencyId();
         Country country1 = decomposedFlow.getCountry1();
         Country country2 = decomposedFlow.getCountry2();
-
-        double acReferenceFlow = decomposedFlow.getAcReferenceFlow();
+        double acTerminal2ReferenceFlow = decomposedFlow.getAcTerminal2ReferenceFlow();
         double dcReferenceFlow = decomposedFlow.getDcReferenceFlow();
         double allocatedFlow = decomposedFlow.getAllocatedFlow();
         double xNodeFlow = decomposedFlow.getXNodeFlow();
         double pstFlow = decomposedFlow.getPstFlow();
         double internalFlow = decomposedFlow.getInternalFlow();
         Map<String, Double> loopFlows = decomposedFlow.getLoopFlows();
 
-        if (Double.isNaN(acReferenceFlow)) {
-            return decomposedFlow;
-        }
-
-        double deltaToRescale = acReferenceFlow * Math.signum(acReferenceFlow) - decomposedFlow.getTotalFlow();
-        double sumOfReLUFlows = reLU(allocatedFlow) + reLU(pstFlow) + reLU(xNodeFlow) + loopFlows.values().stream().mapToDouble(DecomposedFlowsRescaler::reLU).sum() + reLU(internalFlow);
+        double deltaToRescale = acTerminal1ReferenceFlow * Math.signum(acTerminal1ReferenceFlow) - decomposedFlow.getTotalFlow();
+        double sumOfReLUFlows = reLU(allocatedFlow) + reLU(pstFlow) + reLU(xNodeFlow) + loopFlows.values().stream().mapToDouble(DecomposedFlowRescalerAcerMethodology::reLU).sum() + reLU(internalFlow);
 
         double rescaledAllocatedFlow = rescaleValue(allocatedFlow, deltaToRescale, sumOfReLUFlows);
         double rescaledXNodeFlow = rescaleValue(xNodeFlow, deltaToRescale, sumOfReLUFlows);
         double rescaledPstFlow = rescaleValue(pstFlow, deltaToRescale, sumOfReLUFlows);
         double rescaleInternalFlow = rescaleValue(internalFlow, deltaToRescale, sumOfReLUFlows);
         Map<String, Double> rescaledLoopFlows = loopFlows.entrySet().stream()
-            .collect(Collectors.toMap(Map.Entry::getKey, entry -> rescaleValue(entry.getValue(), deltaToRescale, sumOfReLUFlows)));
+                .collect(Collectors.toMap(Map.Entry::getKey, entry -> rescaleValue(entry.getValue(), deltaToRescale, sumOfReLUFlows)));
 
-        return new DecomposedFlow(branchId, contingencyId, country1, country2, acReferenceFlow, dcReferenceFlow, rescaledAllocatedFlow, rescaledXNodeFlow, rescaledPstFlow, rescaleInternalFlow, rescaledLoopFlows);
+        return new DecomposedFlowBuilder()
+                .addBranchId(branchId)
+                .addContingencyId(contingencyId)
+                .addCountry1(country1)
+                .addCountry2(country2)
+                .addAcTerminal1ReferenceFlow(acTerminal1ReferenceFlow)
+                .addAcTerminal2ReferenceFlow(acTerminal2ReferenceFlow)
+                .addDcReferenceFlow(dcReferenceFlow)
+                .addAllocatedFlow(rescaledAllocatedFlow)
+                .addXNodeFlow(rescaledXNodeFlow)
+                .addPstFlow(rescaledPstFlow)
+                .addInternalFlow(rescaleInternalFlow)
+                .addLoopFlowsMap(rescaledLoopFlows)
+                .build();
     }
 }

flow-decomposition/src/main/java/com/powsybl/flow_decomposition/DecomposedFlowRescalerNoOp.java

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2024, 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.flow_decomposition;
+
+/**
+ * @author Sebastien Murgey {@literal <sebastien.murgey at rte-france.com>}
+ * @author Hugo Schindler {@literal <hugo.schindler at rte-france.com>}
+ * @author Caio Luke {@literal <caio.luke at artelys.com>}
+ */
+public class DecomposedFlowRescalerNoOp implements DecomposedFlowRescaler {
+
+    public DecomposedFlowRescalerNoOp() {
+        // empty constructor
+    }
+
+    @Override
+    public DecomposedFlow rescale(DecomposedFlow decomposedFlow) {
+        return decomposedFlow;
+    }
+}