epyt-flow 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

epyt_flow/simulation/sensor_config.py

@@ -11,17 +11,19 @@ from epyt.epanet import ToolkitConstants
 from ..serialization import SENSOR_CONFIG_ID, JsonSerializable, serializable
 
 
-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_LINK_BULK_SPECIES = 10
-SENSOR_TYPE_SURFACE_SPECIES   = 11
+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_LINK_BULK_SPECIES      = 10
+SENSOR_TYPE_SURFACE_SPECIES        = 11
+SENSOR_TYPE_PUMP_EFFICIENCY        = 12
+SENSOR_TYPE_PUMP_ENERGYCONSUMPTION = 13
 
 AREA_UNIT_FT2 = 1
 AREA_UNIT_M2 = 2
@@ -282,7 +284,7 @@ def is_flowunit_simetric(unit_id: int) -> bool:
     `bool`
         True if the fiven unit is a SI metric unit, False otherwise.
     """
-    return unit_id in [ToolkitConstants.EN_LPM, ToolkitConstants.EN_MLD,
+    return unit_id in [ToolkitConstants.EN_LPS, ToolkitConstants.EN_LPM, ToolkitConstants.EN_MLD,
                        ToolkitConstants.EN_CMH, ToolkitConstants.EN_CMD]
 
 
@@ -462,6 +464,8 @@ class SensorConfig(JsonSerializable):
                  quality_link_sensors: list[str] = [],
                  valve_state_sensors: list[str] = [],
                  pump_state_sensors: list[str] = [],
+                 pump_efficiency_sensors: list[str] = [],
+                 pump_energyconsumption_sensors: list[str] = [],
                  tank_volume_sensors: list[str] = [],
                  bulk_species_node_sensors: dict = {},
                  bulk_species_link_sensors: dict = {},
@@ -572,6 +576,20 @@ class SensorConfig(JsonSerializable):
             raise ValueError("Each item in 'pump_state_sensors' must be in 'pumps' -- cannot " +
                              "place a sensor at a non-existing pump.")
 
+        if not isinstance(pump_efficiency_sensors, list):
+            raise TypeError("'pump_efficiency_sensors' must be an instance of 'list[str]' " +
+                            f"but not of '{type(pump_efficiency_sensors)}'")
+        if any(link not in pumps for link in pump_efficiency_sensors):
+            raise ValueError("Each item in 'pump_efficiency_sensors' must be in 'pumps' -- cannot " +
+                             "place a sensor at a non-existing pump.")
+
+        if not isinstance(pump_energyconsumption_sensors, list):
+            raise TypeError("'pump_energyconsumption_sensors' must be an instance of 'list[str]' " +
+                            f"but not of '{type(pump_energyconsumption_sensors)}'")
+        if any(link not in pumps for link in pump_energyconsumption_sensors):
+            raise ValueError("Each item in 'pump_energyconsumption_sensors' must be in 'pumps' -- cannot " +
+                             "place a sensor at a non-existing pump.")
+
         if not isinstance(tank_volume_sensors, list):
             raise TypeError("'tank_volume_sensors' must be an instance of 'list[str]' " +
                             f"but not of '{type(tank_volume_sensors)}'")
@@ -714,6 +732,8 @@ class SensorConfig(JsonSerializable):
         self.__quality_link_sensors = quality_link_sensors
         self.__valve_state_sensors = valve_state_sensors
         self.__pump_state_sensors = pump_state_sensors
+        self.__pump_energyconsumption_sensors = pump_energyconsumption_sensors
+        self.__pump_efficiency_sensors = pump_efficiency_sensors
         self.__tank_volume_sensors = tank_volume_sensors
         self.__bulk_species_node_sensors = bulk_species_node_sensors
         self.__bulk_species_link_sensors = bulk_species_link_sensors
@@ -771,6 +791,51 @@ class SensorConfig(JsonSerializable):
                             bulkspecies_id_to_idx=sensor_config.bulkspecies_id_to_idx,
                             surfacespecies_id_to_idx=sensor_config.surfacespecies_id_to_idx)
 
+    def is_empty(self) -> bool:
+        """
+        Checks if the sensor configuration is empty -- i.e. no sensors are placed.
+
+        Returns
+        -------
+        `bool`
+            True if no sensors are placed, False otherwise.
+        """
+        if self.__pressure_sensors == [] and self.__flow_sensors == [] \
+                and self.__demand_sensors == [] and self.__quality_node_sensors == [] \
+                and self.__quality_link_sensors == [] and self.__valve_state_sensors == [] \
+                and self.__pump_state_sensors == [] \
+                and self.__pump_energyconsumption_sensors == [] \
+                and self.__pump_efficiency_sensors == [] and self.__tank_volume_sensors == [] \
+                and self.__bulk_species_node_sensors == [] \
+                and self.__bulk_species_link_sensors == [] \
+                and self.__surface_species_sensors == []:
+            return True
+        else:
+            return False
+
+    def place_sensors_everywhere(self) -> None:
+        """
+        Places sensors everywhere -- i.e. every possible quantity is monitored
+        at every position in the network.
+        """
+        self.__pressure_sensors = self.__nodes[:]
+        self.__demand_sensors = self.__nodes[:]
+        self.__flow_sensors = self.__links[:]
+        self.__quality_node_sensors = self.__nodes[:]
+        self.__quality_link_sensors = self.__links[:]
+        self.__pump_state_sensors = self.__pumps[:]
+        self.__pump_energyconsumption_sensors = self.__pumps[:]
+        self.__pump_efficiency_sensors = self.__pumps[:]
+        self.__tank_volume_sensors = self.__tanks[:]
+        self.__bulk_species_node_sensors = {species_id: self.__nodes[:]
+                                            for species_id in self.__bulk_species}
+        self.__bulk_species_link_sensors = {species_id: self.__links[:]
+                                            for species_id in self.__bulk_species}
+        self.__surface_species_sensors = {species_id: self.__links[:]
+                                          for species_id in self.__surface_species}
+
+        self.__compute_indices()
+
     @property
     def node_id_to_idx(self) -> dict:
         """
