epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/serialization.py

@@ -0,0 +1,438 @@
+"""
+Module provides functions and classes for serialization.
+"""
+from typing import Any, Union
+from abc import abstractmethod, ABC
+from io import BufferedIOBase
+import importlib
+import json
+import gzip
+import umsgpack
+import numpy as np
+import networkx
+import scipy
+
+
+SCIPY_BSRARRAY_ID                       = -3
+NETWORKX_GRAPH_ID                       = -2
+NUMPY_ARRAY_ID                          = -1
+SENSOR_CONFIG_ID                        = 0
+SCENARIO_CONFIG_ID                      = 1
+MODEL_UNCERTAINTY_ID                    = 2
+SENSOR_NOISE_ID                         = 3
+ABSOLUTE_GAUSSIAN_UNCERTAINTY_ID        = 4
+RELATIVE_GAUSSIAN_UNCERTAINTY_ID        = 5
+ABSOLUTE_UNIFORM_UNCERTAINTY_ID         = 6
+RELATIVE_UNIFORM_UNCERTAINTY_ID         = 7
+PERCENTAGE_DEVIATON_UNCERTAINTY_ID      = 8
+ABSOLUTE_DEEP_UNIFORM_UNCERTAINTY_ID    = 9
+RELATIVE_DEEP_UNIFORM_UNCERTAINTY_ID    = 10
+ABSOLUTE_DEEP_GAUSSIAN_UNCERTAINTY_ID   = 11
+RELATIVE_DEEP_GAUSSIAN_UNCERTAINTY_ID   = 12
+ABSOLUTE_DEEP_UNCERTAINTY_ID            = 13
+RELATIVE_DEEP_UNCERTAINTY_ID            = 14
+SENSOR_FAULT_CONSTANT_ID                = 15
+SENSOR_FAULT_DRIFT_ID                   = 16
+SENSOR_FAULT_GAUSSIAN_ID                = 17
+SENSOR_FAULT_PERCENTAGE_ID              = 18
+SENSOR_FAULT_STUCKATZERO_ID             = 19
+LEAKAGE_ID                              = 20
+ABRUPT_LEAKAGE_ID                       = 21
+INCIPIENT_LEAKAGE_ID                    = 22
+SCADA_DATA_ID                           = 23
+SENSOR_ATTACK_OVERRIDE_ID               = 24
+SENSOR_ATTACK_REPLAY_ID                 = 25
+NETWORK_TOPOLOGY_ID                     = 26
+PUMP_STATE_EVENT_ID                     = 28
+PUMP_SPEED_EVENT_ID                     = 29
+VALVE_STATE_EVENT_ID                    = 30
+
+
+def my_packb(data: Any) -> bytes:
+    """
+    Overriden `umsgpack.packb` method to support custom serialization handlers.
+    """
+    return umsgpack.packb(data, ext_handlers=ext_handler_pack)
+
+
+def my_unpackb(data: Any) -> Any:
+    """
+    Overriden `umsgpack.unpackb` method to support custom serialization handlers.
+    """
+    return umsgpack.unpackb(data, ext_handlers=ext_handler_unpack)
+
+
+def serializable(my_id: int, my_file_ext: str) -> Any:
+    """
+    Decorator for a serializable class -- i.e. subclass of
+    :class:`~epyt_flow.serialization.Serializable`.
+
+    This decorator registers a new class as a serializable class.
+
+    Parameters
+    ----------
+    my_id : `int`
+        ID of the class.
+    my_file_ext : `str`
+        File extension.
+    """
+    def wrapper(my_class):
+        @staticmethod
+        def unpackb(data: bytes) -> Any:
+            return my_class(**my_unpackb(data))
+        setattr(my_class, "unpackb", unpackb)
+
+        @staticmethod
+        def file_ext() -> str:
+            return my_file_ext
+        setattr(my_class, "file_ext", file_ext)
+
+        return umsgpack.ext_serializable(my_id)(my_class)
+
+    return wrapper
+
+
+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):
+        super().__init__(**kwds)
+
+    @abstractmethod
+    def get_attributes(self) -> dict:
+        """
+        Gets all attributes to be serialized -- these attributes are passed to the
+        constructor when the object is deserialized.
+
+        Returns
+        -------
+        `dict`
+            Dictionary of attributes -- i.e. pairs of attribute name + value.
+        """
+        return {}
+
+    def file_ext(self) -> str:
+        """
+        Returns the file extension of this class.
+
+        This function is automatically implemented by applying the
+        :func:`~epyt_flow.serialization.serializable` decorator.
+
+        Returns
+        -------
+        `str`
+            File extension.
+        """
+        raise NotImplementedError()
+
+    def packb(self) -> bytes:
+        """
+        Serializes the attributes of this object.
+
+        Returns
+        -------
+        `bytes`
+            Serialized object.
+        """
+        return my_packb(self.get_attributes())
+
+    @staticmethod
+    def load(data: Union[bytes, BufferedIOBase]) -> Any:
+        """
+        Deserializes an instance of this class.
+
+        Parameters
+        ----------
+        data : `bytes` or `io.BufferedIOBase`
+            Serialized data or stream from which serialized data can be read.
+
+        Returns
+        -------
+        `Any`
+            Deserialized object.
+        """
+        return load(data)
+
+    @staticmethod
+    def load_from_file(f_in: str, use_zip: bool = True) -> Any:
+        """
+        Deserializes an instance of this class from a (compressed) file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the file from which to deserialize the object.
+        use_zip : `bool`, optional
+            If True, the file `f_in` is supposed to be zip compressed -- False,
+            if no compression was used when serializing the object.
+
+            The default is True.
+
+        Returns
+        -------
+        `Any`
+            Deserialized object.
+        """
+        return load_from_file(f_in, use_zip)
+
+    def dump(self, stream_out: BufferedIOBase = None) -> Any:
+        """
+        Serializes this object to a byte array.
+
+        Parameters
+        ----------
+        stream_out : `io.BufferedIOBase`, optional
+            Stream to which the serialized object is written.
+            If None, the serialized object is returned as a `bytes` array.
+
+            The default is None.
+
+        Returns
+        -------
+        `bytes`
+            If `stream_out` is None, the serialized object is returned as a `bytes` array.
+        """
+        return dump(self, stream_out)
+
+    def save_to_file(self, f_out: str, use_zip: bool = True) -> None:
+        """
+        Serializes this instance and stores it in a (compressed) file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the file where this serialized object will be stored.
+        use_zip : `bool`, optional
+            If True, the file `f_in` will be zip compressed -- False,
+            if no compression is wanted.
+
+            The default is True.
+        """
+        if not f_out.endswith(self.file_ext()):
+            f_out += self.file_ext()
+
+        return save_to_file(f_out, self, use_zip)
+
+
+def my_to_json(obj: Any) -> str:
+    """
+    Serializes a given object to JSON.
+
+    Parameters
+    ----------
+    obj : `Any`
+        Object to be serialized.
+
+    Returns
+    -------
+    `str`
+        JSON data.
+    """
+    def __json_serialize(obj_: Any) -> dict:
+        if isinstance(obj_, JsonSerializable):
+            my_class_name = (obj_.__module__, obj_.__class__.__name__)
+            return obj_.get_attributes() | {"__type__": my_class_name}
+        elif isinstance(obj_, np.ndarray):
+            return obj_.tolist()
+        else:
+            return obj_
+
+    return json.dumps(obj, default=__json_serialize)
+
+
+def my_load_from_json(data: str) -> Any:
+    """
+    Loads (i.e. deserializes) an object from given JSON data.
+
+    Parameters
+    ----------
+    data : `str`
+        JSON data.
+
+    Returns
+    -------
+    `Any`
+        Deserialized object.
+    """
+    def __object_hook(obj: dict) -> dict:
+        if "__type__" in obj:
+            module_name, class_name = obj["__type__"]
+            cls = getattr(importlib.import_module(module_name), class_name)
+            del obj["__type__"]
+
+            for attr in obj:
+                if isinstance(attr, dict):
+                    obj[attr] = __object_hook(obj[attr])
+
+            return cls(**obj)
+        return obj
+
+    return json.loads(data, object_hook=__object_hook)
+
+
+class JsonSerializable(Serializable):
+    """
+    Base class for JSON serializable classes.
+    Inherits from :class:`~epyt_flow.serialization.Serializable`.
+    """
+
+    def to_json(self) -> str:
+        """
+        Serializes this instance to JSON.
+
+        Returns
+        -------
+        `str`
+            JSON data.
+        """
+        return my_to_json(self)
+
+    @staticmethod
+    def load_from_json(data: str) -> Any:
+        """
+        Loads (i.e. deserializes) an instance of this class from given JSON data.
+
+        Parameters
+        ----------
+        data : `str`
+            JSON data.
+
+        Returns
+        -------
+        `Any`
+            Deserialized instance of this class.
+        """
+        return my_load_from_json(data)
+
+
+def load(data: Union[bytes, BufferedIOBase]) -> Any:
+    """
+    Deserializes data.
+
+    Parameters
+    ----------
+    data : `bytes` or `io.BufferedIOBase`
+        Serialized data or stream from which serialized data can be read.
+
+    Returns
+    -------
+    `Any`
+        Deserialized data.
+    """
+    if isinstance(data, bytes):
+        return my_unpackb(data)
+    elif isinstance(data, BufferedIOBase):
+        return my_unpackb(data.read())
+    else:
+        raise TypeError("Invalid type of 'data' -- must be either instance of 'bytes' or " +
+                        f"'io.BufferedIOBase' but not of '{type(data)}'")
+
+
+def dump(data: Any, stream_out: BufferedIOBase = None) -> Union[bytes, None]:
+    """
+    Serializes some given data to a byte array.
+
+    Parameters
+    ----------
+    stream_out : `io.BufferedIOBase`, optional
+        Stream to which the serialized object is written.
+        If None, the serialized object is returned as a `bytes` array.
+
+        The default is None.
+
+    Returns
+    -------
+    `bytes`
+        Serialized data if `stream_out` is None -- otherwise, nothing is returned.
+    """
+    if stream_out is None:
+        return my_packb(data)
+    else:
+        if not isinstance(stream_out, BufferedIOBase):
+            raise TypeError("'stream_out' must be an instance of 'io.BufferedIOBase' " +
+                            f"but not of '{type(stream_out)}'")
+
+        stream_out.write(my_packb(data))
+
+
+def load_from_file(f_in: str, use_compression: bool = True) -> Any:
+    """
+    Deserializes data from a (compressed) file.
+
+    Parameters
+    ----------
+    f_in : `str`
+        Path to the file from which to deserialize the data.
+    use_compression : `bool`, optional
+        If True, the file `f_in` is supposed to be gzip compressed -- False,
+        if no compression was used when serializing the data.
+
+        The default is True.
+
+    Returns
+    -------
+    `Any`
+        Deserialized data.
+    """
+    if use_compression is False:
+        with open(f_in, "rb") as f:
+            return umsgpack.unpack(f, ext_handlers=ext_handler_unpack)
+    else:
+        with gzip.open(f_in, "rb") as f:
+            return load(f.read())
+
+
+def save_to_file(f_out: str, data: Any, use_compression: bool = True) -> None:
+    """
+    Serializes data and stores it in a (compressed) file.
+
+    Parameters
+    ----------
+    f_in : `str`
+        Path to the file where the serialized data will be stored.
+    use_compression : `bool`, optional
+        If True, the file `f_in` will be gzip compressed -- False, if no compression is wanted.
+
+        The default is True.
+    """
+    if use_compression is False:
+        with open(f_out, "wb") as f:
+            umsgpack.pack(data, f, ext_handlers=ext_handler_pack)
+    else:
+        with gzip.open(f_out, "wb") as f:
+            f.write(dump(data))
+
+
+# Add numpy.ndarray, networkx.Graph, and scipy.sparse.bsr_array support
+def __encode_bsr_array(array: scipy.sparse.bsr_array
+                       ) -> tuple[tuple[int, int], tuple[list[float], tuple[list[int], list[int]]]]:
+    shape = array.shape
+    data = array.data.flatten().tolist()
+    rows = array.nonzero()[0].tolist()
+    cols = array.nonzero()[1].tolist()
+
+    return shape, (data, (rows, cols))
+
+
+def __decode_bsr_array(ext_data: tuple[tuple[int, int],
+                                       tuple[list[float], tuple[list[int], list[int]]]]
+                       ) -> scipy.sparse.bsr_array:
+    shape, data = ext_data
+    return scipy.sparse.bsr_array((data[0], (data[1][0], data[1][1])), shape=(shape[0], shape[1]))
+
+
+ext_handler_pack = {np.ndarray:
+                    lambda arr: umsgpack.Ext(NUMPY_ARRAY_ID, umsgpack.packb(arr.tolist())),
+                    networkx.Graph:
+                        lambda graph:
+                            umsgpack.Ext(NETWORKX_GRAPH_ID,
+                                         umsgpack.packb(networkx.node_link_data(graph))),
+                    scipy.sparse.bsr_array:
+                    lambda arr: umsgpack.Ext(SCIPY_BSRARRAY_ID,
+                                             umsgpack.packb(__encode_bsr_array(arr)))}
+ext_handler_unpack = {NUMPY_ARRAY_ID: lambda ext: np.array(umsgpack.unpackb(ext.data)),
+                      NETWORKX_GRAPH_ID:
+                      lambda ext: networkx.node_link_graph(umsgpack.unpackb(ext.data)),
+                      SCIPY_BSRARRAY_ID: lambda ext: __decode_bsr_array(umsgpack.unpackb(ext.data))}

