epyt-flow 0.9.0__tar.gz → 0.10.0__tar.gz

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 EPyT-Flow Developers
+Copyright (c) EPyT-Flow Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: epyt-flow
-Version: 0.9.0
+Version: 0.10.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
@@ -17,10 +17,11 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: epyt>=1.2.0
+Requires-Dist: epyt>=1.2.1
 Requires-Dist: requests>=2.31.0
 Requires-Dist: scipy>=1.11.4
 Requires-Dist: u-msgpack-python>=2.8.0
@@ -66,8 +67,8 @@ Unique features of EPyT-Flow that make it superior to other (Python) toolboxes a
 - High- and low-level interface
 - Object-orientated design that is easy to extend and customize
 - Sensor configurations
-- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, cyber-attacks, etc.)
-- Wide variety of pre-defined types of uncertainties (e.g. model uncertainties)
+- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, contamination, cyber-attacks, etc.)
+- Wide variety of pre-defined types of global & local uncertainties (e.g. model uncertainties)
 - Step-wise simulation and environment for training and evaluating control strategies
 - Serialization module for easy exchange of data and (scenario) configurations
 - REST API to make EPyT-Flow accessible in other applications
@@ -76,7 +77,7 @@ Unique features of EPyT-Flow that make it superior to other (Python) toolboxes a
 
 ## Installation
 
-EPyT-Flow supports Python 3.9 - 3.12
+EPyT-Flow supports Python 3.9 - 3.13
 
 Note that [EPANET and EPANET-MSX sources](epyt_flow/EPANET/) are compiled and overwrite the binaries
 shipped by EPyT **IF** EPyT-Flow is installed on a Unix system and the *gcc* compiler is available.

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/README.md

@@ -29,8 +29,8 @@ Unique features of EPyT-Flow that make it superior to other (Python) toolboxes a
 - High- and low-level interface
 - Object-orientated design that is easy to extend and customize
 - Sensor configurations
-- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, cyber-attacks, etc.)
-- Wide variety of pre-defined types of uncertainties (e.g. model uncertainties)
+- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, contamination, cyber-attacks, etc.)
+- Wide variety of pre-defined types of global & local uncertainties (e.g. model uncertainties)
 - Step-wise simulation and environment for training and evaluating control strategies
 - Serialization module for easy exchange of data and (scenario) configurations
 - REST API to make EPyT-Flow accessible in other applications
@@ -39,7 +39,7 @@ Unique features of EPyT-Flow that make it superior to other (Python) toolboxes a
 
 ## Installation
 
-EPyT-Flow supports Python 3.9 - 3.12
+EPyT-Flow supports Python 3.9 - 3.13
 
 Note that [EPANET and EPANET-MSX sources](epyt_flow/EPANET/) are compiled and overwrite the binaries
 shipped by EPyT **IF** EPyT-Flow is installed on a Unix system and the *gcc* compiler is available.

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/REQUIREMENTS.txt

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

epyt_flow-0.10.0/epyt_flow/VERSION

@@ -0,0 +1 @@
+0.10.0

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/epyt_flow/gym/scenario_control_env.py

@@ -107,6 +107,14 @@ class ScenarioControlEnv(ABC):
             Current SCADA data (i.e. sensor readings).
         """
         if self._scenario_sim is not None:
+            # Abort current simulation if any is runing
+            try:
+                next(self._sim_generator)
+                self._sim_generator.send(True)
+            except StopIteration:
+                pass
+
+            # Close scenario
             self._scenario_sim.close()
 
         self._scenario_sim = ScenarioSimulator(
@@ -194,7 +202,7 @@ class ScenarioControlEnv(ABC):
         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(pump_idx, pattern_idx)
+            self._scenario_sim.epanet_api.setLinkPumpPatternIndex(pump_idx + 1, pattern_idx)
 
         self._scenario_sim.epanet_api.setPattern(pattern_idx, np.array([speed]))
 

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/epyt_flow/serialization.py

@@ -48,6 +48,10 @@ PUMP_STATE_EVENT_ID                     = 28
 PUMP_SPEED_EVENT_ID                     = 29
 VALVE_STATE_EVENT_ID                    = 30
 SPECIESINJECTION_EVENT_ID               = 31
+SIMPLE_CONTROL_ID                       = 32
+COMPLEX_CONTROL_ID                      = 33
+COMPLEX_CONTROL_CONDITION_ID            = 34
+COMPLEX_CONTROL_ACTION_ID               = 35
 
 
 def my_packb(data: Any) -> bytes:

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/epyt_flow/simulation/events/sensor_reading_attack.py

@@ -46,7 +46,7 @@ class SensorOverrideAttack(SensorReadingAttack, JsonSerializable):
     @property
     def new_sensor_values(self) -> np.ndarray:
         """
-        Get the new sensor reading values -- i.e. these values replace the
+        Returns the new sensor reading values -- i.e. these values replace the
         true sensor reading values.
 
         Returns
@@ -64,7 +64,7 @@ class SensorOverrideAttack(SensorReadingAttack, JsonSerializable):
             raise TypeError("Can not compare 'SensorOverrideAttack' instance " +
                             f"with '{type(other)}' instance")
 
-        return super().__eq__(other) and self.__new_sensor_values == other.new_sensor_values
+        return super().__eq__(other) and np.all(self.__new_sensor_values == other.new_sensor_values)
 
     def __str__(self) -> str:
         return f"{type(self).__name__} {super().__str__()} " +\
