removed referencePriority, added javadoc for LoadFlow API balance types

Signed-off-by: Damien Jeandemange <damien.jeandemange@artelys.com>

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/ActivePowerControl.java

@@ -75,16 +75,4 @@ default String getName() {
      */
     void setLongPF(float longPF);
 
-    /**
-     * Priority for use as powerflow voltage phase angle reference bus selection.
-     * 0 = don't care (default) 1 = highest priority. 2 is less than 1 and so on.
-     * @return reference priority
-     */
-    int getReferencePriority();
-
-    /**
-     * @param referencePriority new reference priority value
-     */
-    void setReferencePriority(int referencePriority);
-
 }

iidm/iidm-extensions/src/main/java/com/powsybl/iidm/network/extensions/ActivePowerControlAdder.java

@@ -26,6 +26,4 @@ default Class<ActivePowerControl> getExtensionClass() {
     ActivePowerControlAdder<I> withNormalPF(float normalPF);
 
     ActivePowerControlAdder<I> withLongPF(float longPF);
-
-    ActivePowerControlAdder<I> withReferencePriority(int referencePriority);
 }

iidm/iidm-impl/src/main/java/com/powsybl/iidm/network/impl/extensions/ActivePowerControlAdderImpl.java

@@ -21,15 +21,14 @@ public class ActivePowerControlAdderImpl<I extends Injection<I>>
     private float shortPF;
     private float normalPF;
     private float longPF;
-    private int referencePriority;
 
     protected ActivePowerControlAdderImpl(I extendable) {
         super(extendable);
     }
 
     @Override
     protected ActivePowerControlImpl<I> createExtension(I extendable) {
-        return new ActivePowerControlImpl<>(extendable, participate, droop, shortPF, normalPF, longPF, referencePriority);
+        return new ActivePowerControlImpl<>(extendable, participate, droop, shortPF, normalPF, longPF);
     }
 
     @Override
@@ -62,10 +61,4 @@ public ActivePowerControlAdder<I> withLongPF(float longPF) {
         return this;
     }
 
-    @Override
-    public ActivePowerControlAdder<I> withReferencePriority(int referencePriority) {
-        this.referencePriority = referencePriority;
-        return this;
-    }
-
 }

iidm/iidm-impl/src/main/java/com/powsybl/iidm/network/impl/extensions/ActivePowerControlImpl.java

@@ -11,7 +11,6 @@
 import com.powsybl.iidm.network.extensions.ActivePowerControl;
 import com.powsybl.iidm.network.impl.AbstractMultiVariantIdentifiableExtension;
 import gnu.trove.list.array.TFloatArrayList;
-import gnu.trove.list.array.TIntArrayList;
 
 import java.util.List;
 
@@ -27,7 +26,6 @@ public class ActivePowerControlImpl<T extends Injection<T>> extends AbstractMult
     private final TFloatArrayList shortPF;
     private final TFloatArrayList normalPF;
     private final TFloatArrayList longPF;
-    private final TIntArrayList referencePriority;
 
     private final List<TFloatArrayList> allTFloatArrayLists;
 
@@ -36,24 +34,21 @@ public ActivePowerControlImpl(T component,
                                   float droop,
                                   float shortPF,
                                   float normalPF,
-                                  float longPF,
-                                  int referencePriority) {
+                                  float longPF) {
         super(component);
         int variantArraySize = getVariantManagerHolder().getVariantManager().getVariantArraySize();
         this.participate = new TBooleanArrayList(variantArraySize);
         this.droop = new TFloatArrayList(variantArraySize);
         this.shortPF = new TFloatArrayList(variantArraySize);
         this.normalPF = new TFloatArrayList(variantArraySize);
         this.longPF = new TFloatArrayList(variantArraySize);
-        this.referencePriority = new TIntArrayList(variantArraySize);
         this.allTFloatArrayLists = List.of(this.droop, this.shortPF, this.normalPF, this.longPF);
         for (int i = 0; i < variantArraySize; i++) {
             this.participate.add(participate);
             this.droop.add(droop);
             this.shortPF.add(shortPF);
             this.normalPF.add(normalPF);
             this.longPF.add(longPF);
-            this.referencePriority.add(referencePriority);
         }
     }
 
@@ -98,31 +93,20 @@ public void setLongPF(float longPF) {
 
     }
 
-    public int getReferencePriority() {
-        return referencePriority.get(getVariantIndex());
-    }
-
-    public void setReferencePriority(int referencePriority) {
-        this.referencePriority.set(getVariantIndex(), referencePriority);
-    }
-
     @Override
     public void extendVariantArraySize(int initVariantArraySize, int number, int sourceIndex) {
         participate.ensureCapacity(participate.size() + number);
         allTFloatArrayLists.forEach(fl -> fl.ensureCapacity(fl.size() + number));
-        referencePriority.ensureCapacity(referencePriority.size() + number);
         for (int i = 0; i < number; ++i) {
             participate.add(participate.get(sourceIndex));
             allTFloatArrayLists.forEach(fl -> fl.add(fl.get(sourceIndex)));
-            referencePriority.add(referencePriority.get(sourceIndex));
         }
     }
 
     @Override
     public void reduceVariantArraySize(int number) {
         participate.remove(participate.size() - number, number);
         allTFloatArrayLists.forEach(fl -> fl.remove(fl.size() - number, number));
-        referencePriority.remove(referencePriority.size() - number, number);
     }
 
     @Override
