improve SVC validation rules

samirromdhani · samirromdhani · commit af31f1dfdd63 · 2026-03-24T17:07:51.000+01:00
Signed-off-by: Samir Romdhani &lt;samir.romdhani_externe@rte-france.com&gt;
diff --git a/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/StaticVarCompensatorsValidation.java b/loadflow/loadflow-validation/src/main/java/com/powsybl/loadflow/validation/StaticVarCompensatorsValidation.java
@@ -100,9 +100,9 @@ public boolean checkSVCs(StaticVarCompensator svc, ValidationConfig config, Vali
         double nominalVcontroller = svc.getTerminal().getVoltageLevel().getNominalV();
         double vController = bus != null ? bus.getV() : Double.NaN;
         double vControlled = svc.getRegulatingTerminal() != null
-                ? ValidationUtils.getTerminalState(svc.getRegulatingTerminal()).v()
+                ? getTerminalState(svc.getRegulatingTerminal()).v()
                 : vController;
-        ValidationUtils.TerminalState terminalState = ValidationUtils.getTerminalState(svc.getTerminal());
+        TerminalState terminalState = getTerminalState(svc.getTerminal());
         boolean connected = terminalState.connected();
         boolean mainComponent = terminalState.mainComponent();
         return checkSVCs(svc.getId(), p, q, vControlled, vController, nominalVcontroller, reactivePowerSetpoint, voltageSetpoint, regulationMode, regulating, bMin, bMax, connected, mainComponent, config, svcsWriter);
@@ -122,23 +122,6 @@ public boolean checkSVCs(String id, double p, double q, double vControlled, doub
         }
     }
 
