epyt-flow 0.8.1__py3-none-any.whl → 0.10.0__py3-none-any.whl

epyt_flow/simulation/scada/scada_data_export.py

@@ -102,7 +102,7 @@ class ScadaDataExport():
 
         Returns
         -------
-        `numpy.ndarray`
+        `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_
             3-dimensional array describing all columns of the sensor readings:
             The first dimension describes the sensor type, the second dimension
             describes the sensor location, and the third one describes the measurement units.

epyt_flow/simulation/scada/simple_control.py

@@ -0,0 +1,317 @@
+"""
+The module contains classes for representing simple control rules as used in EPANET.
+"""
+from typing import Union
+from epyt.epanet import ToolkitConstants
+
+from ..events import ActuatorConstants
+from ...serialization import JsonSerializable, SIMPLE_CONTROL_ID, serializable
+
+
+@serializable(SIMPLE_CONTROL_ID, ".epytflow_simple_control")
+class SimpleControlModule(JsonSerializable):
+    """
+    A class for representing a simple EPANET control rule.
+
+    Parameters
+    ----------
+    link_id : `str`
+        Link ID.
+    link_status : `int` or `float`
+        Status of the link that is set when the condition is fullfilled.
+
+        Instance of `float` if the link constitutes a pump -- in this case,
+        the argument corresponds to the pump speed.
+
+        Instance of `int` if the link constitutes a valve -- in this case,
+        must be one of the followig costants defined in
+        :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+            - EN_CLOSED = 0
+            - EN_OPEN   = 1
+    cond_type : `int`
+        Condition/Rule type.
+
+        Must be one of the following EPANET constants:
+
+            - EN_LOWLEVEL  = 0
+            - EN_HILEVEL   = 1
+            - EN_TIMER     = 2
+            - EN_TIMEOFDAY = 3
+    cond_var_value : `str` or `int`
+        Condition/Rule variable value.
+
+        Node ID in the cases of EN_LOWLEVEL or EN_HILEVEL.
+        Time of the day (in AM/PM format) in the case of EN_TIMEOFDAY.
+        Number of hours (as an integer) since simulation start in the case of EN_TIMER.
+    cond_comp_value : `float`
+        The condition/rule comparison value at which this control rule is triggered.
+
+        Lower or upper value on the pressure (or tank level) in the cases of
+        EN_LOWLEVEL and EN_HILEVEL.
+
+        Will be ignored in all other cases -- i.e. should be set to None.
+    """
+    def __init__(self, link_id: str, link_status: Union[int, float], cond_type: int,
+                 cond_var_value: Union[str, int], cond_comp_value: float,
+                 **kwds):
+        if not isinstance(link_id, str):
+            raise TypeError(f"'link_id' must be an instance of 'str' but not of '{type(link_id)}'")
+        if isinstance(link_status, int):
+            if link_status not in [ActuatorConstants.EN_OPEN, ActuatorConstants.EN_CLOSED]:
+                raise ValueError(f"Invalid link status {link_status} in 'link_status'")
+        elif isinstance(link_status, float):
+            if link_status < 0:
+                raise TypeError("'link_status' can not be negative")
+        else:
+            raise TypeError("'link_status' must be an instance of 'int' or 'float' but not " +
+                            f"of '{type(link_status)}'")
+        if cond_type not in [ToolkitConstants.EN_TIMEOFDAY, ToolkitConstants.EN_TIMER,
+                             ToolkitConstants.EN_LOWLEVEL, ToolkitConstants.EN_HILEVEL]:
+            raise ValueError(f"Invalid control type '{cond_type}' in 'cond_type'")
+
+        if cond_type == ToolkitConstants.EN_TIMEOFDAY:
+            if not isinstance(cond_var_value, str):
+                raise TypeError("EN_TIMEOFDAY requires that 'cond_var_value' must be an instance " +
+                                f"of 'str' but not of '{type(cond_var_value)}'")
+            if not cond_var_value.endswith("AM") and not cond_var_value.endswith("PM"):
+                raise ValueError(f"Invalid time of day format '{cond_var_value}' in " +
+                                 "'cond_var_value'")
+        elif cond_type == ToolkitConstants.EN_TIMER:
+            if not isinstance(cond_var_value, int):
+                raise TypeError("EN_TIMER requires that 'cond_var_value' must be an instance " +
+                                f"of 'int' but not of '{type(cond_var_value)}'")
+            if cond_var_value < 0:
+                raise ValueError("'cond_var_value' can not be negative")
+        else:
+            if not isinstance(cond_var_value, str):
+                raise TypeError("'cond_var_value' must be an instance of 'str' but " +
+                                f"not of '{type(cond_var_value)}'")
+            if not isinstance(cond_comp_value, float):
+                raise TypeError("'cond_comp_value' must be an instance of 'float' " +
+                                f"but not of '{type(cond_comp_value)}'")
+            if cond_comp_value < 0:
+                raise ValueError("'cond_comp_value' can not be negative")
+
+        self.__link_id = link_id
+        self.__link_status = link_status
+        self.__cond_type = cond_type
+        self.__cond_var_value = cond_var_value
+        self.__cond_comp_value = cond_comp_value
+
+        super().__init__(**kwds)
+
+    @property
+    def link_id(self) -> str:
+        """
+        Returns the link ID.
+
+        Returns
+        -------
+        `str`
+            Link ID.
+        """
+        return self.__link_id
+
+    @property
+    def link_status(self) -> Union[int, float]:
+        """
+        Returns the link status that is set when the condition is fullfilled.
+
+        Returns
+        -------
+        `int` or `float`
+            Pump speed if the link is a pump, otherwise one of the followig costants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED = 0
+                - EN_OPEN   = 1
+        """
+        return self.__link_status
+
+    @property
+    def cond_type(self) -> int:
+        """
+        Returns the condition/rule type.
+
+        Returns
+        -------
+        `int`
+            Condition/Rule type -- will be one of the following EPANET constants:
+
+                - EN_LOWLEVEL  = 0
+                - EN_HILEVEL   = 1
+                - EN_TIMER     = 2
+                - EN_TIMEOFDAY = 3
+        """
+        return self.__cond_type
+
+    @property
+    def cond_var_value(self) -> Union[str, int]:
+        """
+        Return the condition/rule variable value.
+
+        Node ID in the cases of EN_LOWLEVEL or EN_HILEVEL.
+        Time of the day (in AM/PM format) in the case of EN_TIMEOFDAY.
+        Number of hours (as an integer) since simulation start in the case of EN_TIMER.
+
+        Returns
+        -------
+        `str` or `int`
+            Condition/rule variable value.
+        """
+        return self.__cond_var_value
+
+    @property
+    def cond_comp_value(self) -> float:
+        """
+        Returns the condition/rule comparison value -- might be None if not needed.
+
+        Lower or upper value on the pressure (or tank level) in the cases of
+        EN_LOWLEVEL and EN_HILEVEL.
+
+        Returns
+        -------
+        `float`
+            Condition/Rule comparison value.
+        """
+        return self.__cond_comp_value
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"link_id": self.__link_id,
+                                           "link_status": self.__link_status,
+                                           "cond_type": self.__cond_type,
+                                           "cond_var_value": self.__cond_var_value,
+                                           "cond_comp_value": self.__cond_comp_value}
+
+    def __eq__(self, other) -> bool:
+        return super().__eq__(other) and self.__link_id == other.link_id and \
+            self.__link_status == other.link_status and self.__cond_type == other.cond_type and \
+            self.__cond_var_value == other.cond_var_value and \
+            self.__cond_comp_value == other.cond_comp_value
+
+    def __str__(self) -> str:
+        control_rule_str = f"LINK {self.__link_id} "
+        if isinstance(self.__link_status, int):
+            control_rule_str += "OPEN " if self.__link_status == ActuatorConstants.EN_OPEN \
+                else "CLOSED "
+        else:
+            control_rule_str += f"{self.__link_status} "
+
+        if self.__cond_type == ToolkitConstants.EN_TIMER:
+            control_rule_str += f"AT TIME {self.__cond_var_value}"
+        elif self.__cond_type == ToolkitConstants.EN_TIMEOFDAY:
+            control_rule_str += f"AT CLOCKTIME {self.__cond_var_value}"
+        elif self.__cond_type == ToolkitConstants.EN_LOWLEVEL:
+            control_rule_str += f"IF NODE {self.__cond_var_value} BELOW {self.__cond_comp_value}"
+        elif self.__cond_type == ToolkitConstants.EN_HILEVEL:
+            control_rule_str += f"IF NODE {self.__cond_var_value} ABOVE {self.__cond_comp_value}"
+
+        return control_rule_str
+
+
+class SimplePumpSpeedTimeControl(SimpleControlModule):
+    """
+    A class for representing a simple control rule for setting the pump speed at some point in time.
+
+    Parameters
+    ----------
+    pump_id : `str`
+        Pump ID.
+    pump_speed : `float`
+        Pump speed.
+    time : `str` or `int`
+        Time of the day (in AM/PM format) in the case or
+        number of hours (as an integer) since simulation start.
+    """
+    def __init__(self, pump_id: str, pump_speed: float, time: Union[str, int]):
+        super().__init__(link_id=pump_id, link_status=pump_speed,
+                         cond_type=ToolkitConstants.EN_TIMER if isinstance(time, int)
+                         else ToolkitConstants.EN_TIMEOFDAY,
+                         cond_var_value=time, cond_comp_value=None)
+
+
+class SimplePumpSpeedConditionControl(SimpleControlModule):
+    """
+    A class for representing a simple IF-THEN control rule for setting the pump speed.
+
+    Parameters
+    ----------
+    Parameters
+    ----------
+    pump_id : `str`
+        Pump ID.
+    pump_speed : `float`
+        Pump speed.
+    node_id : `str`
+        Node ID.
+    comp_type : `int`
+        Comparison type -- must be one of the following EPANET constants:
+
+            - EN_LOWLEVEL  = 0
+            - EN_HILEVEL   = 1
+    comp_value : `float`:
+        Lower or upper value on the pressure (or tank level) at which this
+        control rule is triggered.
+    """
+    def __init__(self, pump_id: str, pump_speed: float, node_id: str, comp_type: int,
+                 comp_value: float):
+        super().__init__(link_id=pump_id, link_status=pump_speed, cond_type=comp_type,
+                         cond_var_value=node_id, cond_comp_value=comp_value)
+
+
+class SimpleValveTimeControl(SimpleControlModule):
+    """
+    A class for representing a simple control rule for setting the valve status
+    at some point in time.
+
+    Parameters
+    ----------
+    valve_id : `str`
+        valve ID.
+    valve_status : `int`
+        Valve status -- must be one of the followig costants defined in
+        :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+            - EN_CLOSED = 0
+            - EN_OPEN   = 1
+    time : `str` or `int`
+        Time of the day (in AM/PM format) in the case or
+        number of hours (as an integer) since simulation start.
+    """
+    def __init__(self, valve_id: str, valve_status: int, time: Union[str, int]):
+        super().__init__(link_id=valve_id, link_status=valve_status,
+                         cond_type=ToolkitConstants.EN_TIMER if isinstance(time, int)
+                         else ToolkitConstants.EN_TIMEOFDAY,
+                         cond_var_value=time, cond_comp_value=None)
+
+
+class SimpleValveConditionControl(SimpleControlModule):
+    """
+    A class for representing a simple IF-THEN control rule for setting the valve status.
+
+    Parameters
+    ----------
+    valve_id : `str`
+        valve ID.
+    valve_status : `int`
+        Valve status -- must be one of the followig costants defined in
+        :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+            - EN_CLOSED = 0
+            - EN_OPEN   = 1
+    node_id : `str`
+        Node ID.
+    comp_type : `int`
+        Comparison type -- must be one of the following EPANET constants:
+
+            - EN_LOWLEVEL  = 0
+            - EN_HILEVEL   = 1
+    comp_value : `float`:
+        Lower or upper value on the pressure (or tank level) at which this
+        control rule is triggered.
+    """
+    def __init__(self, valve_id: str, valve_status: int, node_id: str, comp_type: int,
+                 comp_value: float):
+        super().__init__(link_id=valve_id, link_status=valve_status, cond_type=comp_type,
+                         cond_var_value=node_id, cond_comp_value=comp_value)

epyt_flow/simulation/scenario_config.py

@@ -3,16 +3,17 @@ Module provides a class for specifying scenario configurations.
 """
 from typing import Any
 from copy import deepcopy
+import warnings
 import os
 import json
-import numpy as np
 from pathlib import Path
+import numpy as np
 
 from ..uncertainty import AbsoluteGaussianUncertainty, RelativeGaussianUncertainty, \
     AbsoluteUniformUncertainty, RelativeUniformUncertainty, ModelUncertainty, \
     SensorNoise, Uncertainty
 from .sensor_config import SensorConfig
-from .scada import AdvancedControlModule
+from .scada import CustomControlModule, SimpleControlModule, ComplexControlModule
 from .events import SystemEvent, SensorReadingEvent
 from .events.sensor_faults import SensorFaultConstant, SensorFaultDrift, SensorFaultGaussian, \
     SensorFaultPercentage, SensorFaultStuckZero
@@ -63,8 +64,16 @@ class ScenarioConfig(Serializable):
         Speciation of sensor noise -- i.e. noise/uncertainty affecting the sensor readings.
 
         The default is None
-    controls : list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`], optional
-        List of control modules that are active during the simulation.
+    csutom_controls : list[:class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`], optional
+        List of custom control modules that are active during the simulation.
+
+        The default is an empty list.
+    simple_controls : list[:class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`], optional
+        List of EPANET control rules that are active during the simulation.
+
+        The default is an empty list.
+    complex_controls : list[:class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`], optional
+        List of complex (i.e. IF-THEN-ELSE) EPANET control rules that are active during the simulation.
 
         The default is an empty list.
     model_uncertainty : :class:`~epyt_flow.uncertainty.model_uncertainty.ModelUncertainty`, optional
@@ -82,11 +91,22 @@ class ScenarioConfig(Serializable):
     def __init__(self, scenario_config: Any = None, f_inp_in: str = None, f_msx_in: str = None,
                  general_params: dict = None, sensor_config: SensorConfig = None,
                  memory_consumption_estimate: float = None,
-                 controls: list[AdvancedControlModule] = [],
+                 controls: list = None,
+                 advanced_controls: list = None,
+                 custom_controls: list[CustomControlModule] = [],
+                 simple_controls: list[SimpleControlModule] = [],
+                 complex_controls: list[ComplexControlModule] = [],
                  sensor_noise: SensorNoise = None,
                  model_uncertainty: ModelUncertainty = None,
                  system_events: list[SystemEvent] = [],
                  sensor_reading_events: list[SensorReadingEvent] = [], **kwds):
+        if controls is not None:
+            warnings.warn("'controls' is deprecated and will be removed in future releases")
+            advanced_controls = controls
+        if advanced_controls is not None:
+            warnings.warn("'advanced_controls' is deprecated and will be removed in " +
+                          "future releases -- use 'custom_controls' instead")
+
         if f_inp_in is None and scenario_config is None:
             raise ValueError("Either 'f_inp_in' or 'scenario_config' must be given")
         if scenario_config is not None:
@@ -115,14 +135,32 @@ class ScenarioConfig(Serializable):
             if not isinstance(memory_consumption_estimate, float) or \
                     memory_consumption_estimate <= 0:
                 raise ValueError("'memory_consumption_estimate' must be a positive integer")
-        if not isinstance(controls, list):
-            raise TypeError("'controls' must be an instance of " +
-                            "'list[epyt_flow.simulation.scada.AdvancedControlModule]' but no of " +
-                            f"'{type(controls)}'")
-        if len(controls) != 0:
-            if any(not isinstance(c, AdvancedControlModule) for c in controls):
-                raise TypeError("Each item in 'controls' must be an instance of " +
+        if advanced_controls is not None:
+            if not isinstance(advanced_controls, list):
+                raise TypeError("'advanced_controls' must be an instance of " +
+                                "'list[epyt_flow.simulation.scada.AdvancedControlModule]' but no of " +
+                                f"'{type(advanced_controls)}'")
+
+            from .scada.advanced_control import AdvancedControlModule
+            if any(not isinstance(c, AdvancedControlModule) for c in advanced_controls):
+                raise TypeError("Each item in 'advanced_controls' must be an instance of " +
                                 "'epyt_flow.simulation.scada.AdvancedControlModule'")
+        if len(custom_controls) != 0:
+            if any(not isinstance(c, CustomControlModule) for c in custom_controls):
+                raise TypeError("Each item in 'custom_controls' must be an instance of " +
+                                "'epyt_flow.simulation.scada.CustomControlModule'")
+        if not isinstance(simple_controls, list):
+            raise TypeError("'simple_controls' must be an instance of " +
+                            "'list[epyt_flow.simulation.scada.SimpleControlModule]' but no of " +
+                            f"'{type(simple_controls)}'")
+        if len(simple_controls) != 0:
+            if any(not isinstance(c, SimpleControlModule) for c in simple_controls):
+                raise TypeError("Each item in 'simple_controls' must be an instance of " +
+                                "'epyt_flow.simulation.scada.SimppleControlModule'")
+        if len(complex_controls) != 0:
+            if any(not isinstance(c, ComplexControlModule) for c in complex_controls):
+                raise TypeError("Each item in 'complex_controls' must be an instance of " +
+                                "'epyt_flow.simulation.scada.ComplexControlModule'")
         if sensor_noise is not None:
             if not isinstance(sensor_noise, SensorNoise):
                 raise TypeError("'sensor_noise' must be an instance of " +
@@ -169,10 +207,25 @@ class ScenarioConfig(Serializable):
             else:
                 self.__memory_consumption_estimate = memory_consumption_estimate
 
-            if len(controls) == 0:
-                self.__controls = scenario_config.controls
+            self.__advanced_controls = advanced_controls
+            if advanced_controls is not None:
+                if len(advanced_controls) == 0:
+                    self.__advanced_controls = scenario_config.advanced_controls
+
+            if len(custom_controls) == 0:
+                self.__custom_controls = scenario_config.custom_controls
             else:
-                self.__controls = controls
+                self.__custom_controls = custom_controls
+
+            if len(simple_controls) == 0:
+                self.__simple_controls = scenario_config.simple_controls
+            else:
+                self.__simple_controls = simple_controls
+
+            if len(complex_controls) == 0:
+                self.__complex_controls = scenario_config.complex_controls
+            else:
+                self.__complex_controls = complex_controls
 
             if sensor_noise is None:
                 self.__sensor_noise = scenario_config.sensor_noise
@@ -199,7 +252,10 @@ class ScenarioConfig(Serializable):
             self.__general_params = general_params
             self.__sensor_config = sensor_config
             self.__memory_consumption_estimate = memory_consumption_estimate
-            self.__controls = controls
+            self.__advanced_controls = advanced_controls
+            self.__custom_controls = custom_controls
+            self.__simple_controls = simple_controls
+            self.__complex_controls = complex_controls
             self.__sensor_noise = sensor_noise
             self.__system_events = system_events
             self.__sensor_reading_events = sensor_reading_events
@@ -286,16 +342,53 @@ class ScenarioConfig(Serializable):
         return self.__memory_consumption_estimate
 
     @property
-    def controls(self) -> list[AdvancedControlModule]:
+    def advanced_controls(self) -> list:
         """
-        Gets the list of all control modules that are active during the simulation.
+        Gets the list of all (advanced) control modules that are active during the simulation.
 
         Returns
         -------
         list[:class:`~epyt_flow.simulation.scada.advanced_control.AdvancedControlModule`]
             List of all control modules that are active during the simulation.
         """
-        return deepcopy(self.__controls)
+        return deepcopy(self.__advanced_controls)
+
+    @property
+    def custom_controls(self) -> list[CustomControlModule]:
+        """
+        Returns the list of all custom control modules that are active during the simulation.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.custom_control.CustomControlModule`]
+            List of all custom control modules that are active during the simulation.
+        """
+        return deepcopy(self.__custom_controls)
+
+    @property
+    def simple_controls(self) -> list[SimpleControlModule]:
+        """
+        Gets the list of all EPANET control rules that are active during the simulation.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.simple_control.SimpleControlModule`]
+            List of all EPANET control rules that are active during the simulation.
+        """
+        return deepcopy(self.__simple_controls)
+
+    @property
+    def complex_controls(self) -> list[ComplexControlModule]:
+        """
+        Gets the list of all complex (i.e. IF-THEN-ELSE) EPANET control rules
+        that are active during the simulation.
+
+        Returns
+        -------
+        list[:class:`~epyt_flow.simulation.scada.complex_control.ComplexControlModule`]
+            List of all complex EPANET control rules that are active during the simulation.
+        """
+        return deepcopy(self.__complex_controls)
 
     @property
     def sensor_noise(self) -> SensorNoise:
@@ -350,7 +443,9 @@ class ScenarioConfig(Serializable):
                          "general_params": self.__general_params,
                          "sensor_config": self.__sensor_config,
                          "memory_consumption_estimate": self.__memory_consumption_estimate,
-                         "controls": self.__controls,
+                         "custom_controls": self.__custom_controls,
+                         "simple_controls": self.__simple_controls,
+                         "complex_controls": self.__complex_controls,
                          "sensor_noise": self.__sensor_noise,
                          "model_uncertainty": self.__model_uncertainty,
                          "system_events": self.__system_events,
@@ -367,7 +462,10 @@ class ScenarioConfig(Serializable):
             and self.__general_params == other.general_params \
             and self.__memory_consumption_estimate == other.memory_consumption_estimate \
             and self.__sensor_config == other.sensor_config \
-            and np.all(self.__controls == other.controls) \
+            and np.all(self.__advanced_controls == other.advanced_controls) \
+            and np.all(self.__custom_controls == other.custom_controls) \
+            and np.all(self.__simple_controls == other.simple_controls) \
+            and np.all(self.__complex_controls == other.complex_controls) \
             and self.__model_uncertainty == other.model_uncertainty \
             and np.all(self.__system_events == other.system_events) \
             and np.all(self.__sensor_reading_events == other.sensor_reading_events)
@@ -376,8 +474,10 @@ class ScenarioConfig(Serializable):
         return f"f_inp_in: {self.f_inp_in} f_msx_in: {self.f_msx_in} " + \
             f"general_params: {self.general_params} sensor_config: {self.sensor_config} " + \
             f"memory_consumption_estimate: {self.memory_consumption_estimate} " + \
-            f"controls: {self.controls} sensor_noise: {self.sensor_noise} " + \
-            f"model_uncertainty: {self.model_uncertainty} " + \
+            f"advanced_controls: {self.advanced_controls} simple_controls: {self.simple_controls} " + \
+            f"complex_controls: {self.__complex_controls} " + \
+            f"custom_controls: {self.__custom_controls}" + \
+            f"sensor_noise: {self.sensor_noise} model_uncertainty: {self.model_uncertainty} " + \
             f"system_events: {','.join(map(str, self.system_events))} " + \
             f"sensor_reading_events: {','.join(map(str, self.sensor_reading_events))}"
 
@@ -614,6 +714,6 @@ class ScenarioConfig(Serializable):
 
         # Create final scenario configuration
         return ScenarioConfig(f_inp_in=f_inp_in, f_msx_in=f_msx_in, general_params=general_params,
-                              sensor_config=sensor_config, controls=[], sensor_noise=sensor_noise,
+                              sensor_config=sensor_config, sensor_noise=sensor_noise,
                               model_uncertainty=model_uncertainty, system_events=leakages,
                               sensor_reading_events=sensor_faults)