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

epyt_flow/simulation/scenario_config.py

@@ -3,6 +3,7 @@ Module provides a class for specifying scenario configurations.
 """
 from typing import Any
 from copy import deepcopy
+import warnings
 import os
 import json
 from pathlib import Path
@@ -12,7 +13,7 @@ from ..uncertainty import AbsoluteGaussianUncertainty, RelativeGaussianUncertain
     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.__custom_controls = custom_controls
+
+            if len(simple_controls) == 0:
+                self.__simple_controls = scenario_config.simple_controls
             else:
-                self.__controls = controls
+                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)