epyt-flow 0.5.0__tar.gz → 0.6.0__tar.gz

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: epyt-flow
-Version: 0.5.0
+Version: 0.6.0
 Summary: EPyT-Flow -- EPANET Python Toolkit - Flow
 Author-email: André Artelt <aartelt@techfak.uni-bielefeld.de>, "Marios S. Kyriakou" <kiriakou.marios@ucy.ac.cy>, "Stelios G. Vrachimis" <vrachimis.stelios@ucy.ac.cy>
 License: MIT License
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: epyt>=1.1.6
+Requires-Dist: epyt>=1.1.9
 Requires-Dist: requests>=2.31.0
 Requires-Dist: scipy>=1.11.4
 Requires-Dist: u-msgpack-python>=2.8.0

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/REQUIREMENTS.txt

@@ -1,4 +1,4 @@
-epyt>=1.1.6
+epyt>=1.1.9
 requests>=2.31.0
 scipy>=1.11.4
 u-msgpack-python>=2.8.0

epyt_flow-0.6.0/epyt_flow/VERSION

@@ -0,0 +1 @@
+0.6.0

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/epyt_flow/data/benchmarks/battledim.py

@@ -458,10 +458,14 @@ def load_scenario(return_test_scenario: bool, download_dir: str = None,
         ltown_config = load_ltown(use_realistic_demands=True, include_default_sensor_placement=True,
                                   verbose=verbose)
 
-    # Set simulation duration
+    # Set simulation duration and other general parameters such as the demand model
     general_params = {"simulation_duration": to_seconds(days=365),    # One year
                       "hydraulic_time_step": to_seconds(minutes=5),   # 5min time steps
-                      "reporting_time_step": to_seconds(minutes=5)} | ltown_config.general_params
+                      "reporting_time_step": to_seconds(minutes=5),
+                      "demand_model": {"type": "PDA", "pressure_min": 0,
+                                       "pressure_required": 0.1,
+                                       "pressure_exponent": 0.5}
+                      } | ltown_config.general_params
 
     # Add events
     start_time = START_TIME_TEST if return_test_scenario is True else START_TIME_TRAIN

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/epyt_flow/data/benchmarks/leakdb.py

@@ -30,7 +30,7 @@ from .leakdb_data import NET1_LEAKAGES, HANOI_LEAKAGES
 from ...utils import get_temp_folder, to_seconds, unpack_zip_archive, create_path_if_not_exist, \
     download_if_necessary
 from ...metrics import f1_score, true_positive_rate, true_negative_rate
-from ...simulation import ScenarioSimulator
+from ...simulation import ScenarioSimulator, ToolkitConstants
 from ...simulation.events import AbruptLeakage, IncipientLeakage
 from ...simulation import ScenarioConfig
 from ...simulation.scada import ScadaData
@@ -424,14 +424,19 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
     download_dir = download_dir if download_dir is not None else get_temp_folder()
     network_config = load_network(download_dir)
 
-    # Set simulation duration
+    # Set simulation duration and other general parameters such as the demand model and flow units
     hydraulic_time_step = to_seconds(minutes=30)    # 30min time steps
     general_params = {"simulation_duration": to_seconds(days=365),   # One year
                       "hydraulic_time_step": hydraulic_time_step,
-                      "reporting_time_step": hydraulic_time_step} | network_config.general_params
+                      "reporting_time_step": hydraulic_time_step,
+                      "flow_units_id": ToolkitConstants.EN_CMH,
+                      "demand_model": {"type": "PDA", "pressure_min": 0,
+                                       "pressure_required": 0.1,
+                                       "pressure_exponent": 0.5}
+                      } | network_config.general_params
 
     # Add demand patterns
-    def gen_dem(download_dir, use_net1):
+    def gen_dem(download_dir):
         # Taken from https://github.com/KIOS-Research/LeakDB/blob/master/CCWI-WDSA2018/Dataset_Generator_Py3/demandGenerator.py
         week_pat = scipy.io.loadmat(os.path.join(download_dir, "weekPat_30min.mat"))
         a_w = week_pat['Aw']
@@ -503,10 +508,7 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
 
         if not os.path.exists(f_inp_in):
             with ScenarioSimulator(f_inp_in=network_config.f_inp_in) as wdn:
-                wdn.epanet_api.setTimeHydraulicStep(general_params["hydraulic_time_step"])
-                wdn.epanet_api.setTimeSimulationDuration(general_params["simulation_duration"])
-                wdn.epanet_api.setTimePatternStep(general_params["hydraulic_time_step"])
-                wdn.epanet_api.setFlowUnitsCMH()
+                wdn.set_general_parameters(**general_params)
 
                 wdn.epanet_api.deletePatternsAll()
 
