From d50312a40f4511ffe59578d4060e456bff204610 Mon Sep 17 00:00:00 2001
From: David Kleiven <david.kleiven@statnett.no>
Date: Tue, 27 Feb 2024 12:42:31 +0100
Subject: [PATCH] docs: Add documentation for sensitivity analysis

---
 .../ContingencyListContainer.kt               |  3 +-
 src/main/formItemHandlers/FormItemNames.kt    |  1 +
 src/main/resources/openapi/documentation.yaml | 53 +++++++++++++++++--
 .../testDataFactory/SensitivityRunFactory.kt  |  3 +-
 4 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/main/formItemHandlers/ContingencyListContainer.kt b/src/main/formItemHandlers/ContingencyListContainer.kt
index aa3d0e7..6100253 100644
--- a/src/main/formItemHandlers/ContingencyListContainer.kt
+++ b/src/main/formItemHandlers/ContingencyListContainer.kt
@@ -1,5 +1,6 @@
 package com.github.statnett.loadflowservice.formItemHandlers
 
+import com.github.statnett.loadflowservice.formItemHandlers.FormItemNames.Companion.CONTINGENCIES
 import com.powsybl.contingency.ContingenciesProvider
 import com.powsybl.contingency.Contingency
 import com.powsybl.contingency.contingency.list.ContingencyList
@@ -25,7 +26,7 @@ class ContingencyListContainer : AutoVersionableJsonParser(), FormItemLoadable,
 
     override fun formItemHandler(part: PartData.FormItem) {
         val name = part.name ?: ""
-        if (name == "contingencies") {
+        if (name == CONTINGENCIES) {
             this.update(part.value)
             logger.info { "Received contingencies: ${part.value}" }
         }
diff --git a/src/main/formItemHandlers/FormItemNames.kt b/src/main/formItemHandlers/FormItemNames.kt
index b8ee64c..523b858 100644
--- a/src/main/formItemHandlers/FormItemNames.kt
+++ b/src/main/formItemHandlers/FormItemNames.kt
@@ -6,5 +6,6 @@ class FormItemNames {
         const val SENSITIVITY_ANALYSIS_PARAMS = "sensitivity-analysis-params"
         const val SENSITIVITY_FACTORS = "sensitivity-factors"
         const val SECURITY_ANALYSIS_PARAMS = "security-analysis-params"
+        const val CONTINGENCIES = "contingencies"
     }
 }
diff --git a/src/main/resources/openapi/documentation.yaml b/src/main/resources/openapi/documentation.yaml
index b34535c..c78ec6c 100644
--- a/src/main/resources/openapi/documentation.yaml
+++ b/src/main/resources/openapi/documentation.yaml
@@ -62,7 +62,6 @@ paths:
       description: Run load flow calculation
       requestBody:
         $ref: '#/components/networkFile'
-        load-flow-params: Solver parameters. See /default-values/load-flow-params
 
 
       responses:
@@ -118,6 +117,23 @@ paths:
         500:
           $ref: '#/components/internalError'
 
+  /sensitivity-analysis:
+    post:
+      description: Run a sensitivity analysis. See https://www.powsybl.org/pages/documentation/simulation/sensitivity/
+      requestBody:
+        $ref: '#/components/networkFile'
+
+      responses:
+        200:
+          description: Result of the sensitivity analysis
+          content:
+            application/json:
+              type: object
+        422:
+          $ref: '#/components/missingNetworkFileResponse'
+        500:
+          $ref: '#/components/internalError'
+
 
 components:
   schemas:
@@ -134,9 +150,23 @@ components:
           type: double
         reactivePower:
           type: double
+    sensitivity-factor:
+      type: object
+      properties:
+        functionType:
+          type: string
+        functionId:
+          type: string
+        variableType:
+          type: string
+        variableId:
+          type: string
+        variableSet:
+          type: bool
+        contingencyContextType:
+          type: string
   networkFile:
     description: Form with network data sent as file
-    required: true
     content:
       multipart/form-data:
         schema:
@@ -145,6 +175,24 @@ components:
             network:
               type: string
               format: binary
+            load-flow-params:
+              type: object
+              description: Parameters for load flow calculations. Has effect for /run-load-flow and /sensitivity-analysis). See default-values/load-flow-params for possible fields
+            sensitivity-analysis-params:
+              type: object
+              description: Parameters for sensitivity analysis. Has effect for /sensitivity-analysis. See /default-values/sensitivity-analysis-parameters for possible fields
+            sensitivity-factors:
+              type: array
+              description: Sensitivity factors. Has effect for /sensitivity-analysis
+              items:
+                $ref: '#/components/schemas/sensitivity-factor'
+            contingencies:
+              type: array
+              description: Contingencies. Has effect for /sensitivity-analysis
+              items:
+                type: object
+          required:
+          - network
   missingNetworkFileResponse:
     description: No network file provided
     content:
@@ -162,4 +210,3 @@ components:
     content:
       image/svg+xml:
         type: string
-
diff --git a/src/test/testDataFactory/SensitivityRunFactory.kt b/src/test/testDataFactory/SensitivityRunFactory.kt
index 8ddd570..f923b21 100644
--- a/src/test/testDataFactory/SensitivityRunFactory.kt
+++ b/src/test/testDataFactory/SensitivityRunFactory.kt
@@ -1,6 +1,7 @@
 package testDataFactory
 
 import com.github.statnett.loadflowservice.formItemHandlers.AutoSerializableSensitivityFactor
+import com.github.statnett.loadflowservice.formItemHandlers.FormItemNames.Companion.CONTINGENCIES
 import com.github.statnett.loadflowservice.formItemHandlers.FormItemNames.Companion.LOAD_FLOW_PARAMS
 import com.github.statnett.loadflowservice.formItemHandlers.FormItemNames.Companion.SENSITIVITY_ANALYSIS_PARAMS
 import com.github.statnett.loadflowservice.formItemHandlers.FormItemNames.Companion.SENSITIVITY_FACTORS
@@ -106,7 +107,7 @@ fun sensFactors(): List<PartData> {
 fun contingencies(): List<PartData> {
     return formData {
         append(
-            "contingencies",
+            CONTINGENCIES,
             Json.encodeToString(ieee14BusContingencies()),
         )
     }