ShuntCompensator validation review, prepare actions

Signed-off-by: Samir Romdhani <samir.romdhani_externe@rte-france.com>

Author: samirromdhani

loadflow/loadflow-validation/note.md

@@ -1,17 +1,33 @@
-### Rules / Config Threshold
+## Rules / loadflow validation rules review (this file just for review purpose, do not merge )
 
-#### ShuntCompensator
+### ShuntCompensator validation 
 
-- doc: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#shunt-compensator
+#### Doc
+- core grid model: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#shunt-compensator
+- core tool loadflow-validation: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#shunts
+#### Notes (draft)
+1. Rule1: **|p| < e**
+   - if connected, p must be undefined
+2. Rule2: **| q + #sections * B * v^2 | < e**
+   - if connected, q must match expectedQ (within threshold), ( **expectedQ = #sections * B * v^2** ==> **| q + expectedQ | < e** )
+        - if LinearModel then #sections = bPerSection else #sections = B
+        - **bPerSection**: the susceptance per section in S
+        - **currentSectionCount** = B (The susceptance of the shunt compensator in its current state)
+3. Rule3: if the shunt is disconnected, q should be undefined or 0
+#### Summary and actions
 
-* Rule1: if disconnected, q must be NaN or 0
-* Rule2: if connected, p must be NaN
-* Rule3: if connected, q must match expectedQ (within threshold)
+|            |           Documentation           |                                                                                Code (ShuntCompensatorsValidation) |                                                                                   Description |               Suggestions (TODO) |
+|:-----------|:---------------------------------:|------------------------------------------------------------------------------------------------------------------:|----------------------------------------------------------------------------------------------:|---------------------------------:|
+| Condition1 |             \|P\| < ε             |                                                                                 if(!Double.isNaN(p)) return false |                                        if shunt compensator is connected, p must be undefined | - [ ] Add to condition: `p != 0` |
+| Condition2 | \| q + #sections * B * v^2 \| < ε | if (ValidationUtils.areNaN(config, q, expectedQ) \| Math.abs(q - expectedQ) > config.getThreshold()) return false | if connected, q must match expectedQ (within threshold) <br/> expectedQ = #sections * B * v^2 |                                - |
+| Condition3 |                 -                 |                                                        if (!connected && !Double.isNaN(q) && q != 0) return false |                                      if the shunt is disconnected, q should be undefined or 0 | - [ ] `add this rule in the doc` |
 
-#### Generator TODO
-
-- doc: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#generator
+### Generator validation TODO
 
+#### Doc
+- core grid model: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/grid_model/network_subnetwork.html#generator
+- core tool loadflow-validation:: https://powsybl.readthedocs.io/projects/powsybl-core/en/stable/user/itools/loadflow-validation.html#generators
+#### Notes (Draft) 
 * Rule1: Active power (p) must match setpoint (expectedP) (within threshold)
 * Rule2: if voltageRegulatorOn="false" then reactive power (Q) should match to setpoint (targetQ) (within threshold)
 * Rule3: if voltageRegulatorOn="true"
@@ -20,4 +36,4 @@
 * Rule3.3: If V < targetV - threshold, generator (Qgen) must be at max reactive limit
 * Rule3.4: If |V-targetV| <= threshold, generator (Qgen) must be within [minQ, maxQ]
 
-[//]: # (TODO)
+##### Actions TODO

loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/ShuntCompensatorsValidation.java

@@ -117,24 +117,30 @@ public boolean checkShunts(String id, double p, double q, int currentSectionCoun
         }
     }
 
+    /**
+     * Rule1: |p| < e : p must be undefined </br>
+     * Rule2: | q + #sections * B * v^2 | < e : q must match expectedQ (within threshold) </br>
+     * Rule3: if the shunt is disconnected, q should be undefined or 0 </br>
+     */
     public boolean checkShunts(String id, double p, double q, int currentSectionCount, int maximumSectionCount, double bPerSection,
                                double v, double qMax, double nominalV, boolean connected, boolean mainComponent, ValidationConfig config,
                                ValidationWriter shuntsWriter) {
         boolean validated = true;
 
-        if (!connected && !Double.isNaN(q) && q != 0) { // if the shunt is disconnected then either “q” is not defined or “q” is 0 => Rule1: if the shunt is disconnected, q should be NaN or 0
+        if (!connected && !Double.isNaN(q) && q != 0) { // if the shunt is disconnected then either “q” is not defined or “q” is 0 => Rule3: if the shunt is disconnected, q should be NaN or 0
             LOGGER.warn("{} {}: {}: disconnected shunt Q {}", ValidationType.SHUNTS, ValidationUtils.VALIDATION_ERROR, id, q);
             validated = false;
         }
         // “q” = - bPerSection * currentSectionCount * v^2
-        double expectedQ = -bPerSection * currentSectionCount * v * v; //TODO define this rule
+        double expectedQ = -bPerSection * currentSectionCount * v * v;
         if (connected && ValidationUtils.isMainComponent(config, mainComponent)) {
-            // “p” is always NaN => Rule2: if connected, p must be NaN
+            // “p” is always NaN => Rule1: p must be NaN  (|p| < e)
+            // TODO add (or) p != 0 in this condition
             if (!Double.isNaN(p)) {
                 LOGGER.warn("{} {}: {}: P={}", ValidationType.SHUNTS, ValidationUtils.VALIDATION_ERROR, id, p);
                 validated = false;
             }
-            // Rule3: if connected, q must match expectedQ (within threshold)
+            // Rule2: q must match expectedQ (within threshold)
             if (ValidationUtils.areNaN(config, q, expectedQ) || Math.abs(q - expectedQ) > config.getThreshold()) {
                 LOGGER.warn("{} {}: {}:  Q {} {}", ValidationType.SHUNTS, ValidationUtils.VALIDATION_ERROR, id, q, expectedQ);
                 validated = false;