epyt_flow/simulation/__init__.py

@@ -0,0 +1,5 @@
+from .scenario_config import *
+from .sensor_config import *
+from .scenario_simulator import *
+from .scenario_visualizer import *
+from .parallel_simulation import *

epyt_flow/simulation/events/__init__.py

@@ -0,0 +1,6 @@
+from .system_event import *
+from .leakages import *
+from .sensor_reading_event import *
+from .sensor_faults import *
+from .sensor_reading_attack import *
+from .actuator_events import *

epyt_flow/simulation/events/actuator_events.py

@@ -0,0 +1,259 @@
+"""
+Module provides implementations of different types of actuator events.
+"""
+import warnings
+from epyt.epanet import epanet
+import numpy as np
+
+from .system_event import SystemEvent
+from ...serialization import serializable, JsonSerializable, PUMP_STATE_EVENT_ID, \
+    PUMP_SPEED_EVENT_ID, VALVE_STATE_EVENT_ID
+
+
+class ActuatorConstants:
+    """
+    Class defining some constants related to actuator events.
+
+    Attributes
+    ----------
+    EN_CLOSED
+        Valve or pump is closed.
+    EN_OPEN
+        Valve or pump is open -- i.e. active.
+    """
+    EN_CLOSED       = 0
+    EN_OPEN         = 1
+
+
+class ActuatorEvent(SystemEvent):
+    """
+    Base class of an actuator event.
+
+    .. note::
+        Note that actuator events are one-time events -- i.e.
+        they are executed only once at a given point in time.
+
+    Parameters
+    ----------
+    time : int
+        Time (in seconds since simulation start) at which this event is executed.
+    """
+    def __init__(self, time: int, **kwds):
+        super().__init__(start_time=time, end_time=time+1, **kwds)
+
+    def get_attributes(self) -> dict:
+        return {"time": self.start_time}
+
+
+class PumpEvent(ActuatorEvent):
+    """
+    Base class of a pump event.
+
+    Parameters
+    ----------
+    pump_id : str
+        ID of the pump that is affected by this event.
+    """
+    def __init__(self, pump_id: str, **kwds):
+        self.__pump_id = pump_id
+
+        super().__init__(**kwds)
+
+    def init(self, epanet_api: epanet) -> None:
+        if self.__pump_id not in epanet_api.getLinkPumpNameID():
+            raise ValueError(f"Invalid pump ID '{self.__pump_id}'")
+
+        super().init(epanet_api)
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"pump_id": self.__pump_id}
+
+    @property
+    def pump_id(self) -> str:
+        """
+        Gets the ID of the pump affected by this event.
+
+        Returns
+        -------
+        `str`
+            Pump ID.
+        """
+        return self.__pump_id
+
+
+@serializable(PUMP_STATE_EVENT_ID, ".epytflow_pump_state_event")
+class PumpStateEvent(PumpEvent, JsonSerializable):
+    """
+    Class implementing a pump state event.
+
+    Parameters
+    ----------
+    pump_state : `str`
+        New state of the pump -- i.e. the state of the pump is set to this value
+        while the event is active.
+
+        Must be one of the following constants defined in
+        :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+            - EN_CLOSED  = 0
+            - EN_OPEN    = 1
+    """
+    def __init__(self, pump_state: int, **kwds):
+        if not isinstance(pump_state, int):
+            raise TypeError("'pump_state' must be an instace of 'int' " +
+                            f"but not of {type(pump_state)}")
+        if not 0 <= pump_state <= 1:
+            raise ValueError(f"Invalid pump state '{pump_state}' -- " +
+                             "must be either EN_CLOSED (0) or EN_OPEN (1)")
+
+        self.__pump_state = pump_state
+
+        super().__init__(**kwds)
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"pump_state": self.__pump_state}
+
+    @property
+    def pump_state(self) -> int:
+        """
+        Gets the new pump state.
+
+        Returns
+        -------
+        `int`
+            New pump state.
+
+            One of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+                - EN_CLOSED  = 0
+                - EN_OPEN    = 1
+        """
+        return self.__pump_state
+
+    def apply(self, cur_time: int) -> None:
+        pump_idx = self._epanet_api.getLinkPumpNameID().index(self.pump_id) + 1
+        pump_link_idx = self._epanet_api.getLinkPumpIndex(pump_idx)
+        self._epanet_api.setLinkStatus(pump_link_idx, self.__pump_state)
+
+
+@serializable(PUMP_SPEED_EVENT_ID, ".epytflow_pump_speed_event")
+class PumpSpeedEvent(PumpEvent, JsonSerializable):
+    """
+    Class implementing a pump speed event.
+
+    Parameters
+    ----------
+    pump_speed : float
+        New pump speed -- i.e. the speed of the pump is set to this value while the event is active.
+    """
+    def __init__(self, pump_speed: float, **kwds):
+        if not isinstance(pump_speed, float):
+            raise TypeError("'pump_speed' must be an instance of 'float' " +
+                            f"but not of {type(pump_speed)}")
+        if pump_speed <= 0:
+            raise ValueError("Pump speed must be positive")
+
+        self.__pump_speed = pump_speed
+
+        super().__init__(**kwds)
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"pump_speed": self.__pump_speed}
+
+    @property
+    def pump_speed(self) -> float:
+        """
+        Gets the new pump speed.
+
+        Returns
+        -------
+        `float`
+            New pump speed.
+        """
+        return self.__pump_speed
+
+    def apply(self, cur_time: int) -> None:
+        pump_idx = self._epanet_api.getLinkPumpNameID().index(self.pump_id) + 1
+        pattern_idx = self._epanet_api.getLinkPumpPatternIndex(pump_idx)
+
+        if pattern_idx == 0:
+            warnings.warn(f"No pattern for pump '{self.pump_id}' found -- a new pattern is created")
+            pattern_idx = self._epanet_api.addPattern(f"pump_speed_{self.pump_id}")
+            self._epanet_api.setLinkPumpPatternIndex(pattern_idx)
+
+        self._epanet_api.setPattern(pattern_idx, np.array([self.__pump_speed]))
+
+
+@serializable(VALVE_STATE_EVENT_ID, ".epytflow_valve_state_event")
+class ValveStateEvent(ActuatorEvent, JsonSerializable):
+    """
+    Class implementing a valve state event.
+
+    Parameters
+    ----------
+    valve_id : `str`
+        ID of the valve that is affected by this event.
+    valve_state : `str`
+        New state of the valve -- i.e. the valve state is set to this value this event is executed.
+
+        Must be one of the following constants defined in
+        :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+
+            - EN_CLOSED       = 0
+            - EN_OPEN         = 1
+    """
+    def __init__(self, valve_id: str, valve_state: int, **kwds):
+        if not isinstance(valve_state, int):
+            raise TypeError("'valve_state' must be an instance of 'int' " +
+                            f"but not of {type(valve_state)}")
+        if not 0 <= valve_state <= 1:
+            raise ValueError(f"Invalid valve state '{valve_state}' -- " +
+                             "must be either EN_CLOSED (0) or EN_OPEN (1)")
+
+        self.__valve_id = valve_id
+        self.__valve_state = valve_state
+
+        super().__init__(**kwds)
+
+    def init(self, epanet_api: epanet) -> None:
+        if self.__valve_id not in epanet_api.getLinkValveNameID():
+            raise ValueError(f"Invalid valve ID '{self.__valve_id}'")
+
+        super().init(epanet_api)
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"valve_id": self.__valve_id,
+                                           "valve_state": self.__valve_state}
+
+    @property
+    def valve_id(self) -> str:
+        """
+        Gets the ID of the valve affected by this event.
+
+        Returns
+        -------
+        `str`
+            Valve ID.
+        """
+        return self.__valve_id
+
+    @property
+    def valve_state(self) -> int:
+        """
+        Gets the new state of the valve.
+
+        Returns
+        -------
+        `int`
+            New valve state.
+
+            One of the following constants defined in
+            :class:`~epyt_flow.simulation.events.actuator_events.ActuatorConstants`:
+        """
+        return self.__valve_state
+
+    def apply(self, cur_time: int) -> None:
+        valve_idx = self._epanet_api.getLinkValveNameID().index(self.__valve_id) + 1
+        valve_link_idx = self._epanet_api.getLinkValveIndex(valve_idx)
+        self._epanet_api.setLinkStatus(valve_link_idx, self.__valve_state)