@@ -136,7 +120,6 @@ public void allocateVariantArrayElement(int[] indexes, int sourceIndex) {
             participate.set(index, participate.get(sourceIndex));
             droop.set(index, droop.get(sourceIndex));
             allTFloatArrayLists.forEach(fl -> fl.set(index, fl.get(sourceIndex)));
-            referencePriority.set(index, referencePriority.get(sourceIndex));
         }
     }
 }

iidm/iidm-tck/src/test/java/com/powsybl/iidm/network/tck/extensions/AbstractActivePowerControlTest.java

@@ -38,7 +38,6 @@ public void test() {
                 .withShortPF(1.1f)
                 .withNormalPF(1.2f)
                 .withLongPF(1.3f)
-                .withReferencePriority(1)
                 .add();
         ActivePowerControl<Battery> activePowerControl = bat.getExtension(ActivePowerControl.class);
         assertEquals("activePowerControl", activePowerControl.getName());
@@ -50,7 +49,6 @@ public void test() {
         activePowerControl.setShortPF(2f);
         activePowerControl.setNormalPF(3f);
         activePowerControl.setLongPF(4f);
-        activePowerControl.setReferencePriority(0);
         checkValues2(activePowerControl);
     }
 
@@ -69,7 +67,6 @@ public void variantsCloneTest() {
                 .withShortPF(1.1f)
                 .withNormalPF(1.2f)
                 .withLongPF(1.3f)
-                .withReferencePriority(1)
                 .add();
         ActivePowerControl<Battery> activePowerControl = bat.getExtension(ActivePowerControl.class);
         assertNotNull(activePowerControl);
@@ -87,7 +84,6 @@ public void variantsCloneTest() {
         activePowerControl.setShortPF(2f);
         activePowerControl.setNormalPF(3f);
         activePowerControl.setLongPF(4f);
-        activePowerControl.setReferencePriority(0);
         checkValues2(activePowerControl);
         variantManager.setWorkingVariant(INITIAL_VARIANT_ID);
         checkValues1(activePowerControl);
@@ -117,7 +113,6 @@ private static void checkValues1(ActivePowerControl<Battery> activePowerControl)
         assertEquals(1.1f, activePowerControl.getShortPF(), 0f);
         assertEquals(1.2f, activePowerControl.getNormalPF(), 0f);
         assertEquals(1.3f, activePowerControl.getLongPF(), 0f);
-        assertEquals(1, activePowerControl.getReferencePriority());
     }
 
     private static void checkValues2(ActivePowerControl<Battery> activePowerControl) {
@@ -126,6 +121,5 @@ private static void checkValues2(ActivePowerControl<Battery> activePowerControl)
         assertEquals(2f, activePowerControl.getShortPF(), 0f);
         assertEquals(3f, activePowerControl.getNormalPF(), 0f);
         assertEquals(4f, activePowerControl.getLongPF(), 0f);
-        assertEquals(0, activePowerControl.getReferencePriority());
     }
 }

iidm/iidm-xml-converter/src/main/java/com/powsybl/iidm/xml/extensions/ActivePowerControlXmlSerializer.java

@@ -36,7 +36,6 @@ public void write(ActivePowerControl activePowerControl, XmlWriterContext contex
         XmlUtil.writeFloat("shortPF", activePowerControl.getShortPF(), context.getWriter());
         XmlUtil.writeFloat("normalPF", activePowerControl.getNormalPF(), context.getWriter());
         XmlUtil.writeFloat("longPF", activePowerControl.getLongPF(), context.getWriter());
-        XmlUtil.writeInt("referencePriority", activePowerControl.getReferencePriority(), context.getWriter());
     }
 
     @Override
@@ -46,14 +45,12 @@ public ActivePowerControl<T> read(T identifiable, XmlReaderContext context) {
         float shortPF = XmlUtil.readOptionalFloatAttribute(context.getReader(), "shortPF", 0f);
         float normalPF = XmlUtil.readOptionalFloatAttribute(context.getReader(), "normalPF", 0f);
         float longPF = XmlUtil.readOptionalFloatAttribute(context.getReader(), "longPF", 0f);
-        int referencePriority = XmlUtil.readOptionalIntegerAttribute(context.getReader(), "referencePriority", 0);
         ActivePowerControlAdder<T> activePowerControlAdder = identifiable.newExtension(ActivePowerControlAdder.class);
         return activePowerControlAdder.withParticipate(participate)
                 .withDroop(droop)
                 .withShortPF(shortPF)
                 .withNormalPF(normalPF)
                 .withLongPF(longPF)
-                .withReferencePriority(referencePriority)
                 .add();
     }
 }

