improve Generator validation rules

samirromdhani · samirromdhani · commit 68632e2fa96b · 2026-03-25T15:29:28.000+01:00
Signed-off-by: Samir Romdhani &lt;samir.romdhani_externe@rte-france.com&gt;
diff --git a/docs/user/itools/loadflow-validation.md b/docs/user/itools/loadflow-validation.md
@@ -211,10 +211,11 @@ $$
 \end{align*}
 $$
 
-In the PowSyBl validation, there are a few tricks to handle special cases:
+In the PowSyBl validation, there are a few tricks to handle special cases before applying the nominal active/reactive/voltage rules
+- if `P` or `Q` is missing, validation fails if setpoints are defined and non-zero
 - if $minQ > maxQ$, then the values are switched to recover a meaningful interval if `noRequirementIfReactiveBoundInversion = false`
 - in case of a missing value, the corresponding test is OK
-- $minQ$ and $maxQ$ are function of $P$. If $targetP$ is outside $[minP, maxP]$, no test is done.
+- $minQ$ and $maxQ$ are function of $P$. If $targetP$ is outside $[minP, maxP]$, and `noRequirementIfSetpointOutsidePowerBounds = true`, generator validation checks are bypassed.
 
 ### Loads
 <span style="color: red">To be implemented, with tests similar to generators with voltage regulation.</span>
diff --git a/loadflow/loadflow-validation/notes/note.md b/loadflow/loadflow-validation/notes/note.md
@@ -99,8 +99,7 @@
 | Condition4 | `same checks as a generator with voltage regulation with the following bounds: Qmin, Qmax` |                 `voltageRegulationModeKo` |                                               Rule4.1, Rule4.2, Rule4.3, Rule4.4 |                                                                                                            - |
 | Condition5 |                                             -                                              |                         `notRegulatingKo` |                  if regulating is false then reactive power should be equal to 0 |                                                                                 - `add this rule in the doc` |
 
-
-- Used util methods inValidationUtils
+- Used util methods in ValidationUtils
     - `isUndefinedOrZero`
     - `isOutsideTolerance`
 ### Generator validation
@@ -109,16 +108,30 @@
 - 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: when maxQ < minQ if noRequirementIfReactiveBoundInversion (parameter) return true (TODO)
-- [ ] Rule2: when targetP < minP or targetP > maxP if noRequirementIfSetpointOutsidePowerBounds (parameter) return true (TODO)
-- [ ] Rule3: p or q should be defined if voltage and a target (targetP and targetQ) defined => voltage not mentioned in the condition in code (TODO)
-- [x] Rule4: Active power (p) must match setpoint (expectedP) (within threshold)
-- [x] Rule5: if voltageRegulatorOn="false" then reactive power (Q) should match to setpoint (targetQ) (within threshold)
-- [x] Rule6: if voltageRegulatorOn="true"
-    * Rule6.1: (minQ/maxQ/targetV) are not defined => OK
-    * Rule6.2: If V > targetV + threshold, generator (Qgen) must be at min reactive limit
-    * Rule6.3: If V < targetV - threshold, generator (Qgen) must be at max reactive limit
-    * Rule6.4: If |V-targetV| <= threshold, generator (Qgen) must be within [minQ, maxQ]
+
+> [!NOTE]
+> Rule1 : If `P` or `Q` is missing, validation fails if setpoints are defined and non-zero
+
+> [!NOTE]
+> Rule2 : If reactive limits are inverted (`maxQ < minQ`) and noRequirementIfReactiveBoundInversion = true, generator validation are bypassed.
+
+> [!NOTE]
+> Rule3 : active setpoint outside bounds bypass
+>  If `targetP` is outside `[minP, maxP]` (with tolerance) and noRequirementIfSetpointOutsidePowerBounds = true, generator validation are bypassed
+
+> [!NOTE]
+> Rule4: Active power p matches expected setpoint
+> Active power p must match setpoint (expectedP) (within threshold)
+
+> [!NOTE]
+> Rule5: If voltage regulator is disabled, Q matches targetQ
+> Reactive power q should match to setpoint (targetQ) (within threshold) when voltageRegulatorOn = false
+
+> [!NOTE]
+> Rule6: If voltage regulator ON, Reactive power q follow V/targetV logic
+>   - qGen at minQ if V > targetV + threshold
+>   - qGen at maxQ if V < targetV - threshold
+>   - else qGen within [minQ, maxQ])
 
 ##### Actions TODO
 
