From 5777a24e7ccc92fdbf4cc3d9ae29a89bbef47647 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Murgey?= <sebastien.murgey@rte-france.com>
Date: Fri, 5 Feb 2021 09:17:48 +0100
Subject: [PATCH] Update sensitivity factors provider API (#1623)

Signed-off-by: Sebastien Murgey <sebastien.murgey@rte-france.com>
---
 .../JsonSensitivityFactorsProvider.java       |  7 +----
 .../SensitivityFactorsProvider.java           | 27 +++++++++++++++----
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/JsonSensitivityFactorsProvider.java b/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/JsonSensitivityFactorsProvider.java
index fb568df7172..4e03d19d111 100644
--- a/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/JsonSensitivityFactorsProvider.java
+++ b/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/JsonSensitivityFactorsProvider.java
@@ -49,12 +49,7 @@ public JsonSensitivityFactorsProvider(final InputStream input) {
     }
 
     @Override
-    public List<SensitivityFactor> getFactors(Network network) {
-        return sensitivityFactors;
-    }
-
-    @Override
-    public List<SensitivityFactor> getFactors(Network network, String contingencyId) {
+    public List<SensitivityFactor> getCommonFactors(Network network) {
         return sensitivityFactors;
     }
 }
diff --git a/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/SensitivityFactorsProvider.java b/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/SensitivityFactorsProvider.java
index 4512e6fb25d..c01927c8c0f 100644
--- a/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/SensitivityFactorsProvider.java
+++ b/sensitivity-analysis-api/src/main/java/com/powsybl/sensitivity/SensitivityFactorsProvider.java
@@ -8,6 +8,7 @@
 
 import com.powsybl.iidm.network.Network;
 
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -18,26 +19,42 @@
  *     for sensitivity analysis.
  * </p>
  *
+ * Sensitivity factors are defined through the combination of a common factors list,
+ * that must be computed on all states (base case and any contingency) and additional
+ * ones by state.
+ *
  * @author Sebastien Murgey {@literal <sebastien.murgey at rte-france.com>}
  * @see SensitivityFactor
  */
 public interface SensitivityFactorsProvider {
 
     /**
-     * Get the list of factors generated based on the given network
+     * Get the list of factors that are common to base case and all contingencies,
+     * generated based on the given network
      *
      * @param network Base IIDM network of provision method
      * @return A list of sensitivity factors
      */
-    List<SensitivityFactor> getFactors(Network network);
+    List<SensitivityFactor> getCommonFactors(Network network);
 
+    /**
+     * Get the list of additional factors specific to base case.
+     *
+     * @param network Base IIDM network of provision method
+     * @return A list of sensitivity factors
+     */
+    default List<SensitivityFactor> getAdditionalFactors(Network network) {
+        return Collections.emptyList();
+    }
 
     /**
-     * Get the list of factors generated based on the given network and a contingency
+     * Get the list of additional factors specific to a given contingency
      *
      * @param network Base IIDM network of provision method
-     * @param contingencyId Id of the contingency for which we want the factors. Set to null for base case factors.
+     * @param contingencyId Id of the contingency for which we want the factors.
      * @return A list of sensitivity factors
      */
-    List<SensitivityFactor> getFactors(Network network, String contingencyId);
+    default List<SensitivityFactor> getAdditionalFactors(Network network, String contingencyId) {
+        return Collections.emptyList();
+    }
 }