@@ -1032,6 +1097,12 @@ class SensorConfig(JsonSerializable):
                                            for v in self.__valve_state_sensors], dtype=np.int32)
         self.__pump_state_idx = np.array([self.map_pump_id_to_idx(p)
                                           for p in self.__pump_state_sensors], dtype=np.int32)
+        self.__pump_efficiency_idx = np.array([self.map_pump_id_to_idx(p)
+                                               for p in self.__pump_efficiency_sensors],
+                                               dtype=np.int32)
+        self.__pump_energyconsumption_idx = np.array([self.map_pump_id_to_idx(p)
+                                                      for p in self.__pump_energyconsumption_sensors],
+                                                      dtype=np.int32)
         self.__tank_volume_idx = np.array([self.map_tank_id_to_idx(t)
                                            for t in self.__tank_volume_sensors], dtype=np.int32)
         self.__bulk_species_node_idx = np.array([(self.map_bulkspecies_id_to_idx(s),
@@ -1057,6 +1128,8 @@ class SensorConfig(JsonSerializable):
         n_link_quality_sensors = len(self.__quality_link_sensors)
         n_valve_state_sensors = len(self.__valve_state_sensors)
         n_pump_state_sensors = len(self.__pump_state_sensors)
+        n_pump_efficiency_sensors = len(self.__pump_efficiency_sensors)
+        n_pump_energyconsumption_sensors = len(self.__pump_energyconsumption_sensors)
         n_tank_volume_sensors = len(self.__tank_volume_sensors)
         n_bulk_species_node_sensors = len(list(itertools.chain(
             *self.__bulk_species_node_sensors.values())))
@@ -1070,7 +1143,9 @@ class SensorConfig(JsonSerializable):
         link_quality_idx_shift = node_quality_idx_shift + n_node_quality_sensors
         valve_state_idx_shift = link_quality_idx_shift + n_link_quality_sensors
         pump_state_idx_shift = valve_state_idx_shift + n_valve_state_sensors
-        tank_volume_idx_shift = pump_state_idx_shift + n_pump_state_sensors
+        pump_efficiency_idx_shift = pump_state_idx_shift + n_pump_state_sensors
+        pump_energyconsumption_idx_shift = pump_efficiency_idx_shift + n_pump_efficiency_sensors
+        tank_volume_idx_shift = pump_energyconsumption_idx_shift + n_pump_energyconsumption_sensors
         bulk_species_node_idx_shift = tank_volume_idx_shift + n_tank_volume_sensors
         bulk_species_link_idx_shift = bulk_species_node_idx_shift + n_bulk_species_node_sensors
         surface_species_idx_shift = bulk_species_link_idx_shift + n_bulk_species_link_sensors
@@ -1103,6 +1178,11 @@ class SensorConfig(JsonSerializable):
                                                             valve_state_idx_shift),
                    "pump_state": __build_sensors_id_to_idx(self.__pump_state_sensors,
                                                            pump_state_idx_shift),
+                   "pump_efficiency": __build_sensors_id_to_idx(self.__pump_efficiency_sensors,
+                                                                pump_efficiency_idx_shift),
+                   "pump_energyconsumption":
+                   __build_sensors_id_to_idx(self.__pump_energyconsumption_sensors,
+                                             pump_energyconsumption_idx_shift),
                    "tank_volume": __build_sensors_id_to_idx(self.__tank_volume_sensors,
                                                             tank_volume_idx_shift),
                    "bulk_species_node":
@@ -1526,6 +1606,58 @@ class SensorConfig(JsonSerializable):
 
         self.__compute_indices()
 
+    @property
+    def pump_energyconsumption_sensors(self) -> list[str]:
+        """
+        Gets all pump energy consumption sensors
+        (i.e. IDs of pumps at which the energy consumption is monitored).
+
+        Returns
+        -------
+        `list[str]`
+            All pump IDs with an energy consumption sensor.
+        """
+        return self.__pump_energyconsumption_sensors.copy()
+
+    @pump_energyconsumption_sensors.setter
+    def pump_energyconsumption_sensors(self, pump_energyconsumption_sensors: list[str]) -> None:
+        if not isinstance(pump_energyconsumption_sensors, list):
+            raise TypeError("'pump_energyconsumption_sensors' must be an instance of 'list[str]' " +
+                            f"but not of '{type(pump_energyconsumption_sensors)}'")
+        if any(link not in self.__pumps for link in pump_energyconsumption_sensors):
+            raise ValueError("Each item in 'pump_energyconsumption_sensors' must be in 'pumps' " +
+                             "-- cannot place a sensor at a non-existing pump.")
+
+        self.__pump_energyconsumption_sensors = pump_energyconsumption_sensors
+
+        self.__compute_indices()
+
+    @property
+    def pump_efficiency_sensors(self) -> list[str]:
+        """
+        Gets all pump efficiency sensors
+        (i.e. IDs of pumps at which the efficiency is monitored).
+
+        Returns
+        -------
+        `list[str]`
+            All pump IDs with an efficiency sensor.
+        """
+        return self.__pump_efficiency_sensors.copy()
+
+    @pump_efficiency_sensors.setter
+    def pump_efficiency_sensors(self, pump_efficiency_sensors: list[str]) -> None:
+        if not isinstance(pump_efficiency_sensors, list):
+            raise TypeError("'pump_efficiency_sensors' must be an instance of 'list[str]' " +
+                            f"but not of '{type(pump_efficiency_sensors)}'")
+        if any(link not in self.__pumps for link in pump_efficiency_sensors):
+            raise ValueError("Each item in 'pump_efficiency_sensors' must be in 'pumps' " +
+                             "-- cannot place a sensor at a non-existing pump.")
+
+        self.__pump_efficiency_sensors = pump_efficiency_sensors
+
+        self.__compute_indices()
+
     @property
     def tank_volume_sensors(self) -> list[str]:
         """
@@ -1670,6 +1802,10 @@ class SensorConfig(JsonSerializable):
             r["valve_state"] = self.__valve_state_sensors
         if self.__pump_state_sensors != []:
             r["pump_state"] = self.__pump_state_sensors
+        if self.__pump_efficiency_sensors != []:
+            r["pump_efficiency"] = self.__pump_efficiency_sensors
+        if self.__pump_energyconsumption_sensors != []:
+            r["pump_energyconsumption"] = self.__pump_energyconsumption_sensors
         if self.__quality_node_sensors != []:
             r["node_quality"] = self.__quality_node_sensors
         if self.__quality_link_sensors != []:
@@ -1695,6 +1831,8 @@ class SensorConfig(JsonSerializable):
                 "quality_link_sensors": self.__quality_link_sensors,
                 "valve_state_sensors": self.__valve_state_sensors,
                 "pump_state_sensors": self.__pump_state_sensors,
+                "pump_efficiency_sensors": self.__pump_efficiency_sensors,
+                "pump_energyconsumption_sensors": self.__pump_energyconsumption_sensors,
                 "tank_volume_sensors": self.__tank_volume_sensors,
                 "bulk_species_node_sensors": self.__bulk_species_node_sensors,
                 "bulk_species_link_sensors": self.__bulk_species_link_sensors,
@@ -1730,6 +1868,8 @@ class SensorConfig(JsonSerializable):
             and self.__quality_link_sensors == other.quality_link_sensors \
             and self.__valve_state_sensors == other.valve_state_sensors \
             and self.__pump_state_sensors == other.pump_state_sensors \
+            and self.__pump_efficiency_sensors == other.pump_efficiency_sensors \
+            and self.__pump_energyconsumption_sensors == other.pump_energyconsumption_sensors \
             and self.__tank_volume_sensors == other.tank_volume_sensors \
             and self.__bulk_species_node_sensors == other.bulk_species_node_sensors \
             and self.__bulk_species_link_sensors == other.bulk_species_link_sensors \
@@ -1762,6 +1902,8 @@ class SensorConfig(JsonSerializable):
             f"quality_link_sensors: {self.__quality_link_sensors} " +\
             f"valve_state_sensors: {self.__valve_state_sensors} " +\
             f"pump_state_sensors: {self.__pump_state_sensors} " +\
+            f"pump_efficiency_sensors: {self.__pump_efficiency_sensors} " +\
+            f"pump_energyconsumption_sensors: {self.__pump_energyconsumption_sensors} " +\
             f"tank_volume_sensors: {self.__tank_volume_sensors} " +\
             f"bulk_species_node_sensors: {self.__bulk_species_node_sensors} " +\
             f"bulk_species_link_sensors: {self.__bulk_species_link_sensors} " +\
@@ -1776,7 +1918,8 @@ class SensorConfig(JsonSerializable):
 
     def compute_readings(self, pressures: np.ndarray, flows: np.ndarray, demands: np.ndarray,
                          nodes_quality: np.ndarray, links_quality: np.ndarray,
-                         pumps_state: np.ndarray, valves_state: np.ndarray,
+                         pumps_state: np.ndarray, pumps_efficiency: np.ndarray,
+                         pumps_energyconsumption: np.ndarray, valves_state: np.ndarray,
                          tanks_volume: np.ndarray, bulk_species_node_concentrations: np.ndarray,
                          bulk_species_link_concentrations: np.ndarray,
                          surface_species_concentrations: np.ndarray) -> np.ndarray:
@@ -1798,6 +1941,10 @@ class SensorConfig(JsonSerializable):
             Quality values at all links/pipes.
         pumps_state : `numpy.ndarray`
             States of all pumps.
+        pumps_efficiency : `numpy.ndarray`
+            Efficiency of all pumps.
+        pumps_energyconsumption : `numpy.ndarray`
+            Energy consumption of all pumps.
         valves_state : `numpy.ndarray`
             States of all valves.
         tanks_volume : `numpy.ndarray`
@@ -1874,6 +2021,20 @@ class SensorConfig(JsonSerializable):
                 raise ValueError("Pump states readings requested " +
                                  "but no pump state data is given")
 
+        if pumps_efficiency is not None:
+            data.append(pumps_efficiency[:, self.__pump_efficiency_idx])
+        else:
+            if len(self.__pump_efficiency_sensors) != 0:
+                raise ValueError("Pump efficiency readings requested " +
+                                 "but no pump efficiency data is given")
+
+        if pumps_energyconsumption is not None:
+            data.append(pumps_energyconsumption[:, self.__pump_energyconsumption_idx])
+        else:
+            if len(self.__pump_energyconsumption_sensors) != 0:
+                raise ValueError("Pump energy consumption readings requested " +
+                                 "but no pump energy consumption data is given")
+
         if tanks_volume is not None:
             data.append(tanks_volume[:, self.__tank_volume_idx])
         else:
@@ -1913,7 +2074,9 @@ class SensorConfig(JsonSerializable):
     def get_index_of_reading(self, pressure_sensor: str = None, flow_sensor: str = None,
                              demand_sensor: str = None, node_quality_sensor: str = None,
                              link_quality_sensor: str = None, valve_state_sensor: str = None,
-                             pump_state_sensor: str = None, tank_volume_sensor: str = None,
+                             pump_state_sensor: str = None, pump_efficiency_sensor: str = None,
+                             pump_energyconsumption_sensor: str = None,
+                             tank_volume_sensor: str = None,
                              bulk_species_node_sensor: tuple[str, str] = None,
                              bulk_species_link_sensor: tuple[str, str] = None,
                              surface_species_sensor: tuple[str, str] = None) -> int:
@@ -1943,6 +2106,10 @@ class SensorConfig(JsonSerializable):
             ID of the state sensor (at a valve).
         pump_state_sensor : `str`
             ID of the state sensor (at a pump).
+        pump_efficiency_sensor : `str`
+            ID of the efficiency sensor (at a pump).
+        pump_energyconsumption_sensor : `str`
+            ID of the energy consumption sensor (at a pump).
         tank_volume_sensor : `str`
             ID of the water volume sensor (at a tank)
         bulk_species_node_sensor : `tuple[str, str]`
@@ -1966,6 +2133,10 @@ class SensorConfig(JsonSerializable):
             return self.__sensors_id_to_idx["valve_state"][valve_state_sensor]
         elif pump_state_sensor is not None:
             return self.__sensors_id_to_idx["pump_state"][pump_state_sensor]
+        elif pump_efficiency_sensor is not None:
+            return self.__sensors_id_to_idx["pump_efficiency"][pump_efficiency_sensor]
+        elif pump_energyconsumption_sensor is not None:
+            return self.__sensors_id_to_idx["pump_energyconsumption"][pump_energyconsumption_sensor]
         elif tank_volume_sensor is not None:
             return self.__sensors_id_to_idx["tank_volume"][tank_volume_sensor]
         elif surface_species_sensor is not None:

epyt_flow/topology.py

@@ -188,6 +188,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
         """
         return [node_id for node_id, _ in self.__nodes]
 
+    def get_number_of_nodes(self) -> int:
+        """
+        Returns the number of nodes.
+
+        Returns
+        -------
+        `int`
+            Number of nodes.
+        """
+        return len(self.get_all_nodes())
+
     def get_all_links(self) -> list[tuple[str, tuple[str, str]]]:
         """
         Gets a list of all links/pipes (incl. their end points).
@@ -199,6 +210,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
         """
         return [(link_id, end_points) for link_id, end_points, _ in self.__links]
 
+    def get_number_of_links(self) -> int:
+        """
+        Returns the number of links.
+
+        Returns
+        -------
+        `int`
+            Number of links.
+        """
+        return len(self.get_all_links())
+
     def get_all_junctions(self) -> list[str]:
         """
         Gets all junctions -- i.e. nodes that are not tanks or reservoirs.
@@ -216,6 +238,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
 
         return r
 
+    def get_number_of_junctions(self) -> int:
+        """
+        Returns the number of junctions.
+
+        Returns
+        -------
+        `int`
+            Number of junctions.
+        """
+        return len(self.get_all_junctions())
+
     def get_all_tanks(self) -> list[str]:
         """
         Gets all tanks -- i.e. nodes that are not junctions or reservoirs.
@@ -233,6 +266,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
 
         return r
 
+    def get_number_of_tanks(self) -> int:
+        """
+        Returns the number of tanks.
+
+        Returns
+        -------
+        `int`
+            Number of tanks.
+        """
+        return len(self.get_all_tanks())
+
     def get_all_reservoirs(self) -> list[str]:
         """
         Gets all reservoirs -- i.e. nodes that are not junctions or tanks.
@@ -250,6 +294,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
 
         return r
 
+    def get_number_of_reservoirs(self) -> int:
+        """
+        Returns the number of reservoirs.
+
+        Returns
+        -------
+        `int`
+            Number of reservoirs.
+        """
+        return len(self.get_all_reservoirs())
+
     def get_all_pipes(self) -> list[tuple[str, tuple[str, str]]]:
         """
         Gets all pipes -- i.e. links that not valves or pumps.
@@ -269,6 +324,17 @@ class NetworkTopology(nx.Graph, JsonSerializable):
 
         return r
 
+    def get_number_of_pipes(self) -> int:
+        """
+        Returns the number of pipes.
+
+        Returns
+        -------
+        `int`
+            Number of pipes.
+        """
+        return len(self.get_all_pipes())
+
     def get_all_pumps(self) -> list[str]:
         """
         Gets the IDs of all pumps.
@@ -278,7 +344,18 @@ class NetworkTopology(nx.Graph, JsonSerializable):
         `list[str]`
             Pump IDs.
         """
-        return self.__pumps.keys()
+        return list(self.__pumps.keys())
+
+    def get_number_of_pumps(self) -> int:
+        """
+        Returns the number of pumps.
+
+        Returns
+        -------
+        `int`
+            Number of pumps.
+        """
+        return len(self.get_all_pumps())
 
     def get_all_valves(self) -> list[str]:
         """
@@ -289,7 +366,18 @@ class NetworkTopology(nx.Graph, JsonSerializable):
         `list[str]`
             Valve IDs.
         """
-        return self.__valves.keys()
+        return list(self.__valves.keys())
+
+    def get_number_of_valves(self) -> int:
+        """
+        Returns the number of valves.
+
+        Returns
+        -------
+        `int`
+            Number of valves.
+        """
+        return len(self.get_all_valves())
 
     def get_node_info(self, node_id: str) -> dict:
         """
@@ -419,11 +507,11 @@ class NetworkTopology(nx.Graph, JsonSerializable):
 
         return super().__eq__(other) and \
             self.get_all_nodes() == other.get_all_nodes() \
-            and all(link_a[0] == link_b[0] and all(link_a[1] == link_b[1])
+            and all(link_a[0] == link_b[0] and link_a[1] == link_b[1]
                     for link_a, link_b in zip(self.get_all_links(), other.get_all_links())) \
             and self.__units == other.units \
-            and self.__pumps == other.pumps \
-            and self.__valves == other.valves
+            and self.get_all_pumps() == other.get_all_pumps() \
+            and self.get_all_valves() == other.get_all_valves()
 
     def __str__(self) -> str:
         return f"f_inp: {self.name} nodes: {self.__nodes} links: {self.__links} " +\

epyt_flow/uncertainty/uncertainties.py

@@ -334,8 +334,16 @@ class PercentageDeviationUncertainty(UniformUncertainty, JsonSerializable):
         if not 0 < deviation_percentage < 1:
             raise ValueError("'deviation_percentage' must be in (0,1)")
 
+        if "low" in kwds:
+            del kwds["low"]
+        if "high" in kwds:
+            del kwds["high"]
+
         super().__init__(low=1. - deviation_percentage, high=1. + deviation_percentage, **kwds)
 
+    def get_attributes(self) -> dict:
+        return super().get_attributes() | {"deviation_percentage": self.high - 1.}
+
     def apply(self, data: float) -> float:
         data *= np.random.uniform(low=self.low, high=self.high)
 

epyt_flow/utils.py

@@ -68,7 +68,8 @@ def volume_to_level(tank_volume: float, tank_diameter: float) -> float:
 
 
 def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_label: str = None,
-                         y_axis_label: str = None, show: bool = True,
+                         y_axis_label: str = None, y_ticks: tuple[list[float], list[str]] = None,
+                         show: bool = True, save_to_file: str = None,
                          ax: matplotlib.axes.Axes = None) -> matplotlib.axes.Axes:
     """
     Plots a single or multiple time series.
@@ -89,6 +90,10 @@ def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_labe
     y_axis_label : `str`, optional
         Y axis label.
 
+        The default is None.
+    y_ticks: `(list[float], list[str])`, optional
+        Tuple of ticks (numbers) and labels (strings) for the y-axis.
+
         The default is None.
     show : `bool`, optional
         If True, the plot/figure is shown in a window.
@@ -96,6 +101,13 @@ def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_labe
         Only considered when 'ax' is None.
 
         The default is True.
+    save_to_file : `str`, optional
+        File to which the plot is saved.
+
+        If specified, 'show' must be set to False --
+        i.e. a plot can not be shown and saved to a file at the same time!
+
+        The default is None.
     ax : `matplotlib.axes.Axes`, optional
         If not None, 'ax' is used for plotting.
 
@@ -122,8 +134,18 @@ def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_labe
         if not isinstance(y_axis_label, str):
             raise TypeError("'y_axis_label' must be an instance of 'str' " +
                             f"but not of '{type(y_axis_label)}'")
+    if y_ticks is not None:
+        if len(y_ticks) != 2:
+            raise ValueError("'y_ticks' must be a tuple ticks (numbers) and labels (strings)")
     if not isinstance(show, bool):
         raise TypeError(f"'show' must be an instance of 'bool' but not of '{type(show)}'")
+    if save_to_file is not None:
+        if show is True:
+            raise ValueError("'show' must be False if 'save_to_file' is set")
+
+        if not isinstance(save_to_file, str):
+            raise TypeError("'save_to_file' must be an instance of 'str' but not of " +
+                            f"'{type(save_to_file)}'")
     if ax is not None:
         if not isinstance(ax, matplotlib.axes.Axes):
             raise TypeError("ax' must be an instance of 'matplotlib.axes.Axes'" +
@@ -145,9 +167,20 @@ def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_labe
         ax.set_xlabel(x_axis_label)
     if y_axis_label is not None:
         ax.set_ylabel(y_axis_label)
+    if y_ticks is not None:
+        yticks_pos, yticks_labels = y_ticks
+        ax.set_yticks(yticks_pos, labels=yticks_labels)
 
     if show is True and fig is not None:
         plt.show()
+    if save_to_file is not None:
+        folder_path = str(Path(save_to_file).parent.absolute())
+        create_path_if_not_exist(folder_path)
+
+        if fig is None:
+            plt.savefig(save_to_file, bbox_inches='tight')
+        else:
+            fig.savefig(save_to_file, bbox_inches='tight')
 
     return ax
 
@@ -155,7 +188,9 @@ def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_labe
 def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
                                confidence_interval: np.ndarray = None,
                                x_axis_label: str = None, y_axis_label: str = None,
-                               show: bool = True, ax: matplotlib.axes.Axes = None
+                               y_ticks: tuple[list[float], list[str]] = None,
+                               show: bool = True, save_to_file: str = None,
+                               ax: matplotlib.axes.Axes = None
                                ) -> matplotlib.axes.Axes:
     """
     Plots the prediction (e.g. forecast) of *single* time series together with the
@@ -179,6 +214,10 @@ def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
     y_axis_label : `str`, optional
         Y axis label.
 
+        The default is None.
+    y_ticks: `(list[float], list[str])`, optional
+        Tuple of ticks (numbers) and labels (strings) for the y-axis.
+
         The default is None.
     show : `bool`, optional
         If True, the plot/figure is shown in a window.
@@ -186,6 +225,13 @@ def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
         Only considered when 'ax' is None.
 
         The default is True.
+    save_to_file : `str`, optional
+        File to which the plot is saved.
+
+        If specified, 'show' must be set to False --
+        i.e. a plot can not be shown and saved to a file at the same time!
+
+        The default is None.
     ax : `matplotlib.axes.Axes`, optional
         If not None, 'axes' is used for plotting.
 
@@ -216,8 +262,18 @@ def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
         if not isinstance(y_axis_label, str):
             raise TypeError("'y_axis_label' must be an instance of 'str' " +
                             f"but not of '{type(y_axis_label)}'")
+    if y_ticks is not None:
+        if len(y_ticks) != 2:
+            raise ValueError("'y_ticks' must be a tuple ticks (numbers) and labels (strings)")
     if not isinstance(show, bool):
         raise TypeError(f"'show' must be an instance of 'bool' but not of '{type(show)}'")
+    if save_to_file is not None:
+        if show is True:
+            raise ValueError("'show' must be False if 'save_to_file' is set")
+
+        if not isinstance(save_to_file, str):
+            raise TypeError("'save_to_file' must be an instance of 'str' but not of " +
+                            f"'{type(save_to_file)}'")
     if ax is not None:
         if not isinstance(ax, matplotlib.axes.Axes):
             raise TypeError("ax' must be an instance of 'matplotlib.axes.Axes'" +
@@ -240,9 +296,20 @@ def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
         ax.set_xlabel(x_axis_label)
     if y_axis_label is not None:
         ax.set_ylabel(y_axis_label)
+    if y_ticks is not None:
+        yticks_pos, yticks_labels = y_ticks
+        ax.set_yticks(yticks_pos, labels=yticks_labels)
 
     if show is True and fig is not None:
         plt.show()
+    if save_to_file is not None:
+        folder_path = str(Path(save_to_file).parent.absolute())
+        create_path_if_not_exist(folder_path)
+
+        if fig is None:
+            plt.savefig(save_to_file, bbox_inches='tight')
+        else:
+            fig.savefig(save_to_file, bbox_inches='tight')
 
     return ax