@@ -131,7 +144,10 @@
 | Condition5 |         \|targetQ - Q\| < ε          |                                                                                 `voltageRegulatorOn="false"` | - The reactive power (Q) should match to setpoint (targetQ) (within threshold) |                                                         |
 | Condition6 |                  ..                  |                                                                                 `voltageRegulatorOn="true" ` |                                           - Rule6.1, Rule6.2, Rule6.3, Rule6.4 |                                                         |
 
-
+- Used util methods in ValidationUtils
+    - `isActivePowerKo`
+    - `isReactivePowerKo`
+    - `isVoltageRegulationKo`
 
 ### Buses validation
 
diff --git a/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/FlowsValidation.java b/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/FlowsValidation.java
@@ -61,19 +61,15 @@ public boolean checkFlows(BranchData branch, ValidationConfig config, Validation
         boolean validated = true;
 
         if (!branch.isConnected1()) {
-            //Rule1: checks disconnected terminal
             validated &= checkDisconnectedTerminal(branch.getId(), "1", branch.getP1(), branch.getComputedP1(), branch.getQ1(), branch.getComputedQ1(), config);
         }
         if (!branch.isConnected2()) {
-            //Rule1: checks disconnected terminal
             validated &= checkDisconnectedTerminal(branch.getId(), "2", branch.getP2(), branch.getComputedP2(), branch.getQ2(), branch.getComputedQ2(), config);
         }
         if (branch.isConnected1() && ValidationUtils.isMainComponent(config, branch.isMainComponent1())) {
-            //Rule2: checks connected terminal
             validated &= checkConnectedTerminal(branch.getId(), "1", branch.getP1(), branch.getComputedP1(), branch.getQ1(), branch.getComputedQ1(), config);
         }
         if (branch.isConnected2() && ValidationUtils.isMainComponent(config, branch.isMainComponent2())) {
-            //Rule2: checks connected terminal
             validated &= checkConnectedTerminal(branch.getId(), "2", branch.getP2(), branch.getComputedP2(), branch.getQ2(), branch.getComputedQ2(), config);
         }
         try {
diff --git a/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/GeneratorsValidation.java b/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/GeneratorsValidation.java
@@ -23,6 +23,8 @@
 import com.powsybl.iidm.network.Network;
 import com.powsybl.loadflow.validation.io.ValidationWriter;
 
+import static com.powsybl.loadflow.validation.ValidationUtils.*;
+
 /**
  *
  * @author Massimo Ferraro {@literal <massimo.ferraro@techrain.eu>}
@@ -129,15 +131,14 @@ public boolean checkGenerators(String id, double p, double q, double v, double t
 
         double expectedP = getExpectedP(guesser, id, p, targetP, minP, maxP, config.getThreshold());
         if (connected && ValidationUtils.isMainComponent(config, mainComponent)) {
-            if (Double.isNaN(p) || Double.isNaN(q)) {
-                validated = checkGeneratorsNaNValues(id, p, q, targetP, targetQ); //Rule 1:
-            } else if (checkReactiveBoundInversion(minQ, maxQ, config)) { //Rule 2: when maxQ < minQ if noRequirementIfReactiveBoundInversion return true
+            if (areNaN(p, q)) {
+                validated = validateMissingPQRule(id, p, q, targetP, targetQ);
+            } else if (isReactiveBoundInverted(minQ, maxQ, config.getThreshold(), config.isNoRequirementIfReactiveBoundInversion())) {
                 validated = true;
-            } else if (checkSetpointOutsidePowerBounds(targetP, minP, maxP, config)) { //Rule 3: when targetP < minP or targetP > maxP if noRequirementIfSetpointOutsidePowerBounds return true
+            } else if (isSetpointOutsidePowerBounds(targetP, minP, maxP, config.getThreshold(), config.isNoRequirementIfSetpointOutsidePowerBounds())) {
                 validated = true;
             } else {
-                //Rule 4, Rule 5, Rule 6
-                validated = checkGeneratorsValues(id, p, q, v, expectedP, targetQ, targetV, voltageRegulatorOn, minQ, maxQ, config);
+                validated = validateGeneratorNominalRules(id, p, q, v, expectedP, targetQ, targetV, voltageRegulatorOn, minQ, maxQ, config);
             }
         }
         try {
@@ -166,73 +167,41 @@ private static double getExpectedP(BalanceTypeGuesser guesser, String id, double
         }
     }
 
-    private static boolean checkGeneratorsNaNValues(String id, double p, double q, double targetP, double targetQ) {
+    private static boolean validateMissingPQRule(String id, double p, double q, double targetP, double targetQ) {
         // a validation error should be detected if there is both a voltage and a target but no p or q
-        if (!Double.isNaN(targetP) && targetP != 0
-                || !Double.isNaN(targetQ) && targetQ != 0) {
+        if (!Double.isNaN(targetP) && targetP != 0 || !Double.isNaN(targetQ) && targetQ != 0) {
             LOGGER.warn("{} {}: {}: P={} targetP={} - Q={} targetQ={}", ValidationType.GENERATORS, ValidationUtils.VALIDATION_ERROR, id, p, targetP, q, targetQ);
             return false;
         }
         return true;
     }
 
-    /**
-     * Rule4: Active power (p) must match setpoint (expectedP) (within threshold)
-     * Rule5: if voltageRegulatorOn="false" then reactive power (Q) should match to setpoint (targetQ) (within threshold)
-     * Rule3: if voltageRegulatorOn="true" then either
-     * Rule6.1: (minQ/maxQ/targetV) must be defined
-     * Rule6.2: If V > targetV + threshold, generator (Qgen) must be at min reactive limit
-     * Rule6.3: If V < targetV - threshold, generator (Qgen) must be at max reactive limit
-     * Rule6.4: If |V-targetV| <= threshold, generator (Qgen) must be within [minQ, maxQ]
-     */
-    private static boolean checkGeneratorsValues(String id, double p, double q, double v, double expectedP, double targetQ, double targetV,
+    private static boolean validateGeneratorNominalRules(String id, double p, double q, double v, double expectedP, double targetQ, double targetV,
                                                  boolean voltageRegulatorOn, double minQ, double maxQ, ValidationConfig config) {
         boolean validated = true;
         double threshold = config.getThreshold();
-        // Rule4: Active power (p) must match setpoint (expectedP) (within threshold)
-        if (ValidationUtils.areNaN(config, expectedP) || Math.abs(p + expectedP) > threshold) {
-            LOGGER.warn("{} {}: {}: P={} expectedP={}", ValidationType.GENERATORS, ValidationUtils.VALIDATION_ERROR, id, p, expectedP);
+        // Rule: Active power p matches expected setpoint
+        if (isActivePowerKo(p, expectedP, config, threshold)) {
+            LOGGER.warn("{} {}: {}: P={} expectedP={}",
+                    ValidationType.GENERATORS, ValidationUtils.VALIDATION_ERROR, id, p, expectedP);
             validated = false;
         }
-        //Rule5: if voltageRegulatorOn="false" then reactive power (Q) should match to setpoint (targetQ) (within threshold)
-        if (!voltageRegulatorOn && (ValidationUtils.areNaN(config, targetQ) || Math.abs(q + targetQ) > threshold)) {
+
+        //Rule: If voltage regulator is disabled, Reactive power Q matches targetQ
+        if (!voltageRegulatorOn && (areNaN(config, targetQ) || isReactivePowerKo(q, targetQ, threshold))) {
             LOGGER.warn("{} {}: {}: voltage regulator off - Q={} targetQ={}", ValidationType.GENERATORS, ValidationUtils.VALIDATION_ERROR, id, q, targetQ);
             validated = false;
         }
-        // Rule6, then
-        // either Rule6.1, Rule6.2, Rule6.3 or Rule6.4
-        //
-        // if voltageRegulatorOn="true" then
-        // either if minQ/maxQ/targetV are not NaN,
-        // or q is equal to g.getReactiveLimits().getMinQ(p) and V is higher than g.getTargetV()
-        // or q is equal to g.getReactiveLimits().getMaxQ(p) and V is lower than g.getTargetV()
-        // or V at the connected bus is equal to g.getTargetV() and the reactive bounds are satisfied
+
         double qGen = -q;
-        if (voltageRegulatorOn
-            && (ValidationUtils.areNaN(config, minQ, maxQ, targetV)
-                || v > targetV + threshold && Math.abs(qGen - getMinQ(minQ, maxQ)) > threshold
-                || v < targetV - threshold && Math.abs(qGen - getMaxQ(minQ, maxQ)) > threshold
-                || Math.abs(v - targetV) <= threshold && !ValidationUtils.boundedWithin(minQ, maxQ, qGen, threshold))) {
+        // Rule: If voltage regulator ON, Reactive power q follow V/targetV logic
+        // - qGen at minQ if V > targetV + threshold
+        // - qGen at maxQ if V < targetV - threshold
+        // - else qGen within [minQ, maxQ])
+        if (voltageRegulatorOn && (ValidationUtils.areNaN(config, minQ, maxQ, targetV) || isVoltageRegulationKo(qGen, v, targetV, minQ, maxQ, threshold))) {
             LOGGER.warn("{} {}: {}: voltage regulator on - Q={} minQ={} maxQ={} - V={} targetV={}", ValidationType.GENERATORS, ValidationUtils.VALIDATION_ERROR, id, qGen, minQ, maxQ, v, targetV);
             validated = false;
         }
         return validated;
     }
-
-    private static double getMaxQ(double minQ, double maxQ) {
-        return Math.max(maxQ, minQ);
-    }
-
-    private static double getMinQ(double minQ, double maxQ) {
-        return Math.min(maxQ, minQ);
-    }
-
-    private static boolean checkReactiveBoundInversion(double minQ, double maxQ, ValidationConfig config) {
-        return maxQ < minQ - config.getThreshold() && config.isNoRequirementIfReactiveBoundInversion();
-    }
-
-    private static boolean checkSetpointOutsidePowerBounds(double targetP, double minP, double maxP, ValidationConfig config) {
-        return (targetP < minP - config.getThreshold() || targetP > maxP + config.getThreshold()) && config.isNoRequirementIfSetpointOutsidePowerBounds();
-    }
-
 }
diff --git a/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/ValidationUtils.java b/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/ValidationUtils.java
@@ -58,6 +58,17 @@ public static boolean areNaN(ValidationConfig config, float... values) {
         return areNaN;
     }
 
+    public static boolean areNaN(double... values) {
+        boolean areMissing = false;
+        for (double value : values) {
+            if (Double.isNaN(value)) {
+                areMissing = true;
+                break;
+            }
+        }
+        return areMissing;
+    }
+
     public static boolean areNaN(ValidationConfig config, double... values) {
         Objects.requireNonNull(config);
         if (config.areOkMissingValues()) {
@@ -126,4 +137,48 @@ public static double computeShuntExpectedQ(double bPerSection, int sectionCount,
     public static double voltageFrom(double vBus, double nominalV) {
         return (Double.isNaN(vBus) || vBus == 0.0) ? nominalV : vBus;
     }
+
+    public static boolean isActivePowerKo(double p, double expectedP, ValidationConfig config, double threshold) {
+        return areNaN(config, expectedP) || Math.abs(p + expectedP) > threshold;
+    }
+
+    /**
+     * Generator: rule for valid result <code> | targetQ - Q | < threshold </code>
+     */
+    public static boolean isReactivePowerKo(double q, double targetQ, double threshold) {
+        return Math.abs(q + targetQ) >= threshold;
+    }
+
+    /**
+     * Generator: rules for valid result:</p>
+     * <code> targetV - V < threshold && |Q - minQ| <= threshold</code></p>
+     * <code> V - targetV < threshold && |Q - maxQ| <= threshold</code></p>
+     * <code> |V - targetV|  < threshold && minQ <= Q <= maxQ </code>
+     */
+    public static boolean isVoltageRegulationKo(double qGen, double v, double targetV, double minQ, double maxQ, double threshold) {
+
+        // When V is higher than g.getTargetV() then q must equal to g.getReactiveLimits().getMinQ(p)
+        // When V is lower than g.getTargetV() q must equal to g.getReactiveLimits().getMaxQ(p)
+        // When V is equal to g.getTargetV() then q (reactive bounds) must satisfy
+        return v > targetV + threshold && Math.abs(qGen - Math.min(minQ, maxQ)) > threshold
+                || v < targetV - threshold && Math.abs(qGen - Math.max(minQ, maxQ)) > threshold
+                || Math.abs(v - targetV) <= threshold && !boundedWithin(minQ, maxQ, qGen, threshold);
+    }
+
+    /**
+     * Generator: rule for valid result <p/>
+     * If reactive limits are inverted (`maxQ < minQ`) and noRequirementIfReactiveBoundInversion = true, generator validation OK.
+     */
+    public static boolean isReactiveBoundInverted(double minQ, double maxQ, double threshold, boolean isNoRequirementIfReactiveBoundInversion) {
+        return maxQ < minQ - threshold && isNoRequirementIfReactiveBoundInversion;
+    }
+
+    /**
+     * Generator: rule for valid result<p/>
+     * Active setpoint outside bounds, if `targetP` is outside `[minP, maxP]` and noRequirementIfSetpointOutsidePowerBounds = true, generator validation OK
+     */
+    public static boolean isSetpointOutsidePowerBounds(double targetP, double minP, double maxP, double threshold, boolean isNoRequirementIfSetpointOutsidePowerBounds) {
+        return (targetP < minP - threshold || targetP > maxP + threshold) && isNoRequirementIfSetpointOutsidePowerBounds;
+    }
+
 }
diff --git a/loadflow/loadflow-validation/src/test/java/com/powsybl/loadflow/validation/ValidationUtilsTest.java b/loadflow/loadflow-validation/src/test/java/com/powsybl/loadflow/validation/ValidationUtilsTest.java

Original file line number	Diff line number	Diff line change
`@@ -61,19 +61,15 @@ public boolean checkFlows(BranchData branch, ValidationConfig config, Validation`
`61`	`61`	`boolean validated = true;`
`62`	`62`
`63`	`63`	`if (!branch.isConnected1()) {`
`64`		`- //Rule1: checks disconnected terminal`
`65`	`64`	`validated &= checkDisconnectedTerminal(branch.getId(), "1", branch.getP1(), branch.getComputedP1(), branch.getQ1(), branch.getComputedQ1(), config);`
`66`	`65`	`}`
`67`	`66`	`if (!branch.isConnected2()) {`
`68`		`- //Rule1: checks disconnected terminal`
`69`	`67`	`validated &= checkDisconnectedTerminal(branch.getId(), "2", branch.getP2(), branch.getComputedP2(), branch.getQ2(), branch.getComputedQ2(), config);`
`70`	`68`	`}`
`71`	`69`	`if (branch.isConnected1() && ValidationUtils.isMainComponent(config, branch.isMainComponent1())) {`
`72`		`- //Rule2: checks connected terminal`
`73`	`70`	`validated &= checkConnectedTerminal(branch.getId(), "1", branch.getP1(), branch.getComputedP1(), branch.getQ1(), branch.getComputedQ1(), config);`
`74`	`71`	`}`
`75`	`72`	`if (branch.isConnected2() && ValidationUtils.isMainComponent(config, branch.isMainComponent2())) {`
`76`		`- //Rule2: checks connected terminal`
`77`	`73`	`validated &= checkConnectedTerminal(branch.getId(), "2", branch.getP2(), branch.getComputedP2(), branch.getQ2(), branch.getComputedQ2(), config);`
`78`	`74`	`}`
`79`	`75`	`try {`