Security analysis runner parameters

contingency/contingency-api/src/main/java/com/powsybl/contingency/ContingencyContext.java

@@ -15,14 +15,15 @@
 import java.util.Objects;
 
 /**
+ * A contingency context has several usages in security analysis and in sensitivity analysis.
+ * For a security analysis, it is a way to describe for which contingency we want some network results
+ * or for which contingency we want limit reductions to be applied. For a sensitivity analysis, it is a way
+ * to describe for which contingency we want to compute sensitivity factors.
+ * See {@link ContingencyContextType} for the type of context to use. In case of a SPECIFIC contingency context,
+ * the id of the contingency must be provided.
+ *
  * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
  * @author Etienne Lesot {@literal <etienne.lesot at rte-france.com>}
- * <p>
- * provide the context to get information of the network after a security analysis
- * it contains a contingency's id and a context type. Context type defines
- * if we want the information in a pre-contingency state, a post-contingency state or both.
- * contingency's id is defined if informations are needed after
- * a specific contingency computation
  */
 @JsonPropertyOrder({"contextType", "contingencyId"})
 public class ContingencyContext {

contingency/contingency-api/src/main/java/com/powsybl/contingency/ContingencyContextType.java

@@ -9,28 +9,31 @@
 package com.powsybl.contingency;
 
 /**
+ * This type precises the contingencies involved.
+ * If only pre-contingency state matters, NONE must be used.
+ * If all the post-contingency states plus the pre-contingency state matters, ALL must be used.
+ * If all the post-contingency states without the pre-contingency state matters, ONLY_CONTINGENCIES must be used.
+ * A SPECIFIC contingency context focus on a single contingency, which id is specified in the {@link ContingencyContext}.
+ *
  * @author Geoffroy Jamgotchian {@literal <geoffroy.jamgotchian at rte-france.com>}
  * @author Etienne Lesot {@literal <etienne.lesot at rte-france.com>}
- *
- * Define for a contingencyContext the type of information asked.
- * It can be a pre-contingency state, a post-contingency state (on a specific contingency (SPECIFIC) or on every contingency (ONLY_CONTINGENCIES)) or both (ALL)
  */
 
 public enum ContingencyContextType {
     /**
-     *  Corresponds to all contingencies and pre-contingency situation
+     *  Corresponds to all contingencies and the pre-contingency state.
      */
     ALL,
     /**
-     *  Corresponds to pre-contingency situation
+     *  Corresponds to the pre-contingency state only.
      */
     NONE,
     /**
-     *  Corresponds to one contingency whose id is specified in the contingencyContext
+     *  Corresponds to the contingency whose id is specified in the contingency context.
      */
     SPECIFIC,
     /**
-     *  Corresponds to all contingencies (without the pre-contingency situation)
+     *  Corresponds to all contingencies, without the pre-contingency state.
      */
     ONLY_CONTINGENCIES
 }

security-analysis/security-analysis-api/src/main/java/com/powsybl/security/SecurityAnalysisProvider.java

@@ -11,17 +11,11 @@
 import com.powsybl.commons.Versionable;
 import com.powsybl.commons.config.PlatformConfig;
 import com.powsybl.commons.config.PlatformConfigNamedProvider;
-import com.powsybl.commons.report.ReportNode;
 import com.powsybl.commons.extensions.Extension;
 import com.powsybl.commons.extensions.ExtensionJsonSerializer;
-import com.powsybl.computation.ComputationManager;
 import com.powsybl.contingency.ContingenciesProvider;
 import com.powsybl.iidm.network.Network;
-import com.powsybl.action.Action;
 import com.powsybl.security.interceptors.SecurityAnalysisInterceptor;
-import com.powsybl.security.limitreduction.LimitReduction;
-import com.powsybl.security.monitor.StateMonitor;
-import com.powsybl.security.strategy.OperatorStrategy;
 
 import java.util.*;
 import java.util.concurrent.CompletableFuture;
@@ -55,7 +49,7 @@ static List<SecurityAnalysisProvider> findAll() {
      *
      * <pre> {@code
      * try {
-     *       SecurityAnalysisResult result = securityAnalysis.run(network, variantId, detector, filter, computationManager, parameters, contingenciesProvider, interceptors).join();
+     *       SecurityAnalysisResult result = securityAnalysis.run(network, variantId, contingenciesProvider, runParameters).join();
      *   } catch (CompletionException e) {
      *       if (e.getCause() instanceof ComputationException) {
      *           ComputationException computationException = (ComputationException) e.getCause();
@@ -75,30 +69,14 @@ static List<SecurityAnalysisProvider> findAll() {
      *
      * @param network IIDM network on which the security analysis will be performed
      * @param workingVariantId network variant ID on which the analysis will be performed
-     * @param detector
-     * @param filter
-     * @param computationManager
-     * @param parameters specific security analysis parameters
      * @param contingenciesProvider provides list of contingencies
-     * @param interceptors
-     * @param monitors stateMonitor that defines the branch bus and threeWindingsTransformer about which informations will be written after security analysis
-     * @param limitReductions list of the limit reductions to apply
-     * @param reportNode the reportNode used for functional logs
+     * @param runParameters runner parameters
      * @return a {@link CompletableFuture} on {@link SecurityAnalysisResult} that gathers security factor values
      */
     CompletableFuture<SecurityAnalysisReport> run(Network network,
                                                   String workingVariantId,
-                                                  LimitViolationDetector detector,
-                                                  LimitViolationFilter filter,
-                                                  ComputationManager computationManager,
-                                                  SecurityAnalysisParameters parameters,
                                                   ContingenciesProvider contingenciesProvider,
-                                                  List<SecurityAnalysisInterceptor> interceptors,
-                                                  List<OperatorStrategy> operatorStrategies,
-                                                  List<Action> actions,
-                                                  List<StateMonitor> monitors,
-                                                  List<LimitReduction> limitReductions,
-                                                  ReportNode reportNode);
+                                                  SecurityAnalysisRunParameters runParameters);
 
     /**
      * The serializer for implementation-specific parameters, or {@link Optional#empty()} if the implementation

security-analysis/security-analysis-api/src/main/java/com/powsybl/security/SecurityAnalysisRunParameters.java

@@ -0,0 +1,242 @@
+/**
+ * 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.security;
+
+import com.powsybl.action.Action;
+import com.powsybl.commons.report.ReportNode;
+import com.powsybl.computation.ComputationManager;
+import com.powsybl.computation.local.LocalComputationManager;
+import com.powsybl.security.detectors.DefaultLimitViolationDetector;
+import com.powsybl.security.interceptors.SecurityAnalysisInterceptor;
+import com.powsybl.security.limitreduction.LimitReduction;
+import com.powsybl.security.monitor.StateMonitor;
+import com.powsybl.security.strategy.OperatorStrategy;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Supplier;
+
+/**
+ * Parameters used in {@link SecurityAnalysisProvider#run} called in {@link SecurityAnalysis} API
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public class SecurityAnalysisRunParameters {
+
+    private static final Supplier<LimitViolationDetector> DEFAULT_DETECTOR_SUPPLIER = DefaultLimitViolationDetector::new;
+    private static final Supplier<LimitViolationFilter> DEFAULT_FILTER_SUPPLIER = LimitViolationFilter::load;
+    private static final Supplier<SecurityAnalysisParameters> DEFAULT_SA_PARAMETERS_SUPPLIER = SecurityAnalysisParameters::load;
+    private static final Supplier<ComputationManager> DEFAULT_COMPUTATION_MANAGER_SUPPLIER = LocalComputationManager::getDefault;
+
+    private LimitViolationDetector detector;
+    private LimitViolationFilter filter;
+    private ComputationManager computationManager;
+    private SecurityAnalysisParameters securityAnalysisParameters;
+    private List<SecurityAnalysisInterceptor> interceptors = new ArrayList<>();
+    private List<OperatorStrategy> operatorStrategies = new ArrayList<>();
+    private List<Action> actions = new ArrayList<>();
+    private List<StateMonitor> monitors = new ArrayList<>();
+    private List<LimitReduction> limitReductions = new ArrayList<>();
+    private ReportNode reportNode = ReportNode.NO_OP;
+
+    /**
+     * Returns a {@link SecurityAnalysisRunParameters} instance with default value on each field.
+     * @return the SecurityAnalysisRunParameters instance.
+     */
+    public static SecurityAnalysisRunParameters getDefault() {
+        return new SecurityAnalysisRunParameters()
+                .setDetector(DEFAULT_DETECTOR_SUPPLIER.get())
+                .setFilter(DEFAULT_FILTER_SUPPLIER.get())
+                .setSecurityAnalysisParameters(DEFAULT_SA_PARAMETERS_SUPPLIER.get())
+                .setComputationManager(DEFAULT_COMPUTATION_MANAGER_SUPPLIER.get());
+    }
+
+    /**
+     * {@link LimitViolationDetector} getter<br>
+     * If null, sets the field to its default value with {@link #DEFAULT_DETECTOR_SUPPLIER} before returning it.
+     */
+    public LimitViolationDetector getDetector() {
+        if (detector == null) {
+            setDetector(DEFAULT_DETECTOR_SUPPLIER.get());
+        }
+        return detector;
+    }
+
+    /**
+     * {@link LimitViolationFilter} getter<br>
+     * If null, sets the field to its default value with {@link #DEFAULT_FILTER_SUPPLIER} before returning it.
+     */
+    public LimitViolationFilter getFilter() {
+        if (filter == null) {
+            setFilter(DEFAULT_FILTER_SUPPLIER.get());
+        }
+        return filter;
+    }
+
+    /**
+     * {@link ComputationManager} getter<br>
+     * If null, sets the field to its default value with {@link #DEFAULT_COMPUTATION_MANAGER_SUPPLIER} before returning it.
+     */
+    public ComputationManager getComputationManager() {
+        if (computationManager == null) {
+            setComputationManager(DEFAULT_COMPUTATION_MANAGER_SUPPLIER.get());
+        }
+        return computationManager;
+    }
+
+    /**
+     * {@link SecurityAnalysisParameters} getter<br>
+     * If null, sets the field to its default value with {@link #DEFAULT_SA_PARAMETERS_SUPPLIER} before returning it.
+     */
+    public SecurityAnalysisParameters getSecurityAnalysisParameters() {
+        if (securityAnalysisParameters == null) {
+            setSecurityAnalysisParameters(DEFAULT_SA_PARAMETERS_SUPPLIER.get());
+        }
+        return securityAnalysisParameters;
+    }
+
+    public List<SecurityAnalysisInterceptor> getInterceptors() {
+        return interceptors;
+    }
+
+    public List<OperatorStrategy> getOperatorStrategies() {
+        return operatorStrategies;
+    }
+
+    public List<Action> getActions() {
+        return actions;
+    }
+
+    public List<StateMonitor> getMonitors() {
+        return monitors;
+    }
+
+    public List<LimitReduction> getLimitReductions() {
+        return limitReductions;
+    }
+
+    public ReportNode getReportNode() {
+        return reportNode;
+    }
+
+    public SecurityAnalysisRunParameters setDetector(LimitViolationDetector detector) {
+        Objects.requireNonNull(detector, "LimitViolationDetector should not be null");
+        this.detector = detector;
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters setFilter(LimitViolationFilter filter) {
+        Objects.requireNonNull(filter, "LimitViolationFilter should not be null");
+        this.filter = filter;
+        return this;
+    }
+
+    /**
+     * Sets the computationManager handling command execution.
+     */
+    public SecurityAnalysisRunParameters setComputationManager(ComputationManager computationManager) {
+        Objects.requireNonNull(computationManager, "ComputationManager should not be null");
+        this.computationManager = computationManager;
+        return this;
+    }
+
+    /**
+     * Sets the security analysis parameters, see {@link SecurityAnalysisParameters}.
+     */
+    public SecurityAnalysisRunParameters setSecurityAnalysisParameters(SecurityAnalysisParameters securityAnalysisParameters) {
+        Objects.requireNonNull(securityAnalysisParameters, "Security analysis parameters should not be null");
+        this.securityAnalysisParameters = securityAnalysisParameters;
+        return this;
+    }
+
+    /**
+     * Sets the list of operator strategies to apply to solve limit violations occurring after a contingency,
+     * see {@link OperatorStrategy}.
+     */
+    public SecurityAnalysisRunParameters setOperatorStrategies(List<OperatorStrategy> operatorStrategies) {
+        Objects.requireNonNull(operatorStrategies, "OperatorStrategy list should not be null");
+        this.operatorStrategies = operatorStrategies;
+        return this;
+    }
+
+    /**
+     * Sets the list of interceptors to notify at specific steps of the security analysis,
+     * see {@link SecurityAnalysisInterceptor}.
+     */
+    public SecurityAnalysisRunParameters setInterceptors(List<SecurityAnalysisInterceptor> interceptors) {
+        Objects.requireNonNull(interceptors, "Interceptor list should not be null");
+        this.interceptors = interceptors;
+        return this;
+    }
+
+    /**
+     * Sets the list of the limit reductions to apply, see {@link LimitReduction}
+     */
+    public SecurityAnalysisRunParameters setLimitReductions(List<LimitReduction> limitReductions) {
+        Objects.requireNonNull(limitReductions, "LimitReductions list should not be null");
+        this.limitReductions = limitReductions;
+        return this;
+    }
+
+    /**
+     * Sets the list of state monitors, see  {@link StateMonitor}
+     */
+    public SecurityAnalysisRunParameters setMonitors(List<StateMonitor> monitors) {
+        Objects.requireNonNull(monitors, "StateMonitor list should not be null");
+        this.monitors = monitors;
+        return this;
+    }
+
+    /**
+     * Sets the list of actions referenced in {@link OperatorStrategy}
+     */
+    public SecurityAnalysisRunParameters setActions(List<Action> actions) {
+        Objects.requireNonNull(actions, "Action list should not be null");
+        this.actions = actions;
+        return this;
+    }
+
+    /**
+     * Sets the reportNode used for functional logs, see {@link ReportNode}
+     */
+    public SecurityAnalysisRunParameters setReportNode(ReportNode reportNode) {
+        Objects.requireNonNull(reportNode, "ReportNode should not be null");
+        this.reportNode = reportNode;
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters addOperatorStrategy(OperatorStrategy operatorStrategy) {
+        Objects.requireNonNull(operatorStrategy, "OperatorStrategy should not be null");
+        operatorStrategies.add(operatorStrategy);
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters addInterceptor(SecurityAnalysisInterceptor interceptor) {
+        Objects.requireNonNull(interceptor, "Interceptor should not be null");
+        interceptors.add(interceptor);
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters addLimitReduction(LimitReduction limitReduction) {
+        Objects.requireNonNull(limitReduction, "LimitReduction should not be null");
+        limitReductions.add(limitReduction);
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters addMonitor(StateMonitor monitor) {
+        Objects.requireNonNull(monitor, "StateMonitor should not be null");
+        monitors.add(monitor);
+        return this;
+    }
+
+    public SecurityAnalysisRunParameters addAction(Action action) {
+        Objects.requireNonNull(action, "Action should not be null");
+        actions.add(action);
+        return this;
+    }
+}

security-analysis/security-analysis-api/src/main/java/com/powsybl/security/execution/SecurityAnalysisExecutionImpl.java

@@ -7,7 +7,6 @@
  */
 package com.powsybl.security.execution;
 
-import com.powsybl.commons.report.ReportNode;
 import com.powsybl.computation.ComputationManager;
 import com.powsybl.security.*;
 
@@ -58,10 +57,19 @@ private SecurityAnalysisInput buildInput(SecurityAnalysisExecutionInput executio
     @Override
     public CompletableFuture<SecurityAnalysisReport> execute(ComputationManager computationManager, SecurityAnalysisExecutionInput data) {
         SecurityAnalysisInput input = buildInput(data);
+        SecurityAnalysisRunParameters runParameters = new SecurityAnalysisRunParameters()
+                .setSecurityAnalysisParameters(input.getParameters())
+                .setComputationManager(computationManager)
+                .setFilter(input.getFilter())
+                .setDetector(input.getLimitViolationDetector())
+                .setInterceptors(new ArrayList<>(input.getInterceptors()))
+                .setOperatorStrategies(data.getOperatorStrategies())
+                .setActions(data.getActions())
+                .setMonitors(data.getMonitors())
+                .setLimitReductions(data.getLimitReductions());
         return runner.runAsync(input.getNetworkVariant().getNetwork(),
                 input.getNetworkVariant().getVariantId(),
-                input.getContingenciesProvider(), input.getParameters(), computationManager, input.getFilter(), input.getLimitViolationDetector(),
-                new ArrayList<>(input.getInterceptors()), data.getOperatorStrategies(), data.getActions(), data.getMonitors(),
-                data.getLimitReductions(), ReportNode.NO_OP);
+                input.getContingenciesProvider(),
+                runParameters);
     }
 }