iidm/iidm-xml-converter/src/test/java/com/powsybl/iidm/xml/extensions/ActivePowerControlXmlTest.java

@@ -34,11 +34,11 @@ public void test() throws IOException {
         Battery bat = network.getBattery("BAT");
         assertNotNull(bat);
 
-        ActivePowerControl<Battery> activePowerControl = new ActivePowerControlImpl<>(bat, true, 4f, 1.2f, 1.3f, 1.4f, 1);
+        ActivePowerControl<Battery> activePowerControl = new ActivePowerControlImpl<>(bat, true, 4f, 1.2f, 1.3f, 1.4f);
         bat.addExtension(ActivePowerControl.class, activePowerControl);
 
         Generator generator = network.getGenerator("GEN");
-        generator.addExtension(ActivePowerControl.class, new ActivePowerControlImpl<>(generator, false, 3, 1f, 2f, 3f, 0));
+        generator.addExtension(ActivePowerControl.class, new ActivePowerControlImpl<>(generator, false, 3, 1f, 2f, 3f));
 
         Network network2 = roundTripXmlTest(network,
                 NetworkXml::writeAndValidate,
@@ -55,7 +55,6 @@ public void test() throws IOException {
         assertEquals(activePowerControl.getShortPF(), activePowerControl2.getShortPF(), 0f);
         assertEquals(activePowerControl.getNormalPF(), activePowerControl2.getNormalPF(), 0f);
         assertEquals(activePowerControl.getLongPF(), activePowerControl2.getLongPF(), 0f);
-        assertEquals(activePowerControl.getReferencePriority(), activePowerControl2.getReferencePriority());
         assertEquals(activePowerControl.getName(), activePowerControl2.getName());
     }
 }

iidm/iidm-xml-converter/src/test/resources/V1_8/activePowerControlRoundTripRef.xml

@@ -30,9 +30,9 @@
     <iidm:line id="NHV1_NHV2_1" r="3.0" x="33.0" g1="0.0" b1="1.93E-4" g2="0.0" b2="1.93E-4" bus1="NGEN" connectableBus1="NGEN" voltageLevelId1="VLGEN" bus2="NBAT" connectableBus2="NBAT" voltageLevelId2="VLBAT"/>
     <iidm:line id="NHV1_NHV2_2" r="3.0" x="33.0" g1="0.0" b1="1.93E-4" g2="0.0" b2="1.93E-4" bus1="NGEN" connectableBus1="NGEN" voltageLevelId1="VLGEN" bus2="NBAT" connectableBus2="NBAT" voltageLevelId2="VLBAT"/>
     <iidm:extension id="GEN">
-        <apc:activePowerControl participate="false" droop="3.0" shortPF="1.0" normalPF="2.0" longPF="3.0" referencePriority="0"/>
+        <apc:activePowerControl participate="false" droop="3.0" shortPF="1.0" normalPF="2.0" longPF="3.0"/>
     </iidm:extension>
     <iidm:extension id="BAT">
-        <apc:activePowerControl participate="true" droop="4.0" shortPF="1.2" normalPF="1.3" longPF="1.4" referencePriority="1"/>
+        <apc:activePowerControl participate="true" droop="4.0" shortPF="1.2" normalPF="1.3" longPF="1.4"/>
     </iidm:extension>
 </iidm:network>

loadflow/loadflow-api/src/main/java/com/powsybl/loadflow/LoadFlowParameters.java

@@ -33,14 +33,41 @@ public enum VoltageInitMode {
         DC_VALUES // preprocessing to compute DC angles
     }
 
+    /**
+     * BalanceType enum describes the various options for active power slack distribution
+     */
     public enum BalanceType {
+        /**
+         * active power slack distribution on generators, proportional to generator targetP
+         */
         PROPORTIONAL_TO_GENERATION_P,
+        /**
+         * active power slack distribution on generators, proportional to generator maxP
+         */
         PROPORTIONAL_TO_GENERATION_P_MAX,
+        /**
+         * active power slack distribution on generators, proportional to generator maxP - targetP
+         */
         PROPORTIONAL_TO_GENERATION_REMAINING_MARGIN,
+        /**
+         * active power slack distribution on generators, proportional to shortPF (see ActivePowerControl extension)
+         */
         PROPORTIONAL_TO_GENERATION_SHORT_PF,
+        /**
+         * active power slack distribution on generators, proportional to normalPF (see ActivePowerControl extension)
+         */
         PROPORTIONAL_TO_GENERATION_NORMAL_PF,
+        /**
+         * active power slack distribution on generators, proportional to longPF (see ActivePowerControl extension)
+         */
         PROPORTIONAL_TO_GENERATION_LONG_PF,
+        /**
+         * active power slack distribution on all loads
+         */
         PROPORTIONAL_TO_LOAD,
+        /**
+         * active power slack distribution on conforming loads (see LoadDetails extension)
+         */
         PROPORTIONAL_TO_CONFORM_LOAD,
     }