epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/simulation/events/sensor_faults.py

@@ -0,0 +1,267 @@
+"""
+Module provides classes for implementing different sensor faults.
+"""
+from abc import abstractmethod
+import numpy as np
+
+from .sensor_reading_event import SensorReadingEvent
+from ...serialization import serializable, JsonSerializable, SENSOR_FAULT_CONSTANT_ID, \
+    SENSOR_FAULT_DRIFT_ID, SENSOR_FAULT_GAUSSIAN_ID, SENSOR_FAULT_PERCENTAGE_ID, \
+    SENSOR_FAULT_STUCKATZERO_ID
+
+
+class SensorFault(SensorReadingEvent):
+    """
+    Base class for a sensor fault
+    """
+    # Acknowledgement: This Python implementation is based on
+    # https://github.com/eldemet/sensorfaultmodels/blob/main/sensorfaultmodels.m
+    # and https://github.com/Mariosmsk/sensorfaultmodels/blob/main/sensorfaultmodels.py
+
+    def compute_multiplier(self, cur_time: int) -> float:
+        """
+        Computes the multiplier for a given time stamp.
+
+        Parameters
+        ----------
+        cur_time : `int`
+            Time in seconds.
+
+        Returns
+        -------
+        `float`
+            Multiplier.
+        """
+        b1 = 0
+        b2 = 0
+        a1 = 1
+        a2 = 1
+
+        if cur_time >= self.start_time:
+            b1 = 1 - np.exp(- a1 * (cur_time - self.start_time))
+
+        if cur_time >= self.end_time:
+            b2 = 1 - np.exp(- a2 * (cur_time - self.end_time))
+
+        return b1 - b2
+
+    @abstractmethod
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        """
+        Applies this sensor fault to a given single sensor reading value --
+        i.e. the sensor reading value is perturbed by this fault.
+
+        Parameters:
+        -----------
+        cur_multiplier : `float`
+            Current multiplier -- i.e. controls the "strength" of the fault.
+        sensor_reading : `float`
+            Sensor reading value.
+        cur_time : `int`
+            Current time stamp (in seconds) in the simulation.
+
+        Returns
+        -------
+        `float`
+            Perturbed sensor reading value.
+        """
+        raise NotImplementedError()
+
+    def apply(self, sensor_readings: np.ndarray,
+              sensor_readings_time: np.ndarray) -> np.ndarray:
+        for i in range(sensor_readings.shape[0]):
+            t = sensor_readings_time[i]
+            sensor_readings[i] = self.apply_sensor_fault(self.compute_multiplier(t),
+                                                         sensor_readings[i], t)
+
+        return sensor_readings
+
+
+@serializable(SENSOR_FAULT_CONSTANT_ID, ".epytflow_sensorfault_constant")
+class SensorFaultConstant(SensorFault, JsonSerializable):
+    """
+    Class implementing a constant shift sensor fault.
+
+    Parameters
+    ----------
+    constant_shift : `float`
+        Constant that is added to the sensor reading.
+    """
+    def __init__(self, constant_shift: float, **kwds):
+        if not isinstance(constant_shift, float):
+            raise TypeError("'constant_shift' must be an instance of 'float' but no of " +
+                            f"'{type(constant_shift)}'")
+
+        self.__constant_shift = constant_shift
+
+        super().__init__(**kwds)
+
+    @property
+    def constant_shift(self) -> float:
+        """
+        Gets the Constant that is added to the sensor reading.
+
+        Returns
+        -------
+        `float`
+            Constant that is added to the sensor reading.
+        """
+        return self.__constant_shift
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"constant_shift": self.__constant_shift}
+
+    def __eq__(self, other) -> bool:
+        return super().__eq__(other) and self.__constant_shift == other.constant_shift
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} constant: {self.__constant_shift}"
+
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        return sensor_reading + cur_multiplier * self.__constant_shift
+
+
+@serializable(SENSOR_FAULT_DRIFT_ID, ".epytflow_sensorfault_drift")
+class SensorFaultDrift(SensorFault, JsonSerializable):
+    """
+    Class implementing a drift sensor fault.
+
+    Parameters
+    ----------
+    coef : `float`
+        Coefficient of the drift.
+    """
+    def __init__(self, coef: float, **kwds):
+        self.__coef = coef
+
+        super().__init__(**kwds)
+
+    @property
+    def coef(self) -> float:
+        """
+        Gets the coefficient of the drift.
+
+        Returns
+        -------
+        `float`
+            Coefficient of the drift.
+        """
+        return self.__coef
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"coef": self.__coef}
+
+    def __eq__(self, other) -> bool:
+        return super().__eq__(other) and self.__coef == other.coef
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} coef: {self.__coef}"
+
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        return sensor_reading + cur_multiplier * (self.__coef * (cur_time - self.start_time))
+
+
+@serializable(SENSOR_FAULT_GAUSSIAN_ID, ".epytflow_sensorfault_gaussian")
+class SensorFaultGaussian(SensorFault, JsonSerializable):
+    """
+    Class implementing a Gaussian shift sensor fault -- i.e.
+     adding Gaussian noise (centered at zero) to the sensor reading.
+
+    Parameters
+    ----------
+    std : `float`
+        Standard deviation of the Gaussian noise.
+    """
+    def __init__(self, std: float, **kwds):
+        if not isinstance(std, float) or not std > 0:
+            raise ValueError("'std' must be an instance of 'float' and be greater than 0")
+
+        self.__std = std
+
+        super().__init__(**kwds)
+
+    @property
+    def std(self) -> float:
+        """
+        Gets the standard deviation of the Gaussian noise.
+
+        Returns
+        -------
+        `float`
+            Standard deviation of the Gaussian noise.
+        """
+        return self.__std
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"std": self.__std}
+
+    def __eq__(self, other) -> bool:
+        return super().__eq__(other) and self.__std == other.std
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} std: {self.__std}"
+
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        return sensor_reading + cur_multiplier * np.random.normal(loc=0, scale=self.__std)
+
+
+@serializable(SENSOR_FAULT_PERCENTAGE_ID, ".epytflow_sensorfault_percentage",)
+class SensorFaultPercentage(SensorFault, JsonSerializable):
+    """
+    Class implementing a percentage shift sensor fault.
+
+    Parameters
+    ----------
+    coef : `float`
+        Coefficient (percentage) of the shift -- i.e. coef must be in (0,].
+    """
+    def __init__(self, coef: float, **kwds):
+        if not isinstance(coef, float) or not coef > 0:
+            raise ValueError("'coef' must be an instance of 'float' and be greater than zero.")
+
+        self.__coef = coef
+
+        super().__init__(**kwds)
+
+    @property
+    def coef(self) -> float:
+        """
+        Gets the coefficient (percentage) of the shift.
+
+        Returns
+        -------
+        `float`
+            Coefficient (percentage) of the shift.
+        """
+        return self.__coef
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"coef": self.__coef}
+
+    def __eq__(self, other) -> bool:
+        return super().__eq__(other) and self.__coef == other.coef
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} coef: {self.__coef}"
+
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        return sensor_reading + cur_multiplier * self.__coef * sensor_reading
+
+
+@serializable(SENSOR_FAULT_STUCKATZERO_ID, ".epytflow_sensorfault_zero")
+class SensorFaultStuckZero(SensorFault, JsonSerializable):
+    """
+    Class implementing a stuck-at-zero sensor fault -- i.e. sensor reading is set to zero.
+    """
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()}"
+
+    def apply_sensor_fault(self, cur_multiplier: float, sensor_reading: float,
+                           cur_time: int) -> float:
+        return sensor_reading + cur_multiplier * (-1. * sensor_reading)

