deprecating connected_component_mode for component_mode

Signed-off-by: Hugo KULESZA <hugo.kulesza@rte-france.com>

cpp/powsybl-cpp/powsybl-cpp.cpp

@@ -330,7 +330,7 @@ LoadFlowParameters::LoadFlowParameters(loadflow_parameters* src) {
     distributed_slack = (bool) src->distributed_slack;
     balance_type = static_cast<BalanceType>(src->balance_type);
     dc_use_transformer_ratio = (bool) src->dc_use_transformer_ratio;
-    connected_component_mode = static_cast<ConnectedComponentMode>(src->connected_component_mode);
+    component_mode = static_cast<ComponentMode>(src->component_mode);
     hvdc_ac_emulation = (bool) src->hvdc_ac_emulation;
     dc_power_factor = (double) src->dc_power_factor;
     copyCharPtrPtrToVector(src->countries_to_balance, src->countries_to_balance_count, countries_to_balance);
@@ -351,7 +351,7 @@ void LoadFlowParameters::load_to_c_struct(loadflow_parameters& res) const {
     res.dc_use_transformer_ratio = (unsigned char) dc_use_transformer_ratio;
     res.countries_to_balance = pypowsybl::copyVectorStringToCharPtrPtr(countries_to_balance);
     res.countries_to_balance_count = countries_to_balance.size();
-    res.connected_component_mode = connected_component_mode;
+    res.component_mode = component_mode;
     res.hvdc_ac_emulation = (unsigned char) hvdc_ac_emulation;
     res.dc_power_factor = dc_power_factor;
     providerParametersToCStruct(res.provider_parameters, provider_parameters_keys, provider_parameters_values);

cpp/powsybl-cpp/powsybl-cpp.h

@@ -317,7 +317,7 @@ class LoadFlowParameters {
     BalanceType balance_type;
     bool dc_use_transformer_ratio;
     std::vector<std::string> countries_to_balance;
-    ConnectedComponentMode connected_component_mode;
+    ComponentMode component_mode;
     bool hvdc_ac_emulation;
     double dc_power_factor;
     std::vector<std::string> provider_parameters_keys;

cpp/pypowsybl-cpp/bindings.cpp

@@ -573,7 +573,7 @@ PYBIND11_MODULE(_pypowsybl, m) {
             .def_readwrite("balance_type", &pypowsybl::LoadFlowParameters::balance_type)
             .def_readwrite("dc_use_transformer_ratio", &pypowsybl::LoadFlowParameters::dc_use_transformer_ratio)
             .def_readwrite("countries_to_balance", &pypowsybl::LoadFlowParameters::countries_to_balance)
-            .def_readwrite("connected_component_mode", &pypowsybl::LoadFlowParameters::connected_component_mode)
+            .def_readwrite("component_mode", &pypowsybl::LoadFlowParameters::component_mode)
             .def_readwrite("hvdc_ac_emulation", &pypowsybl::LoadFlowParameters::hvdc_ac_emulation)
             .def_readwrite("dc_power_factor", &pypowsybl::LoadFlowParameters::dc_power_factor)
             .def_readwrite("provider_parameters_keys", &pypowsybl::LoadFlowParameters::provider_parameters_keys)

cpp/pypowsybl-java/powsybl-api.h

@@ -69,7 +69,7 @@ typedef struct loadflow_parameters_struct {
     unsigned char dc_use_transformer_ratio;
     char** countries_to_balance;
     int countries_to_balance_count;
-    int connected_component_mode;
+    int component_mode;
     unsigned char hvdc_ac_emulation;
     double dc_power_factor;
 } loadflow_parameters;

docs/reference/loadflow.rst

@@ -47,6 +47,7 @@ Some enum classes are used in parameters:
    :template: autosummary/class_without_members.rst
 
     VoltageInitMode
+    ComponentMode
     ConnectedComponentMode
     BalanceType
 

docs/user_guide/loadflow.rst

@@ -48,7 +48,7 @@ Let's have a look at the default ones:
 .. doctest::
 
     >>> lf.Parameters()
-    Parameters(voltage_init_mode=UNIFORM_VALUES, transformer_voltage_control_on=False, use_reactive_limits=True, phase_shifter_regulation_on=False, twt_split_shunt_admittance=False, shunt_compensator_voltage_control_on=False, read_slack_bus=True, write_slack_bus=True, distributed_slack=True, balance_type=PROPORTIONAL_TO_GENERATION_P_MAX, dc_use_transformer_ratio=True, countries_to_balance=[], connected_component_mode=<ConnectedComponentMode.MAIN: 0>, hvdc_ac_emulation=True, dc_power_factor=1.0, provider_parameters={})
+    Parameters(voltage_init_mode=UNIFORM_VALUES, transformer_voltage_control_on=False, use_reactive_limits=True, phase_shifter_regulation_on=False, twt_split_shunt_admittance=False, shunt_compensator_voltage_control_on=False, read_slack_bus=True, write_slack_bus=True, distributed_slack=True, balance_type=PROPORTIONAL_TO_GENERATION_P_MAX, dc_use_transformer_ratio=True, countries_to_balance=[], component_mode=<ComponentMode.MAIN_CONNECTED: 0>, hvdc_ac_emulation=True, dc_power_factor=1.0, provider_parameters={})
 
 For more details on each parameter, please refer to the :doc:`API reference </reference/loadflow/parameters>`.
 

java/pypowsybl/src/main/java/com/powsybl/python/commons/PyPowsyblApiHeader.java

@@ -308,11 +308,11 @@ public interface LoadFlowParametersPointer extends PointerBase {
         @CField("countries_to_balance_count")
         void setCountriesToBalanceCount(int countriesToBalanceCount);
 
-        @CField("connected_component_mode")
-        int getConnectedComponentMode();
+        @CField("component_mode")
+        int getComponentMode();
 
-        @CField("connected_component_mode")
-        void setConnectedComponentMode(int connectedComponentMode);
+        @CField("component_mode")
+        void setComponentMode(int componentMode);
 
         @CField("hvdc_ac_emulation")
         boolean isHvdcAcEmulation();

java/pypowsybl/src/main/java/com/powsybl/python/loadflow/LoadFlowCFunctions.java

@@ -303,7 +303,7 @@ public static void copyToCLoadFlowParameters(LoadFlowParameters parameters, Load
         }
         cParameters.setCountriesToBalance(calloc);
         cParameters.setCountriesToBalanceCount(countries.size());
-        cParameters.setConnectedComponentMode(parameters.getConnectedComponentMode().ordinal());
+        cParameters.setComponentMode(parameters.getComponentMode().ordinal());
         cParameters.setHvdcAcEmulation(parameters.isHvdcAcEmulation());
         cParameters.setDcPowerFactor(parameters.getDcPowerFactor());
         if (loadFlowProvider != null) {

java/pypowsybl/src/main/java/com/powsybl/python/loadflow/LoadFlowCUtils.java

@@ -66,7 +66,7 @@ public static LoadFlowParameters convertLoadFlowParameters(boolean dc,
                 .setDcUseTransformerRatio(loadFlowParametersPtr.isDcUseTransformerRatio())
                 .setCountriesToBalance(CTypeUtil.toStringList(loadFlowParametersPtr.getCountriesToBalance(), loadFlowParametersPtr.getCountriesToBalanceCount())
                         .stream().map(Country::valueOf).collect(Collectors.toSet()))
-                .setConnectedComponentMode(LoadFlowParameters.ConnectedComponentMode.values()[loadFlowParametersPtr.getConnectedComponentMode()])
+                .setComponentMode(LoadFlowParameters.ComponentMode.values()[loadFlowParametersPtr.getComponentMode()])
                 .setHvdcAcEmulation(loadFlowParametersPtr.isHvdcAcEmulation())
                 .setDcPowerFactor(loadFlowParametersPtr.getDcPowerFactor());
     }

pypowsybl/_pypowsybl.pyi

@@ -39,6 +39,22 @@ class ConnectedComponentMode:
     @property
     def name(self) -> str: ...
 
+class ComponentMode:
+    __members__: ClassVar[Dict[str, ComponentMode]] = ...  # read-only
+    ALL_CONNECTED: ClassVar[ComponentMode] = ...
+    MAIN_CONNECTED: ClassVar[ComponentMode] = ...
+    MAIN_SYCNHRONOUS: ClassVar[ComponentMode] = ...
+    def __init__(self, arg0: int) -> None: ...
+    def __eq__(self, arg0: object) -> bool: ...
+    def __getstate__(self) -> int: ...
+    def __hash__(self) -> int: ...
+    def __index__(self) -> int: ...
+    def __int__(self) -> int: ...
+    def __ne__(self, arg0: object) -> bool: ...
+    def __setstate__(self, arg0: int) -> None: ...
+    @property
+    def name(self) -> str: ...
+
 class ContingencyContextType:
     __members__: ClassVar[Dict[str, ContingencyContextType]] = ...  # read-only
     ALL: ClassVar[ContingencyContextType] = ...
@@ -476,7 +492,7 @@ class LoadFlowParameters:
     balance_type: BalanceType
     dc_use_transformer_ratio: bool
     countries_to_balance: Sequence[str]
-    connected_component_mode: ConnectedComponentMode
+    component_mode: ComponentMode
     dc_power_factor: float
     hvdc_ac_emulation: bool
     provider_parameters_keys: List[str]

pypowsybl/loadflow/__init__.py

@@ -10,6 +10,7 @@
     run_ac_async,
     run_dc,
     ConnectedComponentMode,
+    ComponentMode,
     BalanceType,
     VoltageInitMode,
     get_provider_parameters_names,

pypowsybl/loadflow/impl/loadflow.py

@@ -12,6 +12,7 @@
 from pypowsybl import _pypowsybl
 from pypowsybl._pypowsybl import (
     ConnectedComponentMode,
+    ComponentMode,
     BalanceType,
     VoltageInitMode,
     LoadFlowValidationParameters,
@@ -32,6 +33,7 @@
 VoltageInitMode.__module__ = __name__
 BalanceType.__module__ = __name__
 ConnectedComponentMode.__module__ = __name__
+ComponentMode.__module__ = __name__
 
 
 def run_ac(network: Network, parameters: Optional[Parameters] = None, provider: str = '', reporter: Optional[ReportNode] = None,

pypowsybl/loadflow/impl/parameters.py

@@ -4,8 +4,12 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # SPDX-License-Identifier: MPL-2.0
 #
+import warnings
 from typing import Sequence, Dict, Optional, Any
+
+from pandapower.topology import connected_component
 from pypowsybl._pypowsybl import (
+    ComponentMode,
     ConnectedComponentMode,
     BalanceType,
     VoltageInitMode,
@@ -18,8 +22,10 @@
 VoltageInitMode.__module__ = __name__
 BalanceType.__module__ = __name__
 ConnectedComponentMode.__module__ = __name__
+ComponentMode.__module__ = __name__
 
 import pypowsybl._pypowsybl
+from pypowsybl.loadflow.impl.util import _convert_to_component_mode, _convert_to_connected_component_mode
 
 
 class Parameters:  # pylint: disable=too-few-public-methods
@@ -55,16 +61,19 @@ class Parameters:  # pylint: disable=too-few-public-methods
             Will tag the slack bus selected by your loadflow provider with an extension.
         distributed_slack: Distribute active power slack on the network.
             ``True`` means that the active power slack is distributed, on loads or on generators according to ``balance_type``.
-        balance_type: How to distributed active power slack.
+        balance_type: How to distribute active power slack.
             Use ``PROPORTIONAL_TO_LOAD`` to distribute slack on loads,
             ``PROPORTIONAL_TO_GENERATION_P_MAX`` or ``PROPORTIONAL_TO_GENERATION_P`` to distribute on generators.
         dc_use_transformer_ratio: In DC mode, take into account transformer ratio.
             Used only for DC load flows, to include ratios in the equation system.
         countries_to_balance: List of countries participating to slack distribution.
             Used only if distributed_slack is ``True``.
-        connected_component_mode: Define which connected components should be computed.
-            Use ``MAIN`` to computes flows only on the main connected component,
-            or prefer ``ALL`` for a run on all connected component.
+        component_mode: Defines which network components should be computed.
+            Use ``MAIN_SYNCHRONOUS`` to computes flows only on the main synchronous component,
+            ``MAIN_CONNECTED`` to computes flows only on the main connected component,
+            or prefer ``ALL_CONNECTED`` for a run on all connected components.
+        connected_component_mode: Deprecated, use parameter ``component_mode`` (``MAIN`` corresponds to component_mode = ``MAIN_CONNECTED``,
+            ``ALL`` to component_mode = ``ALL_CONNECTED``).
         hvdc_ac_emulation: Enable AC emulation of HVDC links.
         dc_power_factor: Power factor used to convert current limits into active power limits in DC calculations.
         provider_parameters: Define parameters linked to the loadflow provider
@@ -83,6 +92,7 @@ def __init__(self, voltage_init_mode: Optional[VoltageInitMode] = None,
                  balance_type: Optional[BalanceType] = None,
                  dc_use_transformer_ratio: Optional[bool] = None,
                  countries_to_balance: Optional[Sequence[str]] = None,
+                 component_mode: Optional[ComponentMode] = None,
                  connected_component_mode: Optional[ConnectedComponentMode] = None,
                  dc_power_factor: Optional[float] = None,
                  hvdc_ac_emulation: Optional[bool] = None,
@@ -112,8 +122,11 @@ def __init__(self, voltage_init_mode: Optional[VoltageInitMode] = None,
             self.dc_use_transformer_ratio = dc_use_transformer_ratio
         if countries_to_balance is not None:
             self.countries_to_balance = countries_to_balance
+        if component_mode is not None:
+            self.component_mode = component_mode
         if connected_component_mode is not None:
-            self.connected_component_mode = connected_component_mode
+            warnings.deprecated("connected_component_mode is deprecated, use component_mode parameter instead")
+            self.component_mode = _convert_to_component_mode(connected_component_mode)
         if hvdc_ac_emulation is not None:
             self.hvdc_ac_emulation = hvdc_ac_emulation
         if dc_power_factor is not None:
@@ -134,7 +147,7 @@ def _init_from_c(self, c_parameters: LoadFlowParameters) -> None:
         self.balance_type = c_parameters.balance_type
         self.dc_use_transformer_ratio = c_parameters.dc_use_transformer_ratio
         self.countries_to_balance = c_parameters.countries_to_balance
-        self.connected_component_mode = c_parameters.connected_component_mode
+        self.component_mode = c_parameters.component_mode
         self.hvdc_ac_emulation = c_parameters.hvdc_ac_emulation
         self.dc_power_factor = c_parameters.dc_power_factor
         self.provider_parameters = dict(
@@ -157,13 +170,23 @@ def _to_c_parameters(self) -> LoadFlowParameters:
         c_parameters.balance_type = self.balance_type
         c_parameters.dc_use_transformer_ratio = self.dc_use_transformer_ratio
         c_parameters.countries_to_balance = self.countries_to_balance
-        c_parameters.connected_component_mode = self.connected_component_mode
+        c_parameters.component_mode = self.component_mode
         c_parameters.hvdc_ac_emulation = self.hvdc_ac_emulation
         c_parameters.dc_power_factor = self.dc_power_factor
         c_parameters.provider_parameters_keys = list(self.provider_parameters.keys())
         c_parameters.provider_parameters_values = list(self.provider_parameters.values())
         return c_parameters
 
+    @property
+    def connected_component_mode(self) -> Optional[ConnectedComponentMode]:
+        warnings.deprecated("connected_component_mode is deprecated, use component_mode parameter instead")
+        return _convert_to_connected_component_mode(self.component_mode)
+
+    @connected_component_mode.setter
+    def connected_component_mode(self, connected_component_mode: ConnectedComponentMode) -> None:
+        warnings.deprecated("connected_component_mode is deprecated, use component_mode parameter instead")
+        self.component_mode = _convert_to_component_mode(connected_component_mode)
+
     @staticmethod
     def from_json(json_str: str) -> "Parameters":
         parameters = Parameters()
@@ -193,7 +216,7 @@ def __repr__(self) -> str:
                f", balance_type={self.balance_type.name}" \
                f", dc_use_transformer_ratio={self.dc_use_transformer_ratio!r}" \
                f", countries_to_balance={self.countries_to_balance}" \
-               f", connected_component_mode={self.connected_component_mode!r}" \
+               f", component_mode={self.component_mode!r}" \
                f", hvdc_ac_emulation={self.hvdc_ac_emulation!r}" \
                f", dc_power_factor={self.dc_power_factor!r}" \
                f", provider_parameters={self.provider_parameters!r}" \

pypowsybl/loadflow/impl/util.py

@@ -4,7 +4,11 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 # SPDX-License-Identifier: MPL-2.0
 #
+from typing import Optional
+
 from pypowsybl import _pypowsybl
+from pypowsybl._pypowsybl import ConnectedComponentMode, ComponentMode
+
 from .parameters import Parameters
 
 
@@ -15,3 +19,17 @@ def parameters_from_c(c_parameters: _pypowsybl.LoadFlowParameters) -> Parameters
     res = Parameters.__new__(Parameters)
     res._init_from_c(c_parameters) # pylint: disable=protected-access
     return res
+
+def _convert_to_component_mode(connected_component_mode: ConnectedComponentMode) -> ComponentMode:
+    if connected_component_mode == ConnectedComponentMode.MAIN:
+        return ComponentMode.MAIN_CONNECTED
+    else:
+        return ComponentMode.ALL_CONNECTED
+
+def _convert_to_connected_component_mode(component_mode: ComponentMode) -> Optional[ConnectedComponentMode]:
+    if component_mode == ComponentMode.MAIN_CONNECTED:
+        return ConnectedComponentMode.MAIN
+    elif component_mode == ComponentMode.ALL_CONNECTED:
+        return ConnectedComponentMode.ALL
+    else:
+        return None

tests/test_flow_decomposition.py

@@ -27,7 +27,7 @@ def define_test_load_flow_parameters():
         balance_type=pp.loadflow.BalanceType.PROPORTIONAL_TO_GENERATION_P_MAX,
         dc_use_transformer_ratio=True,
         countries_to_balance=[],
-        connected_component_mode=pp.loadflow.ConnectedComponentMode.MAIN,
+        component_mode=pp.loadflow.ComponentMode.MAIN_CONNECTED,
         provider_parameters={}
         )
 

tests/test_loadflow.py

@@ -11,7 +11,7 @@
 import tempfile
 
 import pytest
-from pypowsybl._pypowsybl import LoadFlowComponentStatus
+from pypowsybl._pypowsybl import LoadFlowComponentStatus, ConnectedComponentMode
 
 import pypowsybl as pp
 import pypowsybl.loadflow as lf
@@ -80,7 +80,7 @@ def test_lf_parameters():
     parameters = lf.Parameters()
     assert parameters.dc_use_transformer_ratio
     assert 0 == len(parameters.countries_to_balance)
-    assert lf.ConnectedComponentMode.MAIN == parameters.connected_component_mode
+    assert (lf.ComponentMode.MAIN_CONNECTED == parameters.component_mode)
 
     # Testing setting independently every attributes
     attributes = {
@@ -96,7 +96,7 @@ def test_lf_parameters():
         'balance_type': [lf.BalanceType.PROPORTIONAL_TO_CONFORM_LOAD, lf.BalanceType.PROPORTIONAL_TO_GENERATION_P],
         'dc_use_transformer_ratio': [True, False],
         'countries_to_balance': [['FR'], ['BE']],
-        'connected_component_mode': [lf.ConnectedComponentMode.MAIN, lf.ConnectedComponentMode.ALL],
+        'component_mode': [lf.ComponentMode.MAIN_CONNECTED, lf.ComponentMode.ALL_CONNECTED, lf.ComponentMode.MAIN_SYCNHRONOUS],
         'dc_power_factor': [1.0, 0.95]
     }
 
@@ -109,6 +109,15 @@ def test_lf_parameters():
             setattr(parameters, attribute, value)
             assert value == getattr(parameters, attribute)
 
+def test_deprecated_connected_component_mode_parameter():
+    with pytest.warns(DeprecationWarning, match=re.escape("connected_component_mode is deprecated, use component_mode parameter instead")):
+        parameters = lf.Parameters(connected_component_mode=lf.ConnectedComponentMode.ALL)
+    assert parameters.component_mode == lf.ComponentMode.ALL_CONNECTED
+
+    parameters2 = lf.Parameters()
+    with pytest.warns(DeprecationWarning, match=re.escape("connected_component_mode is deprecated, use component_mode parameter instead")):
+        parameters2.connected_component_mode = lf.ConnectedComponentMode.ALL
+    assert parameters.component_mode == lf.ComponentMode.ALL_CONNECTED
 
 def test_validation():
     n = pp.network.create_ieee14()