@@ -519,7 +521,7 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
                     node_idx = wdn.epanet_api.getNodeIndex(node_id)
                     base_demand = wdn.epanet_api.getNodeBaseDemands(node_idx)[1][0]
 
-                    my_demand_pattern = np.array(gen_dem(download_dir, use_net1))
+                    my_demand_pattern = np.array(gen_dem(download_dir))
 
                     wdn.set_node_demand_pattern(node_id=node_id, base_demand=base_demand,
                                                 demand_pattern_id=f"demand_{node_id}",

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/epyt_flow/data/networks.py

@@ -56,8 +56,7 @@ def get_default_hydraulic_options(flow_units_id: int = None) -> dict:
         Dictionary with default hydraulics options that can be passed to
         :func:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator.set_general_parameters`.
     """
-    params = {"demand_model": {"type": "PDA", "pressure_min": 0, "pressure_required": 0.1,
-                               "pressure_exponent": 0.5}}
+    params = {}
     if flow_units_id is not None:
         params |= {"flow_units_id": flow_units_id}
 

epyt_flow-0.6.0/epyt_flow/gym/scenario_control_env.py

@@ -0,0 +1,196 @@
+"""
+Module provides a base class for control environments.
+"""
+from abc import abstractmethod, ABC
+from typing import Union
+import warnings
+import numpy as np
+
+from ..simulation import ScenarioSimulator, ScenarioConfig, ScadaData
+
+
+class ScenarioControlEnv(ABC):
+    """
+    Base class for a control environment challenge.
+
+    Parameters
+    ----------
+    scenario_config : :class:`~epyt_flow.simulation.scenario_config.ScenarioConfig`
+        Scenario configuration.
+    autoreset : `bool`, optional
+        If True, environment is automatically reset if terminated.
+
+        The default is False.
+    """
+    def __init__(self, scenario_config: ScenarioConfig, autoreset: bool = False, **kwds):
+        self.__scenario_config = scenario_config
+        self._scenario_sim = None
+        self._sim_generator = None
+        self.__autoreset = autoreset
+
+        super().__init__(**kwds)
+
+    @property
+    def autoreset(self) -> bool:
+        """
+        True, if environment automatically resets after it terminated.
+
+        Returns
+        -------
+        `bool`
+            True, if environment automatically resets after it terminated.
+        """
+        return self.__autoreset
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self) -> None:
+        """
+        Frees all resources.
+        """
+        try:
+            if self._sim_generator is not None:
+                self._sim_generator.send(True)
+                next(self._sim_generator)
+        except StopIteration:
+            pass
+
+        if self._scenario_sim is not None:
+            self._scenario_sim.close()
+
+    def reset(self) -> ScadaData:
+        """
+        Resets the environment (i.e. simulation).
+
+        Returns
+        -------
+        :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            Current SCADA data (i.e. sensor readings).
+        """
+        if self._scenario_sim is not None:
+            self._scenario_sim.close()
+
+        self._scenario_sim = ScenarioSimulator(
+            scenario_config=self.__scenario_config)
+        self._sim_generator = self._scenario_sim.run_simulation_as_generator(support_abort=True)
+
+        return self._next_sim_itr()
+
+    def _next_sim_itr(self) -> ScadaData:
+        try:
+            next(self._sim_generator)
+            r = self._sim_generator.send(False)
+
+            if self.autoreset is True:
+                return r
+            else:
+                return r, False
+        except StopIteration:
+            if self.__autoreset is True:
+                return self.reset()
+            else:
+                return None, True
+
+    def set_pump_status(self, pump_id: str, status: int) -> None:
+        """
+        Sets the status of a pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump for which the status is set.
+        status : `int`
+            New status of the pump -- either active (i.e. open) or inactive (i.e. closed).
+
+            Must be one of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED  = 0
+                - EN_OPEN    = 1
+        """
+        pump_idx = self._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
+        pump_link_idx = self._scenario_sim.epanet_api.getLinkPumpIndex(pump_idx + 1)
+        self._scenario_sim.epanet_api.setLinkStatus(pump_link_idx, status)
+
+    def set_pump_speed(self, pump_id: str, speed: float) -> None:
+        """
+        Sets the speed of a pump.
+
+        Parameters
+        ----------
+        pump_id : `str`
+            ID of the pump for which the pump speed is set.
+        speed : `float`
+            New pump speed.
+        """
+        pump_idx = self._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
+        pattern_idx = self._scenario_sim.epanet_api.getLinkPumpPatternIndex(pump_idx + 1)
+
+        if pattern_idx == 0:
+            warnings.warn(f"No pattern for pump '{pump_id}' found -- a new pattern is created")
+            pattern_idx = self._scenario_sim.epanet_api.addPattern(f"pump_speed_{pump_id}")
+            self._scenario_sim.epanet_api.setLinkPumpPatternIndex(pattern_idx)
+
+        self._scenario_sim.epanet_api.setPattern(pattern_idx, np.array([speed]))
+
+    def set_valve_status(self, valve_id: str, status: int) -> None:
+        """
+        Sets the status of a valve.
+
+        Parameters
+        ----------
+        valve_id : `str`
+            ID of the valve for which the status is set.
+        status : `int`
+            New status of the valve -- either open or closed.
+
+            Must be one of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED  = 0
+                - EN_OPEN    = 1
+        """
+        valve_idx = self._scenario_sim.epanet_api.getLinkValveNameID().index(valve_id)
+        valve_link_idx = self._scenario_sim.epanet_api.getLinkValveIndex()[valve_idx]
+        self._scenario_sim.epanet_api.setLinkStatus(valve_link_idx, status)
+
+    def set_node_quality_source_value(self, node_id: str, pattern_id: str,
+                                      qual_value: float) -> None:
+        """
+        Sets the quality source at a particular node to a specific value -- e.g.
+        setting the chlorine concentration injection to a specified value.
+
+        Parameters
+        ----------
+        node_id : `str`
+            ID of the node.
+        pattern_id : `str`
+            ID of the quality pattern at the specific node.
+        qual_value : `float`
+            New quality source value.
+        """
+        node_idx = self._scenario_sim.epanet_api.getNodeIndex(node_id)
+        pattern_idx = self._scenario_sim.epanet_api.getPatternIndex(pattern_id)
+        self._scenario_sim.epanet_api.setNodeSourceQuality(node_idx, 1)
+        self._scenario_sim.epanet_api.setPattern(pattern_idx, np.array([qual_value]))
+
+    @abstractmethod
+    def step(self, *actions) -> Union[tuple[ScadaData, float, bool], tuple[ScadaData, float]]:
+        """
+        Performs the next step by applying an action and observing
+        the consequences (SCADA data, reward, terminated).
+
+        Note that `terminated` is only returned if `autoreset=False` otherwise
+        only the current SCADA data and reward are returned.
+
+        Returns
+        -------
+        `(` :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` `, float, bool)` or `(` :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` `, float)`
+            Triple or tuple of observations (:class:`~epyt_flow.simulation.scada.scada_data.ScadaData`),
+            reward (`float`), and terminated (`bool`).
+        """
+        raise NotImplementedError()

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/epyt_flow/serialization.py

@@ -4,6 +4,7 @@ Module provides functions and classes for serialization.
 from typing import Any, Union
 from abc import abstractmethod, ABC
 from io import BufferedIOBase
+import pathlib
 import importlib
 import json
 import gzip
@@ -97,7 +98,9 @@ class Serializable(ABC):
     Base class for a serializable class -- must be used in conjunction with the
     :func:`~epyt_flow.serialization.serializable` decorator.
     """
-    def __init__(self, **kwds):
+    def __init__(self, _parent_path: str = "", **kwds):
+        self._parent_path = _parent_path
+
         super().__init__(**kwds)
 
     @abstractmethod
@@ -376,12 +379,19 @@ def load_from_file(f_in: str, use_compression: bool = True) -> Any:
     `Any`
         Deserialized data.
     """
+    inst = None
+
     if use_compression is False:
         with open(f_in, "rb") as f:
-            return umsgpack.unpack(f, ext_handlers=ext_handler_unpack)
+            inst = load(f.read())
     else:
         with gzip.open(f_in, "rb") as f:
-            return load(f.read())
+            inst = load(f.read())
+
+    if isinstance(inst, Serializable):
+        inst._parent_path = pathlib.Path(f_in).parent.resolve()
+
+    return inst
 
 
 def save_to_file(f_out: str, data: Any, use_compression: bool = True) -> None:

{epyt_flow-0.5.0 → epyt_flow-0.6.0}/epyt_flow/simulation/scada/advanced_control.py

@@ -98,7 +98,7 @@ class AdvancedControlModule(ABC):
                 - EN_OPEN    = 1
         """
         valve_idx = self._epanet_api.getLinkValveNameID().index(valve_id)
-        valve_link_idx = self._epanet_api.getLinkValveIndex(valve_idx + 1)
+        valve_link_idx = self._epanet_api.getLinkValveIndex()[valve_idx]
         self._epanet_api.setLinkStatus(valve_link_idx, status)
 
     def set_node_quality_source_value(self, node_id: str, pattern_id: str,