add regulating element for generator, vsc and svc creation

Signed-off-by: Etienne LESOT <etienne.lesot@rte-france.com>

docs/user_guide/flowdecomposition.rst

@@ -108,8 +108,8 @@ As we cannot set a PST on an interconnection, we set an equivalent null load cal
     >>> network.get_generators()
                        name energy_source  target_p   min_p   max_p   min_q   max_q  rated_s reactive_limits_kind  target_v  target_q  voltage_regulator_on regulated_element_id   p   q   i voltage_level_id     bus_id  connected
     id
-    FGEN  11_generator              OTHER     100.0 -1000.0  1000.0 -1000.0  1000.0      NaN              MIN_MAX     400.0       0.0                  True                      NaN NaN NaN          FGEN  1  FGEN  1_0       True
-    BLOAD 12_generator              OTHER     100.0 -1000.0  1000.0 -1000.0  1000.0      NaN              MIN_MAX     400.0       0.0                  True                      NaN NaN NaN          BLOAD 1  BLOAD 1_1       True
+    FGEN  11_generator              OTHER     100.0 -1000.0  1000.0 -1000.0  1000.0      NaN              MIN_MAX     400.0       0.0                  True   FGEN  11_generator NaN NaN NaN          FGEN  1  FGEN  1_0       True
+    BLOAD 12_generator              OTHER     100.0 -1000.0  1000.0 -1000.0  1000.0      NaN              MIN_MAX     400.0       0.0                  True   BLOAD 12_generator NaN NaN NaN          BLOAD 1  BLOAD 1_1       True
     >>> network.get_loads()
                       name       type     p0   q0   p   q   i voltage_level_id     bus_id  connected
     id                                                                                          

docs/user_guide/network.rst

@@ -132,8 +132,8 @@ For example, you can retrieve generators data as follows:
     >>> network.get_generators() # doctest: +NORMALIZE_WHITESPACE
          name energy_source  target_p    min_p   max_p          min_q          max_q  rated_s reactive_limits_kind  target_v  target_q  voltage_regulator_on regulated_element_id   p   q   i voltage_level_id   bus_id  connected
     id
-    GEN               OTHER     607.0 -9999.99  4999.0  -9.999990e+03   9.999990e+03      NaN              MIN_MAX      24.5     301.0                  True                      NaN NaN NaN            VLGEN  VLGEN_0       True
-    GEN2              OTHER     607.0 -9999.99  4999.0 -1.797693e+308  1.797693e+308      NaN              MIN_MAX      24.5     301.0                  True                      NaN NaN NaN            VLGEN  VLGEN_0       True
+    GEN               OTHER     607.0 -9999.99  4999.0  -9.999990e+03   9.999990e+03      NaN              MIN_MAX      24.5     301.0                  True                  GEN NaN NaN NaN            VLGEN  VLGEN_0       True
+    GEN2              OTHER     607.0 -9999.99  4999.0 -1.797693e+308  1.797693e+308      NaN              MIN_MAX      24.5     301.0                  True                 GEN2 NaN NaN NaN            VLGEN  VLGEN_0       True
 
 Most dataframes are indexed on the ID of the elements.
 However, some more complex dataframes have a multi-index : for example,

java/src/main/java/com/powsybl/dataframe/network/NetworkDataframes.java

@@ -286,22 +286,13 @@ private static String getRegulatedElementId(Injection<?> injection) {
         } else {
             throw new UnsupportedOperationException(String.format("%s is neither a generator, a vsc station or a var static compensator", injection.getId()));
         }
