Automation systems (#2779)

Signed-off-by: Olivier Perrin <olivier.perrin@rte-france.com>

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/AutomationSystem.java

@@ -0,0 +1,26 @@
+/**
+ * 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.iidm.network;
+
+/**
+ * @author Olivier Perrin {@literal <olivier.perrin at rte-france.com>}
+ */
+public interface AutomationSystem<I extends AutomationSystem<I>> extends Identifiable<I> {
+
+    /**
+     * Says if the system is active or not.
+     * @return <code>true</code> is the automation system is enabled
+     */
+    boolean isEnabled();
+
+    /**
+     * Change the state of the automation system
+     * @param enabled <code>true</code> to enable the automation system
+     */
+    void setEnabled(boolean enabled);
+}

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/IdentifiableType.java

@@ -28,5 +28,6 @@ public enum IdentifiableType {
     SHUNT_COMPENSATOR,
     DANGLING_LINE,
     STATIC_VAR_COMPENSATOR,
-    HVDC_CONVERTER_STATION
+    HVDC_CONVERTER_STATION,
+    OVERLOAD_MANAGEMENT_SYSTEM
 }

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/Network.java

@@ -827,6 +827,28 @@ default VoltageLevelAdder newVoltageLevel() {
      */
     ThreeWindingsTransformer getThreeWindingsTransformer(String id);
 
+    /**
+     * Get all overload management systems.
+     */
+    Iterable<OverloadManagementSystem> getOverloadManagementSystems();
+
+    /**
+     * Get all overload management systems.
+     */
+    Stream<OverloadManagementSystem> getOverloadManagementSystemStream();
+
+    /**
+     * Get the overload management system count.
+     */
+    int getOverloadManagementSystemCount();
+
+    /**
+     * Get an overload management system.
+     *
+     * @param id the id or an alias of the overload management system
+     */
+    OverloadManagementSystem getOverloadManagementSystem(String id);
+
     /**
      * Get all generators.
      */

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/OverloadManagementSystem.java

@@ -0,0 +1,145 @@
+/**
+ * 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.iidm.network;
+
+import java.util.List;
+
+/**
+ * An overload management system.
+ *
+ * @author Olivier Perrin {@literal <olivier.perrin at rte-france.com>}
+ */
+public interface OverloadManagementSystem extends AutomationSystem<OverloadManagementSystem> {
+
+    interface Tripping {
+        enum Type {
+            BRANCH_TRIPPING,
+            THREE_WINDINGS_TRANSFORMER_TRIPPING,
+            SWITCH_TRIPPING
+        }
+
+        Type getType();
+
+        /**
+         * Get the unique key of the tripping.
+         * <p>This key is unique for a single overload management system, but it can be reused
+         * for another overload management system).</p>
+         * @return the tripping key
+         */
+        String getKey();
+
+        /**
+         * Get the name (if available) or the key of the tripping.
+         * <p>This method result is used for reporting purposes.</p>
+         * @return the name (if available) or the key of the tripping
+         */
+        String getNameOrKey();
+
+        /**
+         * Set the name of the tripping.
+         * <p>This name is facultative. It is used only for reporting purposes.</p>
+         * @param name the name of the tripping
+         * @see #getNameOrKey()
+         */
+        Tripping setName(String name);
+
+        /**
+         * Return the maximum acceptable current value (in A).
+         * @return the maximum current value
+         */
+        double getCurrentLimit();
+
+        Tripping setCurrentLimit(double currentLimit);
+
+        /**
+         * Tell if the tripping operation consists in opening (<code>true</code>) or closing (<code>false</code>)
+         * the element (branch, three windings transformer or switch) to operate.
+         * @return <code>true</code> it the operation consists in opening the element, else <code>false</code>.
+         */
+        boolean isOpenAction();
+
+        Tripping setOpenAction(boolean open);
+    }
+
+    interface SwitchTripping extends Tripping {
+        @Override
+        default Type getType() {
+            return Type.SWITCH_TRIPPING;
+        }
+
+        String getSwitchToOperateId();
+
+        SwitchTripping setSwitchToOperateId(String switchToOperateId);
+    }
+
+    interface BranchTripping extends Tripping {
+        @Override
+        default Type getType() {
+            return Type.BRANCH_TRIPPING;
+        }
+
+        String getBranchToOperateId();
+
+        BranchTripping setBranchToOperateId(String branch);
+
+        TwoSides getSideToOperate();
+
+        BranchTripping setSideToOperate(TwoSides side);
+    }
+
+    interface ThreeWindingsTransformerTripping extends Tripping {
+        @Override
+        default Type getType() {
+            return Type.THREE_WINDINGS_TRANSFORMER_TRIPPING;
+        }
+
+        String getThreeWindingsTransformerToOperateId();
+
+        ThreeWindingsTransformerTripping setThreeWindingsTransformerToOperateId(String threeWindingsTransformerId);
+
+        ThreeSides getSideToOperate();
+
+        ThreeWindingsTransformerTripping setSideToOperate(ThreeSides side);
+    }
+
+    /**
+     * Get the parent substation.
+     * @return the parent substation
+     */
+    Substation getSubstation();
+
+    /**
+     * Get the id of the element (branch or three windings transformer) which is monitored
+     * @return the id of the monitored element
+     */
+    String getMonitoredElementId();
+
+    /**
+     * Get the monitored side of the element.
+     * @return the side
+     * @see #getMonitoredElementId()
+     */
+    ThreeSides getMonitoredSide();
+
+    /**
+     * Add a tripping (operation to perform when the current is out of an acceptable interval)
+     * @param tripping the tripping to add
+     */
+    void addTripping(Tripping tripping);
+
+    /**
+     * Return the list of the defined trippings.
+     * @return the trippings
+     */
+    List<Tripping> getTrippings();
+
+    @Override
+    default IdentifiableType getType() {
+        return IdentifiableType.OVERLOAD_MANAGEMENT_SYSTEM;
+    }
+}

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/OverloadManagementSystemAdder.java

@@ -0,0 +1,100 @@
+/**
+ * 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.iidm.network;
+
+/**
+ * @author Olivier Perrin {@literal <olivier.perrin at rte-france.com>}
+ */
+public interface OverloadManagementSystemAdder extends IdentifiableAdder<OverloadManagementSystem, OverloadManagementSystemAdder> {
+
+    interface TrippingAdder<I extends TrippingAdder<I>> {
+        /**
+         * Set the unique key of the tripping.
+         * <p>This key is unique for a single overload management system, but it can be reused
+         * for another overload management system).</p>
+         * @param key the tripping key
+         */
+        I setKey(String key);
+
+        /**
+         * Set the name of the tripping.
+         * <p>This name is facultative. It is used only for reporting purposes.</p>
+         * @param name the name of the tripping
+         */
+        I setName(String name);
+
+        /**
+         * Set the maximum acceptable current value (in A).
+         * @param currentLimit the maximum current value
+         */
+        I setCurrentLimit(double currentLimit);
+
+        I setOpenAction(boolean open);
+
+        OverloadManagementSystem.Tripping.Type getType();
+
+        OverloadManagementSystemAdder add();
+    }
+
+    interface SwitchTrippingAdder extends TrippingAdder<SwitchTrippingAdder> {
+        @Override
+        default OverloadManagementSystem.Tripping.Type getType() {
+            return OverloadManagementSystem.Tripping.Type.SWITCH_TRIPPING;
+        }
+
+        SwitchTrippingAdder setSwitchToOperateId(String switchId);
+    }
+
+    interface BranchTrippingAdder extends TrippingAdder<BranchTrippingAdder> {
+        @Override
+        default OverloadManagementSystem.Tripping.Type getType() {
+            return OverloadManagementSystem.Tripping.Type.BRANCH_TRIPPING;
+        }
+
+        BranchTrippingAdder setBranchToOperateId(String branchId);
+
+        BranchTrippingAdder setSideToOperate(TwoSides side);
+    }
+
+    interface ThreeWindingsTransformerTrippingAdder extends TrippingAdder<ThreeWindingsTransformerTrippingAdder> {
+        @Override
+        default OverloadManagementSystem.Tripping.Type getType() {
+            return OverloadManagementSystem.Tripping.Type.THREE_WINDINGS_TRANSFORMER_TRIPPING;
+        }
+
+        ThreeWindingsTransformerTrippingAdder setThreeWindingsTransformerToOperateId(String threeWindingsTransformerId);
+
+        ThreeWindingsTransformerTrippingAdder setSideToOperate(ThreeSides side);
+
+    }
+
+    @Override
+    OverloadManagementSystem add();
+
+    OverloadManagementSystemAdder setEnabled(boolean enabled);
+
+    /**
+     * Set the id of the element (branch or three windings transformer) which is monitored.
+     * @param monitoredElementId the id of the monitored element
+     * @return the adder
+     */
+    OverloadManagementSystemAdder setMonitoredElementId(String monitoredElementId);
+
+    /**
+     * Set the monitored side of the element.
+     * @param monitoredElementSide the monitored side of the element
+     * @return the adder
+     */
+    OverloadManagementSystemAdder setMonitoredElementSide(ThreeSides monitoredElementSide);
+
+    SwitchTrippingAdder newSwitchTripping();
+
+    BranchTrippingAdder newBranchTripping();
+
+    ThreeWindingsTransformerTrippingAdder newThreeWindingsTransformerTripping();
+}

iidm/iidm-api/src/main/java/com/powsybl/iidm/network/Substation.java

@@ -162,6 +162,26 @@ public interface Substation extends Container<Substation> {
      */
     int getThreeWindingsTransformerCount();
 
+    /**
+     * Get a builder to create a new overload management system in the substation.
+     */
+    OverloadManagementSystemAdder newOverloadManagementSystem();
+
+    /**
+     * Get the overload management systems relative to the substation.
+     */
+    Iterable<OverloadManagementSystem> getOverloadManagementSystems();
+
+    /**
+     * Get the overload management systems relative to the substation.
+     */
+    Stream<OverloadManagementSystem> getOverloadManagementSystemStream();
+
+    /**
+     * Get the overload management systems count
+     */
+    int getOverloadManagementSystemCount();
+
     /**
      * Get geographical tags associated to the substation.
      */