@@ -151,6 +151,19 @@ class SensorReplayAttack(SensorReadingAttack, JsonSerializable):
         """
         return self.__sensor_data_time_window_end
 
+    @property
+    def new_sensor_values(self) -> np.ndarray:
+        """
+        Returns the new sensor reading values -- i.e. these values replace the
+        true sensor reading values.
+
+        Returns
+        -------
+        `np.ndarray`
+            New sensor readings.
+        """
+        return deepcopy(self.__new_sensor_values)
+
     def get_attributes(self) -> dict:
         my_attributes = {"new_sensor_values": self.__new_sensor_values,
                          "replay_data_time_window_start": self.__sensor_data_time_window_start,
@@ -163,7 +176,7 @@ class SensorReplayAttack(SensorReadingAttack, JsonSerializable):
             raise TypeError("Can not compare 'SensorReplayAttack' instance " +
                             f"with '{type(other)}' instance")
 
-        return super().__eq__(other) and self.__new_sensor_values == other.new_sensor_values
+        return super().__eq__(other) and np.all(self.__new_sensor_values == other.new_sensor_values)
 
     def __str__(self) -> str:
         return f"{type(self).__name__} {super().__str__()} " +\

{epyt_flow-0.9.0 → epyt_flow-0.10.0}/epyt_flow/simulation/events/sensor_reading_event.py

@@ -95,13 +95,28 @@ class SensorReadingEvent(Event):
             if self.__sensor_id not in sensor_config.tank_volume_sensors:
                 __show_warning()
         elif self.__sensor_type == SENSOR_TYPE_NODE_BULK_SPECIES:
-            if self.__sensor_id not in sensor_config.bulk_species_node_sensors:
+            sensor_present = False
+            for _, sensors_id in sensor_config.bulk_species_node_sensors.items():
+                if self.__sensor_id in sensors_id:
+                    sensor_present = True
+                    break
+            if sensor_present is False:
                 __show_warning()
         elif self.__sensor_type == SENSOR_TYPE_LINK_BULK_SPECIES:
-            if self.__sensor_id not in sensor_config.bulk_species_link_sensors:
+            sensor_present = False
+            for _, sensors_id in sensor_config.bulk_species_link_sensors.items():
+                if self.__sensor_id in sensors_id:
+                    sensor_present = True
+                    break
+            if sensor_present is False:
                 __show_warning()
         elif self.__sensor_type == SENSOR_TYPE_SURFACE_SPECIES:
-            if self.__sensor_id not in sensor_config.surface_species_sensors:
+            sensor_present = False
+            for _, sensors_id in sensor_config.surface_species_sensors.items():
+                if self.__sensor_id in sensors_id:
+                    sensor_present = True
+                    break
+            if sensor_present is False:
                 __show_warning()
 
     @property

epyt_flow-0.10.0/epyt_flow/simulation/scada/__init__.py

@@ -0,0 +1,5 @@
+from .scada_data import *
+from .scada_data_export import *
+from .custom_control import *
+from .simple_control import *
+from .complex_control import *

epyt_flow-0.10.0/epyt_flow/simulation/scada/advanced_control.py

@@ -0,0 +1,138 @@
+"""
+Deprecated -- use epyt_flow.simulation.scada.custom_control instead
+"""
+import warnings
+from abc import abstractmethod, ABC
+import numpy as np
+import epyt
+
+from . import ScadaData
+
+
+warnings.warn("'epyt_flow.simulation.scada.advanced_control' is deprecated and will be removed " +
+              "in future releases -- use 'epyt_flow.simulation.scada.custom_control' instead")
+
+
+class AdvancedControlModule(ABC):
+    """
+    Base class for a control module.
+
+    Attributes
+    ----------
+    epanet_api : `epyt.epanet <https://epanet-python-toolkit-epyt.readthedocs.io/en/latest/api.html#epyt.epanet.epanet>`_
+        API to EPANET and EPANET-MSX. Is set in :func:`init`.
+    """
+    def __init__(self, **kwds):
+        self._epanet_api = None
+
+        super().__init__(**kwds)
+
+    def init(self, epanet_api: epyt.epanet) -> None:
+        """
+        Initializes the control module.
+
+        Parameters
+        ----------
+        epanet_api : `epyt.epanet <https://epanet-python-toolkit-epyt.readthedocs.io/en/latest/api.html#epyt.epanet.epanet>`_
+            API to EPANET for implementing the control module.
+        """
+        if not isinstance(epanet_api, epyt.epanet):
+            raise TypeError("'epanet_api' must be an instance of 'epyt.epanet' but not of " +
+                            f"'{type(epanet_api)}'")
+
+        self._epanet_api = epanet_api
+
+    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._epanet_api.getLinkPumpNameID().index(pump_id)
+        pump_link_idx = self._epanet_api.getLinkPumpIndex(pump_idx + 1)
+        self._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._epanet_api.getLinkPumpNameID().index(pump_id)
+        pattern_idx = self._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._epanet_api.addPattern(f"pump_speed_{pump_id}")
+            self._epanet_api.setLinkPumpPatternIndex(pattern_idx)
+
+        self._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._epanet_api.getLinkValveNameID().index(valve_id)
+        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,
+                                      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._epanet_api.getNodeIndex(node_id)
+        pattern_idx = self._epanet_api.getPatternIndex(pattern_id)
+        self._epanet_api.setNodeSourceQuality(node_idx, 1)
+        self._epanet_api.setPattern(pattern_idx, np.array([qual_value]))
+
+    @abstractmethod
+    def step(self, scada_data: ScadaData) -> None:
+        """
+        Implements the control algorithm -- i.e. mapping of sensor reading to actions.
+
+        Parameters
+        ----------
+        scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            Sensor readings.
+        """
+        raise NotImplementedError()