-        if (terminal.getVoltageLevel().getTopologyKind() == TopologyKind.BUS_BREAKER) {
-            //Not supported for the moment
-            return null;
-        }
         return terminal.getConnectable() != null ? terminal.getConnectable().getId() : null;
     }
 
     private static void setRegulatedElement(Injection<?> injection, String elementId) {
         Network network = injection.getNetwork();
         Identifiable<?> identifiable = network.getIdentifiable(elementId);
         if (identifiable instanceof Injection) {
-            Terminal terminal = ((Injection<?>) identifiable).getTerminal();
-            if (terminal.getVoltageLevel().getTopologyKind() == TopologyKind.BUS_BREAKER) {
-                throw new UnsupportedOperationException("Cannot set regulated element to " + elementId +
-                        ": not currently supported for bus breaker topologies.");
-            }
             if (injection instanceof Generator) {
                 ((Generator) injection).setRegulatingTerminal(((Injection<?>) identifiable).getTerminal());
             } else if (injection instanceof VscConverterStation) {

java/src/main/java/com/powsybl/dataframe/network/adders/GeneratorDataframeAdder.java

@@ -12,9 +12,7 @@
 import com.powsybl.dataframe.update.IntSeries;
 import com.powsybl.dataframe.update.StringSeries;
 import com.powsybl.dataframe.update.UpdatingDataframe;
-import com.powsybl.iidm.network.EnergySource;
-import com.powsybl.iidm.network.GeneratorAdder;
-import com.powsybl.iidm.network.Network;
+import com.powsybl.iidm.network.*;
 
 import java.util.Collections;
 import java.util.List;
@@ -43,7 +41,8 @@ public class GeneratorDataframeAdder extends AbstractSimpleAdder {
             SeriesMetadata.doubles("target_q"),
             SeriesMetadata.doubles("rated_s"),
             SeriesMetadata.doubles("target_v"),
-            SeriesMetadata.booleans("voltage_regulator_on")
+            SeriesMetadata.booleans("voltage_regulator_on"),
+            SeriesMetadata.strings("regulating_element_id")
     );
 
     @Override
@@ -63,6 +62,7 @@ private static class GeneratorSeries extends InjectionSeries {
         private final IntSeries voltageRegulatorOn;
         private final StringSeries energySource;
         private final StringSeries busOrBusbarSections;
+        private final StringSeries regulatingElements;
 
         GeneratorSeries(UpdatingDataframe dataframe) {
             super(dataframe);
@@ -76,11 +76,13 @@ private static class GeneratorSeries extends InjectionSeries {
             this.voltageRegulatorOn = dataframe.getInts("voltage_regulator_on");
             this.energySource = dataframe.getStrings("energy_source");
             this.busOrBusbarSections = dataframe.getStrings("bus_or_busbar_section_id");
+            this.regulatingElements = dataframe.getStrings("regulating_element_id");
         }
 
         GeneratorAdder createAdder(Network network, int row) {
             GeneratorAdder adder = getVoltageLevelOrThrowWithBusOrBusbarSectionId(network, row, voltageLevels, busOrBusbarSections)
                     .newGenerator();
+
             setInjectionAttributes(adder, row);
             applyIfPresent(maxP, row, adder::setMaxP);
             applyIfPresent(minP, row, adder::setMinP);
@@ -90,6 +92,7 @@ GeneratorAdder createAdder(Network network, int row) {
             applyIfPresent(ratedS, row, adder::setRatedS);
             applyBooleanIfPresent(voltageRegulatorOn, row, adder::setVoltageRegulatorOn);
             applyIfPresent(energySource, row, EnergySource.class, adder::setEnergySource);
+            applyIfPresent(regulatingElements, row, elementId -> Util.setRegulatingTerminal(adder::setRegulatingTerminal, network, elementId));
             return adder;
         }
     }

java/src/main/java/com/powsybl/dataframe/network/adders/SvcDataframeAdder.java

@@ -11,9 +11,7 @@
 import com.powsybl.dataframe.update.DoubleSeries;
 import com.powsybl.dataframe.update.StringSeries;
 import com.powsybl.dataframe.update.UpdatingDataframe;
-import com.powsybl.iidm.network.Network;
-import com.powsybl.iidm.network.StaticVarCompensator;
-import com.powsybl.iidm.network.StaticVarCompensatorAdder;
+import com.powsybl.iidm.network.*;
 
 import java.util.Collections;
 import java.util.List;
@@ -39,7 +37,8 @@ public class SvcDataframeAdder extends AbstractSimpleAdder {
             SeriesMetadata.doubles("b_min"),
             SeriesMetadata.strings("regulation_mode"),
             SeriesMetadata.doubles("target_v"),
-            SeriesMetadata.doubles("target_q")
+            SeriesMetadata.doubles("target_q"),
+            SeriesMetadata.strings("regulating_element_id")
     );
 
     @Override
@@ -56,6 +55,7 @@ private static class StaticVarCompensatorSeries extends InjectionSeries {
         private final DoubleSeries targetV;
         private final DoubleSeries targetQ;
         private final StringSeries busOrBusbarSections;
+        private final StringSeries regulatingElements;
 
         StaticVarCompensatorSeries(UpdatingDataframe dataframe) {
             super(dataframe);
@@ -66,6 +66,7 @@ private static class StaticVarCompensatorSeries extends InjectionSeries {
             this.targetV = dataframe.getDoubles("target_v");
             this.regulationModes = dataframe.getStrings("regulation_mode");
             this.busOrBusbarSections = dataframe.getStrings("bus_or_busbar_section_id");
+            this.regulatingElements = dataframe.getStrings("regulating_element_id");
         }
 
         StaticVarCompensatorAdder createAdder(Network network, int row) {
@@ -77,6 +78,7 @@ StaticVarCompensatorAdder createAdder(Network network, int row) {
             applyIfPresent(targetQ, row, adder::setReactivePowerSetpoint);
             applyIfPresent(targetV, row, adder::setVoltageSetpoint);
             applyIfPresent(regulationModes, row, StaticVarCompensator.RegulationMode.class, adder::setRegulationMode);
+            applyIfPresent(regulatingElements, row, elementId -> Util.setRegulatingTerminal(adder::setRegulatingTerminal, network, elementId));
             return adder;
         }
     }

java/src/main/java/com/powsybl/dataframe/network/adders/TwoWindingsTransformerSeries.java

@@ -1,3 +1,10 @@
+/**
+ * Copyright (c) 2023, 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.dataframe.network.adders;
 
 import com.powsybl.commons.PowsyblException;

java/src/main/java/com/powsybl/dataframe/network/adders/Util.java

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2023, 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.dataframe.network.adders;
+
+import com.powsybl.iidm.network.Identifiable;
+import com.powsybl.iidm.network.Injection;
+import com.powsybl.iidm.network.Network;
+import com.powsybl.iidm.network.Terminal;
+
+import java.util.function.Consumer;
+
+/**
+ * @author Etienne Lesot <etienne.lesot at rte-france.com>
+ */
+public final class Util {
+
+    private Util() {
+
+    }
+
+    public static void setRegulatingTerminal(Consumer<Terminal> adder, Network network, String elementId) {
+        Identifiable<?> injection = network.getIdentifiable(elementId);
+        if (injection instanceof Injection<?>) {
+            adder.accept(((Injection<?>) injection).getTerminal());
+        } else {
+            throw new UnsupportedOperationException("Cannot set regulated element to " + elementId +
+                    ": the regulated element may only be a busbar section or an injection.");
+        }
+    }
+}

java/src/main/java/com/powsybl/dataframe/network/adders/VscStationDataframeAdder.java

@@ -39,7 +39,8 @@ public class VscStationDataframeAdder extends AbstractSimpleAdder {
             SeriesMetadata.doubles("target_v"),
             SeriesMetadata.doubles("target_q"),
             SeriesMetadata.doubles("loss_factor"),
-            SeriesMetadata.booleans("voltage_regulator_on")
+            SeriesMetadata.booleans("voltage_regulator_on"),
+            SeriesMetadata.strings("regulating_element_id")
     );
 
     @Override
@@ -55,6 +56,7 @@ private static class VscStationSeries extends InjectionSeries {
         private final DoubleSeries targetQ;
         private final IntSeries voltageRegulatorOn;
         private final StringSeries busOrBusbarSections;
+        private final StringSeries regulatingElements;
 
         VscStationSeries(UpdatingDataframe dataframe) {
             super(dataframe);
@@ -64,6 +66,7 @@ private static class VscStationSeries extends InjectionSeries {
             this.targetQ = dataframe.getDoubles("target_q");
             this.voltageRegulatorOn = dataframe.getInts("voltage_regulator_on");
             this.busOrBusbarSections = dataframe.getStrings("bus_or_busbar_section_id");
+            this.regulatingElements = dataframe.getStrings("regulating_element_id");
         }
 
         VscConverterStationAdder createAdder(Network network, int row) {
@@ -74,6 +77,7 @@ VscConverterStationAdder createAdder(Network network, int row) {
             applyIfPresent(targetV, row, adder::setVoltageSetpoint);
             applyIfPresent(targetQ, row, adder::setReactivePowerSetpoint);
             applyBooleanIfPresent(voltageRegulatorOn, row, adder::setVoltageRegulatorOn);
+            applyIfPresent(regulatingElements, row, elementId -> Util.setRegulatingTerminal(adder::setRegulatingTerminal, network, elementId));
             return adder;
         }
     }

tests/test_network.py

@@ -559,7 +559,7 @@ def test_update_generators_data_frame():
     generators = n.get_generators()
     assert 607 == generators['target_p']['GEN']
     assert generators['voltage_regulator_on']['GEN']
-    assert '' == generators['regulated_element_id']['GEN']
+    assert 'GEN' == generators['regulated_element_id']['GEN']
     generators2 = pd.DataFrame(data=[[608.0, 302.0, 25.0, False]],
                                columns=['target_p', 'target_q', 'target_v', 'voltage_regulator_on'], index=['GEN'])
     n.update_generators(generators2)
@@ -586,13 +586,12 @@ def test_regulated_terminal_node_breaker():
 def test_regulated_terminal_bus_breaker():
     n = pp.network.create_eurostag_tutorial_example1_network()
     generators = n.get_generators()
-    assert '' == generators['regulated_element_id']['GEN']
-
+    assert 'GEN' == generators['regulated_element_id']['GEN']
     with pytest.raises(pp.PyPowsyblError):
         n.update_generators(id='GEN', regulated_element_id='NHV1')
-    with pytest.raises(pp.PyPowsyblError):
-        n.update_generators(id='GEN', regulated_element_id='LOAD')
-
+    n.update_generators(id='GEN', regulated_element_id='LOAD')
+    generators = n.get_generators()
+    assert 'LOAD' == generators['regulated_element_id']['GEN']
 
 def test_update_unknown_data():
     n = pp.network.create_eurostag_tutorial_example1_network()

tests/test_network_elements_creation.py

@@ -549,7 +549,7 @@ def test_create_network_and_run_loadflow():
 
     generators = pd.DataFrame.from_records(index='id', data=[
         {'voltage_level_id': 'VL1', 'id': 'GEN', 'bus_id': 'B1', 'target_p': 100, 'min_p': 0, 'max_p': 200,
-         'target_v': 400, 'voltage_regulator_on': True}
+         'target_v': 400, 'voltage_regulator_on': True, 'regulating_element_id': 'LOAD'}
     ])
     n.create_generators(generators)
 

tests/test_per_unit.py

@@ -47,12 +47,10 @@ def test_generator_per_unit():
                  'target_v',
                  'target_q', 'voltage_regulator_on', 'regulated_element_id', 'p', 'q', 'i', 'voltage_level_id',
                  'bus_id', 'connected'],
-        data=[['GEN', '', 'OTHER', 6.07, -100, 49.99, -100, 100, None, 'MIN_MAX', 1.02, 3.01, True, '', -3.03, -1.12641,
-               3.16461,
-               'VLGEN', 'VLGEN_0', True],
-              ['GEN2', '', 'OTHER', 6.07, -100, 49.99, -1.79769e+306, 1.79769e+306, None, 'MIN_MAX', 1.02, 3.01, True, '',
-               -3.03,
-               -1.13, 3.16, 'VLGEN', 'VLGEN_0', True]])
+        data=[['GEN', '', 'OTHER', 6.07, -100, 49.99, -100, 100, None, 'MIN_MAX', 1.02, 3.01, True, 'GEN', -3.03,
+               -1.12641, 3.16461, 'VLGEN', 'VLGEN_0', True],
+              ['GEN2', '', 'OTHER', 6.07, -100, 49.99, -1.79769e+306, 1.79769e+306, None, 'MIN_MAX', 1.02, 3.01, True,
+               'GEN2', -3.03, -1.13, 3.16, 'VLGEN', 'VLGEN_0', True]])
     pd.testing.assert_frame_equal(expected, n.get_generators(), check_dtype=False, atol=1e-2)
     generators2 = pd.DataFrame(data=[[6.080, 3.02, 1.1, False, False]],
                                columns=['target_p', 'target_q', 'target_v', 'voltage_regulator_on', 'connected'],
@@ -64,11 +62,10 @@ def test_generator_per_unit():
                  'target_v',
                  'target_q', 'voltage_regulator_on', 'regulated_element_id', 'p', 'q', 'i', 'voltage_level_id',
                  'bus_id', 'connected'],
-        data=[['GEN', '', 'OTHER', 6.07, -100, 49.99, -100, 100, None, 'MIN_MAX', 1.1, 3.02, False, '', -3.03, -1.12641, NaN,
-               'VLGEN', '', False],
-              ['GEN2', '', 'OTHER', 6.07, -100, 49.99, -1.79769e+306, 1.79769e+306, None, 'MIN_MAX', 1.02, 3.01, True, '',
-               -3.03,
-               -1.13, 3.16, 'VLGEN', 'VLGEN_0', True]])
+        data=[['GEN', '', 'OTHER', 6.07, -100, 49.99, -100, 100, None, 'MIN_MAX', 1.1, 3.02, False, 'GEN', -3.03,
+               -1.12641, NaN, 'VLGEN', '', False],
+              ['GEN2', '', 'OTHER', 6.07, -100, 49.99, -1.79769e+306, 1.79769e+306, None, 'MIN_MAX', 1.02, 3.01, True,
+               'GEN2', -3.03, -1.13, 3.16, 'VLGEN', 'VLGEN_0', True]])
     pd.testing.assert_frame_equal(expected, n.get_generators(), check_dtype=False, atol=1e-2)