-     /**
-     *
-     * Rule1: active power (p) (within threshold) should be equal to 0 <br/>
-     * Rule2: **reactivePowerSetpoint** must be undefined or equal to 0 if NO (**p** or **q**)<br/>
-     * - TODO (doc states that p should be equal to 0, if so **reactivePowerSetpoint** must be undefined or equal to 0)<br/>
-     * - Suggestion => check only if (q undefined or equal to 0 then **reactivePowerSetpoint** must be 0)<br/><br/>
-     * Rule3: **regulationMode = REACTIVE_POWER** then same condition as generator without voltage regulation<br/>
-     * - Rule3.1: => (config, reactivePowerSetpoint, qMin, qMax) not defined => OK<br/>
-     * - Rule3.2: => q must match reactivePowerSetpoint (within threshold)<br/><br/>
-     * Rule4: **regulationMode = VOLTAGE** then same condition as generator with voltage regulation<br/>
-     * - Rule4.1: => (config, qMin, qMax, vControlled, voltageSetpoint) not defined => OK<br/>
-     * - Rule4.2: => V is lower than voltageSetpoint (within threshold) AND q must match qMax (within threshold)<br/>
-     * - Rule4.3: => V is higher than voltageSetpoint (within threshold) AND q must match Qmin (within threshold)<br/>
-     * - Rule4.4: => V is at the controlled bus (within threshold) AND q is bounded within [Qmin=-bMax*V*V, Qmax=-bMin*V*V]<br/><br/>
-     * Rule5: if regulating is false then reactive power (q) should be equal to 0<br/>
-     *
-     */
     public boolean checkSVCs(String id, double p, double q, double vControlled, double vController, double nominalVcontroller, double reactivePowerSetpoint, double voltageSetpoint,
                                     RegulationMode regulationMode, boolean regulating, double bMin, double bMax, boolean connected, boolean mainComponent,
                                     ValidationConfig config, ValidationWriter svcsWriter) {
@@ -148,11 +131,14 @@ public boolean checkSVCs(String id, double p, double q, double vControlled, doub
         boolean validated = true;
 
         if (connected && ValidationUtils.isMainComponent(config, mainComponent)) {
+            // Rule2: **reactivePowerSetpoint** must be 0 if p or q is missing (NaN)
             if (Double.isNaN(p) || Double.isNaN(q)) {
-                // Rule2: **reactivePowerSetpoint** must be 0 if p or q is missing (NaN)
-                validated = checkSVCsNaNValues(id, p, q, reactivePowerSetpoint);
+                // a validation error should be detected if there is a setpoint but no p or q
+                if (!isUndefinedOrZero(reactivePowerSetpoint, 0.0)) {
+                    LOGGER.warn("{} {}: {}: P={} Q={} reactivePowerSetpoint={}", ValidationType.SVCS, ValidationUtils.VALIDATION_ERROR, id, p, q, reactivePowerSetpoint);
+                    validated = false;
+                }
             } else {
-                // Rule1, Rule3, Rule4, Rule5
                 validated = checkSVCsValues(id, p, q, vControlled, vController, nominalVcontroller, reactivePowerSetpoint, voltageSetpoint, regulationMode, regulating, bMin, bMax, config);
             }
         }
@@ -164,15 +150,6 @@ public boolean checkSVCs(String id, double p, double q, double vControlled, doub
         return validated;
     }
 
-    private static boolean checkSVCsNaNValues(String id, double p, double q, double reactivePowerSetpoint) {
-        // a validation error should be detected if there is a setpoint but no p or q
-        if (!isUndefinedOrZero(reactivePowerSetpoint, 0.0)) {
-            LOGGER.warn("{} {}: {}: P={} Q={} reactivePowerSetpoint={}", ValidationType.SVCS, ValidationUtils.VALIDATION_ERROR, id, p, q, reactivePowerSetpoint);
-            return false;
-        }
-        return true;
-    }
-
     private static boolean checkSVCsValues(String id, double p, double q, double vControlled, double vController,
         double nominalVcontroller, double reactivePowerSetpoint, double voltageSetpoint,
         RegulationMode regulationMode, boolean regulating, double bMin, double bMax, ValidationConfig config) {
@@ -206,11 +183,9 @@ private static boolean checkSVCsValues(String id, double p, double q, double vCo
                 vController, vControlled, voltageSetpoint);
             validated = false;
         }
-
         // Rule5: if regulating is false then reactive power (q) should be equal to 0
         if (notRegulatingKo(regulating, q, config)) {
-            LOGGER.warn("{} {}: {}: regulator mode={} - Q={} ", ValidationType.SVCS, ValidationUtils.VALIDATION_ERROR,
-                id, regulationMode, q);
+            LOGGER.warn("{} {}: {}: regulator mode={} - Q={} ", ValidationType.SVCS, ValidationUtils.VALIDATION_ERROR, id, regulationMode, q);
             validated = false;
         }
         return validated;
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
@@ -122,13 +122,7 @@ public static double computeShuntExpectedQ(double bPerSection, int sectionCount,
         return -bPerSection * sectionCount * v * v;
     }
 
-    public record QBounds(double qMin, double qMax) { }
-
     public static double voltageFrom(double vBus, double nominalV) {
         return (Double.isNaN(vBus) || vBus == 0.0) ? nominalV : vBus;
     }
-
-    public static boolean isWithinInclusive(double value, double min, double max, double epsilon) {
-        return boundedWithin(min, max, value, epsilon);
-    }
 }
diff --git a/loadflow/loadflow-validation/src/test/java/com/powsybl/loadflow/validation/StaticVarCompensatorsValidationTest.java b/loadflow/loadflow-validation/src/test/java/com/powsybl/loadflow/validation/StaticVarCompensatorsValidationTest.java
@@ -7,8 +7,8 @@
  */
 package com.powsybl.loadflow.validation;
 
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
 import java.io.IOException;
@@ -17,7 +17,6 @@
 import org.apache.commons.io.output.NullWriter;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
-import org.mockito.Mockito;
 
 import com.powsybl.iidm.network.Bus;
 import com.powsybl.iidm.network.Network;
@@ -55,32 +54,32 @@ class StaticVarCompensatorsValidationTest extends AbstractValidationTest {
     void setUp() throws IOException {
         super.setUp();
 
-        Bus svcBus = Mockito.mock(Bus.class);
-        Mockito.when(svcBus.getV()).thenReturn(v);
-        Mockito.when(svcBus.isInMainConnectedComponent()).thenReturn(mainComponent);
-
-        svcBusView = Mockito.mock(BusView.class);
-        Mockito.when(svcBusView.getBus()).thenReturn(svcBus);
-        Mockito.when(svcBusView.getConnectableBus()).thenReturn(svcBus);
-
-        VoltageLevel voltageLevel = Mockito.mock(VoltageLevel.class);
-        Mockito.when(voltageLevel.getNominalV()).thenReturn(nominalV);
-
-        svcTerminal = Mockito.mock(Terminal.class);
-        Mockito.when(svcTerminal.getP()).thenReturn(p);
-        Mockito.when(svcTerminal.getQ()).thenReturn(q);
-        Mockito.when(svcTerminal.getBusView()).thenReturn(svcBusView);
-        Mockito.when(svcTerminal.getVoltageLevel()).thenReturn(voltageLevel);
-
-        svc = Mockito.mock(StaticVarCompensator.class);
-        Mockito.when(svc.getId()).thenReturn("svc");
-        Mockito.when(svc.getTerminal()).thenReturn(svcTerminal);
-        Mockito.when(svc.getReactivePowerSetpoint()).thenReturn(reactivePowerSetpoint);
-        Mockito.when(svc.getVoltageSetpoint()).thenReturn(voltageSetpoint);
-        Mockito.when(svc.getRegulationMode()).thenReturn(regulationMode);
-        Mockito.when(svc.isRegulating()).thenReturn(regulating);
-        Mockito.when(svc.getBmin()).thenReturn(bMin);
-        Mockito.when(svc.getBmax()).thenReturn(bMax);
+        Bus svcBus = mock(Bus.class);
+        when(svcBus.getV()).thenReturn(v);
+        when(svcBus.isInMainConnectedComponent()).thenReturn(mainComponent);
+
+        svcBusView = mock(BusView.class);
+        when(svcBusView.getBus()).thenReturn(svcBus);
+        when(svcBusView.getConnectableBus()).thenReturn(svcBus);
+
+        VoltageLevel voltageLevel = mock(VoltageLevel.class);
+        when(voltageLevel.getNominalV()).thenReturn(nominalV);
+
+        svcTerminal = mock(Terminal.class);
+        when(svcTerminal.getP()).thenReturn(p);
+        when(svcTerminal.getQ()).thenReturn(q);
+        when(svcTerminal.getBusView()).thenReturn(svcBusView);
+        when(svcTerminal.getVoltageLevel()).thenReturn(voltageLevel);
+
+        svc = mock(StaticVarCompensator.class);
+        when(svc.getId()).thenReturn("svc");
+        when(svc.getTerminal()).thenReturn(svcTerminal);
+        when(svc.getReactivePowerSetpoint()).thenReturn(reactivePowerSetpoint);
+        when(svc.getVoltageSetpoint()).thenReturn(voltageSetpoint);
+        when(svc.getRegulationMode()).thenReturn(regulationMode);
+        when(svc.isRegulating()).thenReturn(regulating);
+        when(svc.getBmin()).thenReturn(bMin);
+        when(svc.getBmax()).thenReturn(bMax);
     }
 
     @Test
@@ -169,19 +168,19 @@ void checkSvcsValues() {
     void checkSvcs() {
         // active power should be equal to 0
         assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
-        Mockito.when(svcTerminal.getP()).thenReturn(-39.8);
+        when(svcTerminal.getP()).thenReturn(-39.8);
         assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
 
         // the unit is disconnected
-        Mockito.when(svcBusView.getBus()).thenReturn(null);
+        when(svcBusView.getBus()).thenReturn(null);
         assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
     }
 
     @Test
     void checkNetworkSvcs() throws IOException {
-        Network network = Mockito.mock(Network.class);
-        Mockito.when(network.getId()).thenReturn("network");
-        Mockito.when(network.getStaticVarCompensatorStream()).thenAnswer(dummy -> Stream.of(svc));
+        Network network = mock(Network.class);
+        when(network.getId()).thenReturn("network");
+        when(network.getStaticVarCompensatorStream()).thenAnswer(dummy -> Stream.of(svc));
 
         assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(network, looseConfig, data));
 
@@ -218,4 +217,156 @@ void checkSVCReactivePowerSetpointWhenPOrQMissing() {
         assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
     }
 
+    // Rule 3: regulationMode = REACTIVE_POWER
+    // Test condition: required inputs missing => OK only if okMissingValues=true
+    @Test
+    void checkSVCReactivePowerModeMissingInputs() {
+        // Given regulation enabled, and regulationMode is REACTIVE_POWER
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.REACTIVE_POWER);
+        when(svc.isRegulating()).thenReturn(true);
+        // Given Rule1, Rule2 (OK)
+        when(svcTerminal.getP()).thenReturn(0.0);
+        when(svc.getReactivePowerSetpoint()).thenReturn(Double.NaN);
+        // When
+        strictConfig.setOkMissingValues(false);
+        // Then
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        // When
+        strictConfig.setOkMissingValues(true);
+        // Then
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    // Rule 3: regulationMode = REACTIVE_POWER
+    // Test condition: Q must match reactivePowerSetpoint within threshold
+    @Test
+    void checkSVCReactivePowerModeQMustMatchSetpoint() {
+        // Given regulation enabled, and regulationMode is REACTIVE_POWER
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.REACTIVE_POWER);
+        when(svc.isRegulating()).thenReturn(true);
+
+        when(svcTerminal.getP()).thenReturn(0.0);
+        when(svc.getReactivePowerSetpoint()).thenReturn(3.0);
+        // When
+        when(svcTerminal.getQ()).thenReturn(3.01);
+        // Then
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        // When
+        when(svcTerminal.getQ()).thenReturn(3.5); // diff > (threshold = 0.01)
+        // Then
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    // Rule 4: regulationMode = VOLTAGE
+    // Test condition: required inputs missing => OK only if okMissingValues=true
+    @Test
+    void checkSVCVoltageModeMissingInputs() {
+        // Given regulation enabled, and regulationMode is VOLTAGE
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.VOLTAGE);
+        when(svc.isRegulating()).thenReturn(true);
+        // Given Rule1, Rule 2 (OK)
+        when(svcTerminal.getQ()).thenReturn(0.0);
+        when(svc.getVoltageSetpoint()).thenReturn(Double.NaN);
+        // When
+        strictConfig.setOkMissingValues(false);
+        // Then
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        // When
+        strictConfig.setOkMissingValues(true);
+        // Then
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    // Rule 4: regulationMode = VOLTAGE
+    // Test condition: V controlled < V setPoint, then Q must match maxQ.
+    @Test
+    void checkSVCVoltageModeVLowerThanSetpoint() {
+        // Given regulation enabled, and regulationMode is VOLTAGE
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.VOLTAGE);
+        when(svc.isRegulating()).thenReturn(true);
+        when(svcTerminal.getP()).thenReturn(0.0);
+        // Given V controlled < V setpoint
+        Terminal regulatingTerminal = regulatingTerminalWithVoltage(360.0); // V controlled = 360.0
+        when(svc.getRegulatingTerminal()).thenReturn(regulatingTerminal);
+        when(svc.getVoltageSetpoint()).thenReturn(380.0); // V setpoint 380.0
+        double expectedQmax = -bMin * v * v;
+        assertEquals(1444.0, expectedQmax);
+        // Given q matching Qmax
+        when(svcTerminal.getQ()).thenReturn(expectedQmax);
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        // Given q not matching Qmax
+        when(svcTerminal.getQ()).thenReturn(1300.0);
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+
+    // Rule 4: regulationMode = VOLTAGE
+    // Test condition: V regulation > V setPoint, then Q must match minQ.
+    @Test
+    void checkSVCVoltageModeVHigherThanSetpoint() {
+        // Given regulation enabled, and regulationMode is VOLTAGE
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.VOLTAGE);
+        when(svc.isRegulating()).thenReturn(true);
+        when(svcTerminal.getP()).thenReturn(0.0);
+        // Given V controlled > V setpoint
+        Terminal regulatingTerminal = regulatingTerminalWithVoltage(400.0); // V controlled = 400.0
+        when(svc.getRegulatingTerminal()).thenReturn(regulatingTerminal);
+        when(svc.getVoltageSetpoint()).thenReturn(380.0); // V setpoint 380.0
+        double expectedQmin = -bMax * v * v;
+        assertEquals(-14440.0, expectedQmin);
+        // Given q matching Qmin
+        when(svcTerminal.getQ()).thenReturn(expectedQmin);
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+         // Given q not matching Qmin
+        when(svcTerminal.getQ()).thenReturn(-13000.0);
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    // Rule 4: regulationMode = VOLTAGE
+    // Test condition: V regulation ~ V setPoint, then Q must be within [minQ, maxQ].
+    @Test
+    void checkSVCVoltageModeVAtSetpoint() {
+        // Given regulation enabled, and regulationMode is VOLTAGE
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.VOLTAGE);
+        when(svc.isRegulating()).thenReturn(true);
+        when(svcTerminal.getP()).thenReturn(0.0);
+        // Given V controlled ~ V setpoint
+        Terminal regulatingTerminal = regulatingTerminalWithVoltage(380.0); // V controlled = 380.0.0
+        when(svc.getRegulatingTerminal()).thenReturn(regulatingTerminal);
+        when(svc.getVoltageSetpoint()).thenReturn(380.0); // V setpoint 380.0
+        double expectedQmax = -bMin * v * v;
+        assertEquals(1444.0, expectedQmax);
+        double expectedQmin = -bMax * v * v;
+        assertEquals(-14440.0, expectedQmin);
+        // Given q inside bounds [-14440.0, 1444.0]
+        when(svcTerminal.getQ()).thenReturn(0.0); // inside bounds [-14440.0, 1444.0]
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        // Given q outside bounds [-14440.0, 1444.0]
+        when(svcTerminal.getQ()).thenReturn(2000.0);
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    // Rule 5: if regulating is false then reactive power (Q) should be equal to 0 (within threshold)
+    @Test
+    void checkSVCWhenNoRegulatingQShouldBeZero() {
+        when(svc.getRegulationMode()).thenReturn(RegulationMode.VOLTAGE);
+        when(svc.isRegulating()).thenReturn(false);
+        when(svcTerminal.getP()).thenReturn(0.0);
+        when(svcTerminal.getQ()).thenReturn(0.009); // ~ threshold => invalid result
+        assertTrue(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+        when(svcTerminal.getQ()).thenReturn(0.02); // > threshold => invalid result
+        assertFalse(StaticVarCompensatorsValidation.INSTANCE.checkSVCs(svc, strictConfig, NullWriter.INSTANCE));
+    }
+
+    private Terminal regulatingTerminalWithVoltage(double vControlled) {
+        Bus controlledBus = mock(Bus.class);
+        when(controlledBus.getV()).thenReturn(vControlled);
+
+        BusView controlledBusView = mock(BusView.class);
+        when(controlledBusView.getBus()).thenReturn(controlledBus);
+
+        Terminal regulatingTerminal = mock(Terminal.class);
+        when(regulatingTerminal.getBusView()).thenReturn(controlledBusView);
+        return regulatingTerminal;
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -122,13 +122,7 @@ public static double computeShuntExpectedQ(double bPerSection, int sectionCount,`
`122`	`122`	`return -bPerSection * sectionCount * v * v;`
`123`	`123`	`}`
`124`	`124`
`125`		`- public record QBounds(double qMin, double qMax) { }`
`126`		`-`
`127`	`125`	`public static double voltageFrom(double vBus, double nominalV) {`
`128`	`126`	`return (Double.isNaN(vBus) \|\| vBus == 0.0) ? nominalV : vBus;`
`129`	`127`	`}`
`130`		`-`
`131`		`- public static boolean isWithinInclusive(double value, double min, double max, double epsilon) {`
`132`		`- return boundedWithin(min, max, value, epsilon);`
`133`		`- }`
`134`	`128`	`}`