epyt_flow/simulation/events/sensor_reading_attack.py

@@ -0,0 +1,185 @@
+"""
+This module provides classes for implementing different types of sensor reading attacks.
+"""
+from copy import deepcopy
+import numpy as np
+
+from .sensor_reading_event import SensorReadingEvent
+from ...serialization import serializable, JsonSerializable, SENSOR_ATTACK_OVERRIDE_ID, \
+    SENSOR_ATTACK_REPLAY_ID
+
+
+class SensorReadingAttack(SensorReadingEvent):
+    """
+    Base class of a sensor reading attack.
+    """
+
+
+@serializable(SENSOR_ATTACK_OVERRIDE_ID, ".epytflow_sensorattack_override")
+class SensorOverrideAttack(SensorReadingAttack, JsonSerializable):
+    """
+    Class implementing a sensor override attack -- i.e. sensor reading values are overwritten
+    by pre-defined values.
+
+    If the override attack is running out of pre-defined sensor reading values,
+    it repeats the given values from the beginning onwards.
+
+    Parameters
+    ----------
+    new_sensor_values : `numpy.ndarray`
+        New sensor reading values -- i.e. these values replace the true sensor reading values.
+    """
+    def __init__(self, new_sensor_values: np.ndarray, **kwds):
+        if not isinstance(new_sensor_values, np.ndarray):
+            raise TypeError("'new_sensor_values' must be an instance of 'numpy.ndarray' " +
+                            f"but not of '{type(new_sensor_values)}'")
+        if len(new_sensor_values.shape) != 1:
+            raise ValueError("'new_sensor_values' must be a 1-dimensional array")
+        if len(new_sensor_values) == 0:
+            raise ValueError("'new_sensor_values' can not be empty")
+
+        self.__new_sensor_values = new_sensor_values
+        self.__cur_replay_idx = 0
+
+        super().__init__(**kwds)
+
+    @property
+    def new_sensor_values(self) -> np.ndarray:
+        """
+        Get 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:
+        return super().get_attributes() | {"new_sensor_values": self.__new_sensor_values}
+
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, SensorOverrideAttack):
+            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
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} " +\
+            f"new_sensor_values: {self.__new_sensor_values}"
+
+    def apply(self, sensor_readings: np.ndarray,
+              sensor_readings_time: np.ndarray) -> np.ndarray:
+        for i in range(sensor_readings.shape[0]):
+            t = sensor_readings_time[i]
+
+            if self.start_time <= t <= self.end_time:
+                sensor_readings[i] = self.__new_sensor_values[self.__cur_replay_idx]
+                self.__cur_replay_idx = (self.__cur_replay_idx + 1) % len(self.__new_sensor_values)
+
+        return sensor_readings
+
+
+@serializable(SENSOR_ATTACK_REPLAY_ID, ".epytflow_sensorattack_replay")
+class SensorReplayAttack(SensorReadingAttack, JsonSerializable):
+    """
+    Class implementing a sensor replay attack -- i.e. sensor readings are replaced by
+    historical recordings.
+
+    If the provided time window of historical recordings is smaller than the time window of the
+    attack, it repeats the historical values from the beginning onwards.
+
+    Parameters
+    ----------
+    replay_data_time_window_start : `int`
+        Start (seconds since simulation start) of the time window that is used in the replay
+        of sensor readings.
+    replay_data_time_window_end : `int`
+        End (seconds since simulation start) of the time window that is used in the replay
+        of sensor readings.
+    """
+    def __init__(self, replay_data_time_window_start: int, replay_data_time_window_end: int,
+                 **kwds):
+        if not isinstance(replay_data_time_window_start, int):
+            raise TypeError("'replay_data_time_window_start' must be an instance of 'int' " +
+                            f"but not of {type(replay_data_time_window_start)}")
+        if not isinstance(replay_data_time_window_end, int):
+            raise TypeError("'replay_data_time_window_end' must be an instance of 'int' " +
+                            f"but not of {type(replay_data_time_window_end)}")
+        if replay_data_time_window_start > replay_data_time_window_end or \
+                replay_data_time_window_start < 0:
+            raise ValueError("Invalid values for 'replay_data_time_window_start' and/or " +
+                             "'replay_data_time_window_end' detected.")
+
+        self.__new_sensor_values = np.zeros(replay_data_time_window_end -
+                                            replay_data_time_window_start)
+        self.__sensor_data_time_window_start = replay_data_time_window_start
+        self.__sensor_data_time_window_end = replay_data_time_window_end
+        self.__cur_hist_idx = 0
+        self.__cur_replay_idx = 0
+
+        super().__init__(**kwds)
+
+        if self.__sensor_data_time_window_start > self.start_time:
+            raise ValueError("'replay_data_time_window_start' must be less than 'start_time'")
+
+    @property
+    def sensor_data_time_window_start(self) -> int:
+        """
+        Gets the start time (seconds since simulation start) of the time window
+        that is used in the replay of sensor readings.
+
+        Returns
+        -------
+        `int`
+            Start time.
+        """
+        return self.__sensor_data_time_window_start
+
+    @property
+    def sensor_data_time_window_end(self) -> int:
+        """
+        Gets the end time (seconds since simulation start) of the time window
+        that is used in the replay of sensor readings.
+
+        Returns
+        -------
+        `int`
+            End time.
+        """
+        return self.__sensor_data_time_window_end
+
+    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,
+                         "replay_data_time_window_end": self.__sensor_data_time_window_end}
+
+        return super().get_attributes() | my_attributes
+
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, SensorReplayAttack):
+            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
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__} {super().__str__()} " +\
+            f"new_sensor_values: {self.__new_sensor_values}"
+
+    def apply(self, sensor_readings: np.ndarray,
+              sensor_readings_time: np.ndarray) -> np.ndarray:
+        for i in range(sensor_readings.shape[0]):
+            t = sensor_readings_time[i]
+
+            if self.__sensor_data_time_window_start <= t <= self.__sensor_data_time_window_end:
+                self.__new_sensor_values[self.__cur_hist_idx] = sensor_readings[i]
+                self.__cur_hist_idx += 1
+
+            if self.start_time <= t <= self.end_time:
+                sensor_readings[i] = self.__new_sensor_values[self.__cur_replay_idx]
+                self.__cur_replay_idx = (self.__cur_replay_idx + 1) % len(self.__new_sensor_values)
+
+        return sensor_readings

epyt_flow/simulation/events/sensor_reading_event.py

@@ -0,0 +1,170 @@
+"""
+Module provides a base class for sensor reading events such as sensor faults.
+"""
+from abc import abstractmethod
+import warnings
+import numpy
+
+from .event import Event
+from ..sensor_config import SensorConfig, SENSOR_TYPE_NODE_PRESSURE, SENSOR_TYPE_NODE_QUALITY, \
+    SENSOR_TYPE_NODE_DEMAND, SENSOR_TYPE_LINK_FLOW, SENSOR_TYPE_LINK_QUALITY, \
+    SENSOR_TYPE_VALVE_STATE, SENSOR_TYPE_PUMP_STATE, SENSOR_TYPE_TANK_VOLUME, \
+    SENSOR_TYPE_NODE_BULK_SPECIES, SENSOR_TYPE_LINK_BULK_SPECIES, SENSOR_TYPE_SURFACE_SPECIES
+
+
+class SensorReadingEvent(Event):
+    """
+    Base class for a sensor reading event -- i.e. an event directly affecting sensor readings.
+
+    Parameters
+    ----------
+    sensor_id : `str`
+        ID of the sensor that is affected by this event.
+    sensor_type : `int`
+        Type of the sensor that is specified in 'sensor_id'.
+        Must be one of the following pre-defined constants:
+
+        - SENSOR_TYPE_NODE_PRESSURE     = 1
+        - SENSOR_TYPE_NODE_QUALITY      = 2
+        - SENSOR_TYPE_NODE_DEMAND       = 3
+        - SENSOR_TYPE_LINK_FLOW         = 4
+        - SENSOR_TYPE_LINK_QUALITY      = 5
+        - SENSOR_TYPE_VALVE_STATE       = 6
+        - SENSOR_TYPE_PUMP_STATE        = 7
+        - SENSOR_TYPE_TANK_VOLUME       = 8
+        - SENSOR_TYPE_NODE_BULK_SPECIES = 9
+        - SENSOR_TYPE_NODE_LINK_SPECIES = 10
+        - SENSOR_TYPE_SURFACE_SPECIES   = 11
+    """
+    def __init__(self, sensor_id: str, sensor_type: int, **kwds):
+        if not isinstance(sensor_id, str):
+            raise TypeError("'sensor_id' must be an instance of 'str' but not of " +
+                            f"'{type(sensor_id)}'")
+        if not isinstance(sensor_type, int):
+            raise TypeError("'sensor_type' mut be an instance of 'int' but not of " +
+                            f"'{type(sensor_type)}'")
+        if not 1 <= sensor_type <= 10:
+            raise ValueError("Invalid value of 'sensor_type'")
+
+        self.__sensor_id = sensor_id
+        self.__sensor_type = sensor_type
+
+        super().__init__(**kwds)
+
+    def validate(self, sensor_config: SensorConfig) -> None:
+        """
+        Validates this sensor reading event -- i.e. checks whether the affected
+        sensor is part of the given sensor configuration.
+
+        Parameters
+        ----------
+        sensor_config : :class:`~epyt_flow.simulation.sensor_config.SensorConfig`
+            Sensor configuration.
+        """
+        if not isinstance(sensor_config, SensorConfig):
+            raise TypeError("'sensor_config' must be an instance of " +
+                            "'epyt_flow.simulation.SensorConfig' but not of " +
+                            f"'{type(sensor_config)}'")
+
+        def __show_warning() -> None:
+            warnings.warn("Event does not have any effect because there is " +
+                          f"no sensor at '{self.__sensor_id}'")
+
+        if self.__sensor_type == SENSOR_TYPE_NODE_PRESSURE:
+            if self.__sensor_id not in sensor_config.pressure_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_NODE_QUALITY:
+            if self.__sensor_id not in sensor_config.quality_node_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_NODE_DEMAND:
+            if self.__sensor_id not in sensor_config.demand_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_LINK_FLOW:
+            if self.__sensor_id not in sensor_config.flow_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_LINK_QUALITY:
+            if self.__sensor_id not in sensor_config.quality_link_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_VALVE_STATE:
+            if self.__sensor_id not in sensor_config.valve_state_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_PUMP_STATE:
+            if self.__sensor_id not in sensor_config.pump_state_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_TANK_VOLUME:
+            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:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_LINK_BULK_SPECIES:
+            if self.__sensor_id not in sensor_config.bulk_species_link_sensors:
+                __show_warning()
+        elif self.__sensor_type == SENSOR_TYPE_SURFACE_SPECIES:
+            if self.__sensor_id not in sensor_config.surface_species_sensors:
+                __show_warning()
+
+    @property
+    def sensor_id(self) -> str:
+        """
+        Gets the ID of the node or link that is affected by this event.
+
+        Returns
+        -------
+        `str`
+            Node or link ID.
+        """
+        return self.__sensor_id
+
+    @property
+    def sensor_type(self) -> int:
+        """
+        Gets the sensor type code.
+
+        Returns
+        -------
+        `int`
+            Sensor type code.
+        """
+        return self.__sensor_type
+
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"sensor_id": self.__sensor_id,
+                                           "sensor_type": self.__sensor_type}
+
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, SensorReadingEvent):
+            raise TypeError("Can not compare 'SensorReadingEvent' instance " +
+                            f"with '{type(other)}' instance")
+
+        return super().__eq__(other) and self.__sensor_id == other.sensor_id \
+            and self.__sensor_type == other.sensor_type
+
+    def __str__(self) -> str:
+        return f"{super().__str__()} sensor_id: {self.__sensor_id} " +\
+            f"sensor_type: {self.__sensor_type}"
+
+    def __call__(self, sensor_readings: numpy.ndarray,
+                 sensor_readings_time: numpy.ndarray) -> numpy.ndarray:
+        return self.apply(sensor_readings, sensor_readings_time)
+
+    @abstractmethod
+    def apply(self, sensor_readings: numpy.ndarray,
+              sensor_readings_time: numpy.ndarray) -> numpy.ndarray:
+        """
+        Applies the sensor reading event to sensor reading values -- i.e.
+        modify the sensor readings.
+
+        Parameters
+        ----------
+        sensor_readings : `numpy.ndarray`
+            Original sensor readings.
+        sensor_readings_time : `numpy.ndarray`
+            Time (seconds since simulation start) for each sensor reading row in 'sensor_readings'.
+
+        Returns
+        -------
+        `numpy.ndarray`
+            Modified sensor readings.
+        """
+        raise NotImplementedError()