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

epyt_flow/VERSION

@@ -1 +1 @@
-0.6.0
+0.7.0

epyt_flow/metrics.py

@@ -3,12 +3,74 @@ This module provides different metrics for evaluation.
 """
 import numpy as np
 from sklearn.metrics import roc_auc_score as skelarn_roc_auc_score, f1_score as skelarn_f1_scpre, \
-    mean_absolute_error
+    mean_absolute_error, root_mean_squared_error, r2_score as sklearn_r2_score
 
 
-def running_mse(y_pred: np.ndarray, y: np.ndarray):
+def r2_score(y_pred: np.ndarray, y: np.ndarray) -> float:
     """
-    Computes the running Mean Squared Error (MSE).
+    Computes the R^2 score (also called the coefficient of determination).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `float`
+        R^2 score.
+    """
+    return sklearn_r2_score(y, y_pred)
+
+
+def running_r2_score(y_pred: np.ndarray, y: np.ndarray) -> list[float]:
+    """
+    Computes and returns the running R^2 score -- i.e. the R^2 score for every point in time.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `list[float]`
+        The running R^2 score.
+    """
+    r = []
+
+    for t in range(2, len(y_pred)):
+        r.append(r2_score(y_pred[:t], y[:t]))
+
+    return r
+
+
+def mean_squared_error(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the Mean Squared Error (MSE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `float`
+        MSE.
+    """
+    return root_mean_squared_error(y, y_pred)**2
+
+
+def running_mse(y_pred: np.ndarray, y: np.ndarray) -> list[float]:
+    """
+    Computes the running Mean Squared Error (MSE) -- i.e. the MSE for every point in time.
 
     Parameters
     ----------
@@ -39,7 +101,7 @@ def running_mse(y_pred: np.ndarray, y: np.ndarray):
     r_mse = list(esq for esq in e_sq)
 
     for i in range(1, len(y)):
-        r_mse[i] = ((i * r_mse[i - 1]) / (i + 1)) + (r_mse[i] / (i + 1))
+        r_mse[i] = float((i * r_mse[i - 1]) / (i + 1)) + (r_mse[i] / (i + 1))
 
     return r_mse
 

epyt_flow/serialization.py

@@ -309,6 +309,39 @@ class JsonSerializable(Serializable):
         """
         return my_load_from_json(data)
 
+    @staticmethod
+    def load_from_json_file(f_in: str) -> Any:
+        """
+        Deserializes an instance of this class from a JSON file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the JSON file from which to deserialize the object.
+
+        Returns
+        -------
+        `Any`
+            Deserialized object.
+        """
+        with open(f_in, "r", encoding="utf-8") as f:
+            return my_load_from_json(f.read())
+
+    def save_to_json_file(self, f_out: str) -> None:
+        """
+        Serializes this instance and stores it in a JSON file.
+
+        Parameters
+        ----------
+        f_in : `str`
+            Path to the JSON file where this serialized object will be stored.
+        """
+        if not f_out.endswith(self.file_ext()):
+            f_out += self.file_ext()
+
+        with open(f_out, "w", encoding="utf-8") as f:
+            f.write(self.to_json())
+
 
 def load(data: Union[bytes, BufferedIOBase]) -> Any:
     """

epyt_flow/simulation/scada/scada_data.py

@@ -2150,7 +2150,7 @@ class ScadaData(Serializable):
                 raise TypeError("'bulk_species_sensor_locations' must be an instance of 'dict'" +
                                 f" but not of '{type(bulk_species_sensor_locations)}'")
             for species_id in bulk_species_sensor_locations:
-                if species_id not in self.__sensor_config.bulk_species_sensors:
+                if species_id not in self.__sensor_config.bulk_species_node_sensors:
                     raise ValueError(f"Species '{species_id}' is not included in the " +
                                      "sensor configuration")
 

epyt_flow/simulation/scenario_simulator.py

@@ -94,6 +94,7 @@ class ScenarioSimulator():
         self.__controls = []
         self.__system_events = []
         self.__sensor_reading_events = []
+        self.__running_simulation = False
 
         custom_epanet_lib = None
         custom_epanetmsx_lib = None
@@ -150,7 +151,8 @@ class ScenarioSimulator():
 
             self.epanet_api = epanet(my_f_inp_in, ph=self.__f_msx_in is None,
                                      customlib=custom_epanet_lib, loadfile=True,
-                                     display_msg=epanet_verbose)
+                                     display_msg=epanet_verbose,
+                                     display_warnings=False)
 
             if self.__f_msx_in is not None:
                 self.epanet_api.loadMSXFile(my_f_msx_in, customMSXlib=custom_epanetmsx_lib)
@@ -432,7 +434,7 @@ class ScenarioSimulator():
         new_sensor_config.quality_node_sensors = self.__sensor_config.quality_node_sensors
         new_sensor_config.quality_link_sensors = self.__sensor_config.quality_link_sensors
         new_sensor_config.pump_state_sensors = self.__sensor_config.pump_state_sensors
-        new_sensor_config.pump_efficiecy_sensors = self.__sensor_config.pump_efficiency_sensors
+        new_sensor_config.pump_efficiency_sensors = self.__sensor_config.pump_efficiency_sensors
         new_sensor_config.pump_energyconsumption_sensors = self.__sensor_config.\
             pump_energyconsumption_sensors
         new_sensor_config.valve_state_sensors = self.__sensor_config.valve_state_sensors
@@ -456,8 +458,6 @@ class ScenarioSimulator():
 
         if self.__my_f_inp_in is not None:
             shutil.rmtree(pathlib.Path(self.__my_f_inp_in).parent)
-        if self.__my_f_msx_in is not None:
-            shutil.rmtree(pathlib.Path(self.__my_f_msx_in).parent)
 
     def __enter__(self):
         return self
@@ -744,6 +744,19 @@ class ScenarioSimulator():
                 "units": qualityunit_to_id(qual_info.QualityChemUnits),
                 "trace_node_id": qual_info.TraceNode}
 
+    def get_reporting_time_step(self) -> int:
+        """
+        Gets the reporting time steps -- i.e. time steps at which sensor readings are provided.
+
+        Is always a multiple of the hydraulic time step.
+
+        Returns
+        -------
+        `int`
+            Reporting time steps in seconds.
+        """
+        return self.epanet_api.getTimeReportingStep()
+
     def get_scenario_config(self) -> ScenarioConfig:
         """
         Gets the configuration of this scenario -- i.e. all information & elements
@@ -758,7 +771,7 @@ class ScenarioSimulator():
 
         general_params = {"hydraulic_time_step": self.get_hydraulic_time_step(),
                           "quality_time_step": self.get_quality_time_step(),
-                          "reporting_time_step": self.epanet_api.getTimeReportingStep(),
+                          "reporting_time_step": self.get_reporting_time_step(),
                           "simulation_duration": self.get_simulation_duration(),
                           "flow_units_id": self.get_flow_units(),
                           "quality_model": self.get_quality_model(),
@@ -874,6 +887,9 @@ class ScenarioSimulator():
         """
         Randomizes all demand patterns.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         # Get all demand patterns
@@ -996,6 +1012,9 @@ class ScenarioSimulator():
         event : :class:`~epyt_flow.simulation.events.system_event.SystemEvent`
             System event.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(event, SystemEvent):
@@ -1015,6 +1034,9 @@ class ScenarioSimulator():
         sensor_fault_event : :class:`~epyt_flow.simulation.events.sensor_faults.SensorFault`
             Sensor fault specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         sensor_fault_event.validate(self.__sensor_config)
@@ -1035,6 +1057,9 @@ class ScenarioSimulator():
         sensor_reading_attack : :class:`~epyt_flow.simulation.events.sensor_reading_attack.SensorReadingAttack`
             Sensor fault specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         sensor_reading_attack.validate(self.__sensor_config)
@@ -1055,6 +1080,9 @@ class ScenarioSimulator():
         event : :class:`~epyt_flow.simulation.events.sensor_reading_event.SensorReadingEvent`
             Sensor reading event.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not add events when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         event.validate(self.__sensor_config)
@@ -1134,11 +1162,21 @@ class ScenarioSimulator():
         """
         self.set_sensors(SENSOR_TYPE_NODE_PRESSURE, sensor_locations)
 
-    def place_pressure_sensors_everywhere(self) -> None:
+    def place_pressure_sensors_everywhere(self, junctions_only: bool = False) -> None:
         """
         Places a pressure sensor at every node in the network.
+
+        Parameters
+        ----------
+        junctions_only : `bool`, optional
+            If True, pressure sensors are only placed at junctions but not at tanks and reservoirs.
+
+            The default is False.
         """
-        self.set_pressure_sensors(self.__sensor_config.nodes)
+        if junctions_only is True:
+            self.set_pressure_sensors(self.epanet_api.getNodeJunctionNameID())
+        else:
+            self.set_pressure_sensors(self.__sensor_config.nodes)
 
     def set_flow_sensors(self, sensor_locations: list[str]) -> None:
         """
@@ -1442,6 +1480,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Quality simulation results as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         if self.__f_msx_in is None:
             raise ValueError("No .msx file specified")
 
@@ -1506,6 +1547,9 @@ class ScenarioSimulator():
             Generator containing the current EPANET-MSX simulation results as SCADA data
             (i.e. species concentrations).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         if self.__f_msx_in is None:
             raise ValueError("No .msx file specified")
 
@@ -1522,6 +1566,8 @@ class ScenarioSimulator():
 
         self.epanet_api.initializeMSXQualityAnalysis(ToolkitConstants.EN_NOSAVE)
 
+        self.__running_simulation = True
+
         bulk_species_idx = self.epanet_api.getMSXSpeciesIndex(self.__sensor_config.bulk_species)
         surface_species_idx = self.epanet_api.getMSXSpeciesIndex(
             self.__sensor_config.surface_species)
@@ -1614,6 +1660,7 @@ class ScenarioSimulator():
 
         # Run step-by-step simulation
         tleft = 1
+        total_time = 0
         while tleft > 0:
             if support_abort is True:  # Can the simulation be aborted? If so, handle it.
                 abort = yield
@@ -1656,6 +1703,8 @@ class ScenarioSimulator():
                                         sensor_noise=self.__sensor_noise,
                                         frozen_sensor_config=frozen_sensor_config)
 
+        self.__running_simulation = False
+
     def run_basic_quality_simulation(self, hyd_file_in: str, verbose: bool = False,
                                      frozen_sensor_config: bool = False) -> ScadaData:
         """
@@ -1681,6 +1730,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Quality simulation results as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         result = None
 
         # Run simulation step-by-step
@@ -1741,6 +1793,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Generator with the current simulation results/states as SCADA data.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         requested_time_step = self.epanet_api.getTimeHydraulicStep()
         reporting_time_start = self.epanet_api.getTimeReportingStart()
         reporting_time_step = self.epanet_api.getTimeReportingStep()
@@ -1834,6 +1889,9 @@ class ScenarioSimulator():
         :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
             Simulation results as SCADA data (i.e. sensor readings).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         self.__adapt_to_network_changes()
 
         result = None
@@ -1928,10 +1986,15 @@ class ScenarioSimulator():
             Generator with the current simulation results/states as SCADA data
             (i.e. sensor readings).
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("A simulation is already running.")
+
         self.__adapt_to_network_changes()
 
         self.__prepare_simulation()
 
+        self.__running_simulation = True
+
         self.epanet_api.openHydraulicAnalysis()
         self.epanet_api.openQualityAnalysis()
         self.epanet_api.initializeHydraulicAnalysis(ToolkitConstants.EN_SAVE)
@@ -2041,9 +2104,12 @@ class ScenarioSimulator():
             self.epanet_api.closeQualityAnalysis()
             self.epanet_api.closeHydraulicAnalysis()
 
+            self.__running_simulation = False
+
             if hyd_export is not None:
                 self.epanet_api.saveHydraulicFile(hyd_export)
         except Exception as ex:
+            self.__running_simulation = False
             raise ex
 
     def set_model_uncertainty(self, model_uncertainty: ModelUncertainty) -> None:
@@ -2055,6 +2121,9 @@ class ScenarioSimulator():
         model_uncertainty : :class:`~epyt_flow.uncertainty.model_uncertainty.ModelUncertainty`
             Model uncertainty specifications.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not set uncertainties when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(model_uncertainty, ModelUncertainty):
@@ -2073,6 +2142,9 @@ class ScenarioSimulator():
         sensor_noise : :class:`~epyt_flow.uncertainties.sensor_noise.SensorNoise`
             Sensor noise specification.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not set sensor noise when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if not isinstance(sensor_noise, SensorNoise):
@@ -2155,6 +2227,9 @@ class ScenarioSimulator():
 
             The default is None.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if flow_units_id is not None:
@@ -2277,6 +2352,9 @@ class ScenarioSimulator():
         Sets water age analysis -- i.e. estimates the water age (in hours) at
         all places in the network.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         self.__warn_if_quality_set()
@@ -2305,6 +2383,9 @@ class ScenarioSimulator():
 
             The default is MASS_UNIT_MG.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         self.__warn_if_quality_set()
@@ -2349,6 +2430,9 @@ class ScenarioSimulator():
 
             The default is 1.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if self.epanet_api.getQualityInfo().QualityCode != ToolkitConstants.EN_CHEM:
@@ -2385,6 +2469,9 @@ class ScenarioSimulator():
         trace_node_id : `str`
             ID of the node traced in the source tracing analysis.
         """
+        if self.__running_simulation is True:
+            raise RuntimeError("Can not change general parameters when simulation is running.")
+
         self.__adapt_to_network_changes()
 
         if trace_node_id not in self.__sensor_config.nodes:

epyt_flow/simulation/sensor_config.py

@@ -284,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]
 
 

epyt_flow/topology.py

@@ -507,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
 

{epyt_flow-0.6.0.dist-info → epyt_flow-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: epyt-flow
-Version: 0.6.0
+Version: 0.7.0
 Summary: EPyT-Flow -- EPANET Python Toolkit - Flow
 Author-email: André Artelt <aartelt@techfak.uni-bielefeld.de>, "Marios S. Kyriakou" <kiriakou.marios@ucy.ac.cy>, "Stelios G. Vrachimis" <vrachimis.stelios@ucy.ac.cy>
 License: MIT License
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: epyt >=1.1.9
+Requires-Dist: epyt >=1.2.0
 Requires-Dist: requests >=2.31.0
 Requires-Dist: scipy >=1.11.4
 Requires-Dist: u-msgpack-python >=2.8.0
@@ -121,7 +121,7 @@ pip install .
 ```python
 from epyt_flow.data.benchmarks import load_leakdb_scenarios
 from epyt_flow.simulation import ScenarioSimulator
-from epyt_flow.utils import to_seconds
+from epyt_flow.utils import to_seconds, plot_timeseries_data
 
 
 if __name__ == "__main__":
@@ -142,14 +142,49 @@ if __name__ == "__main__":
         # Run entire simulation
         scada_data = sim.run_simulation()
 
-        # Show sensor readings over the entire simulation
+        # Print & plot sensor readings over the entire simulation
         print(f"Pressure readings: {scada_data.get_data_pressures()}")
+        plot_timeseries_data(scada_data.get_data_pressures().T,
+                             labels=[f"Node {n_id}" for n_id in
+                                     scada_data.sensor_config.pressure_sensors],
+                             x_axis_label="Time (30min steps)",
+                             y_axis_label="Pressure in $m$")
+
         print(f"Flow readings: {scada_data.get_data_flows()}")
+        plot_timeseries_data(scada_data.get_data_flows().T,
+                             x_axis_label="Time (30min steps)",
+                             y_axis_label="Flow rate in $m^3/h$")
 ```
+### Generated plots
+
+<div>
+    <img src="https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_pressure.png?raw=true" width="49%"/>
+    <img src="https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_flow.png?raw=true" width="49%"/>
+</div>
 
 ## Documentation
 
-Documentation is available on readthedocs:[https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)
+Documentation is available on readthedocs: [https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)
+
+## How to Get Started?
+
+EPyT-Flow is accompanied by an extensive documentation
+[https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)
+(including many [examples](https://epyt-flow.readthedocs.io/en/stable/#examples)).
+
+If you are new to water distribution networks, we recommend first to read the chapter on
+[Modeling of Water Distribution Networks](https://epyt-flow.readthedocs.io/en/stable/tut.intro.html).
+You might also want to check out some lecture notes on
+[Smart Water Systems](https://github.com/KIOS-Research/ece808-smart-water-systems).
+
+If you are already familiar with WDNs (and software such as EPANET), we recommend checking out
+our [WDSA CCWI 2024 tutorial](https://github.com/WaterFutures/EPyT-and-EPyT-Flow-Tutorial) which
+not only teaches you how to use EPyT and EPyT-Flow but also contains some examples of applying
+Machine Learning in WDNs.
+Besides that, you can read in-depth about the different functionalities of EPyT-Flow in the
+[In-depth Tutorial](https://epyt-flow.readthedocs.io/en/stable/tutorial.html) of the documentation --
+we recommend reading the chapters in the order in which they are presented;
+you might decide to skip some of the last chapters if their content is not relevant to you.
 
 ## License
 
@@ -170,6 +205,14 @@ If you use this software, please cite it as follows:
     }
 ```
 
+## How to get Support?
+
+If you come across any bug or need assistance please feel free to open a new
+[issue](https://github.com/WaterFutures/EPyT-Flow/issues/)
+if non of the existing issues answers your questions.
+
 ## How to Contribute?
 
-Contributions (e.g. creating issues, pull-requests, etc.) are welcome -- please make sure to read the [code of conduct](CODE_OF_CONDUCT.md) and follow the [developers' guidelines](DEVELOPERS.md).
+Contributions (e.g. creating issues, pull-requests, etc.) are welcome --
+please make sure to read the [code of conduct](CODE_OF_CONDUCT.md) and
+follow the [developers' guidelines](DEVELOPERS.md).

{epyt_flow-0.6.0.dist-info → epyt_flow-0.7.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-epyt_flow/VERSION,sha256=l6XW5UCmEg0Jw53bZn4Ojiusf8wv_vgTuC4I_WA2W84,6
+epyt_flow/VERSION,sha256=ln2a-xATRmZxZvLnboGRC8GQSI19QdUMoAcunZLwDjI,6
 epyt_flow/__init__.py,sha256=KNDiPWiHdB9a5ZF1ipjA1uoq61TwU2ThjaStpvSLBtY,1742
-epyt_flow/metrics.py,sha256=kvt42pzZrUR9PSlCyK4uq5kj6UlYHkt7OcCjLnI1RQE,12883
-epyt_flow/serialization.py,sha256=YhqDFZ7FLLcYOPnhOQdS0K8uyqM6bIXOkKDzGJQ-d3o,13075
-epyt_flow/topology.py,sha256=pWG3Cq48Kq-mql-Lg3HUwvj5BGN0SrySa_OfDYNcGxg,25244
-epyt_flow/utils.py,sha256=AB2MuknQ_16UE-URQe1WShIS7dmSyFwZYVHxMVT539k,12379
+epyt_flow/metrics.py,sha256=W-dolnrmWfoanyvg-knoe2QMUtFwV1xODp4D4EwsQ00,14261
+epyt_flow/serialization.py,sha256=ltWcLiTw62s0KG2DSgkQBkn6CCkxy9soDGq_ENohkrI,13998
+epyt_flow/topology.py,sha256=8gqgJrKxw0zY69sIKo4NxrQAoXHP1Ni00U2DV09vR6g,25275
+epyt_flow/utils.py,sha256=GJDktl7ciUPJxqMg9f2nCnQf6DosNd2mxeKOy7omkik,15196
 epyt_flow/EPANET/compile_linux.sh,sha256=wcrDyiB8NkivmaC-X9FI2WxhY3IJqDLiyIbVTv2XEPY,489
 epyt_flow/EPANET/compile_macos.sh,sha256=1K33-bPdgr01EIf87YUvmOFHXyOkBWI6mKXQ8x1Hzmo,504
 epyt_flow/EPANET/EPANET/SRC_engines/AUTHORS,sha256=yie5yAsEEPY0984PmkSRUdqEU9rVvRSGGWmjxdwCYMU,925
@@ -112,9 +112,9 @@ epyt_flow/rest_api/scenario/uncertainty_handlers.py,sha256=uuu6AP11ZZUp2P3Dnukjg
 epyt_flow/simulation/__init__.py,sha256=VGGJqJRUoXZjKJ0-m6KPp3JQqD_1TFW0pofLgkwZJ8M,164
 epyt_flow/simulation/parallel_simulation.py,sha256=VmC7xemjxRB_N0fx1AAQ7ux82tnyTi7jk7jfFpeg7gM,6523
 epyt_flow/simulation/scenario_config.py,sha256=NyadeCihpR4bpsWVPj7J-1DU2w1CEN0pAo2yh0t8Xkg,26751
-epyt_flow/simulation/scenario_simulator.py,sha256=_DINJgPVBdKds6hq0w4zJuCIoQVBnkqBwU04KIi5egY,101950
+epyt_flow/simulation/scenario_simulator.py,sha256=VYYUlpukvD9vLs8zmZWTb7-HCrmQlydxw52JyHiWKzE,105251
 epyt_flow/simulation/scenario_visualizer.py,sha256=fpj67zl69q-byg7Oxocqhmu1S3P7B3ROCkSYzWyM--0,2187
-epyt_flow/simulation/sensor_config.py,sha256=HSNT8BAfWo0G4k5PXI8BhWDl8YzpS8CYJqlv0pmbPZc,90921
+epyt_flow/simulation/sensor_config.py,sha256=rX13QQv-OBoybCSJZR0gBsGP0GejBAuJ8BRDULKMIDU,90946
 epyt_flow/simulation/events/__init__.py,sha256=tIdqzs7_Cus4X2kbZG4Jl2zs-zsk_4rnajFOCvL0zlI,185
 epyt_flow/simulation/events/actuator_events.py,sha256=2_MPYbYO9As6fMkm5Oy9pjSB9kCvFuKpGu8ykYDAydg,7903
 epyt_flow/simulation/events/event.py,sha256=kARPV20XCAl6zxnJwI9U7ICtZUPACO_rgAmtHm1mGCs,2603
@@ -125,15 +125,15 @@ epyt_flow/simulation/events/sensor_reading_event.py,sha256=rQ-CmdpSUyZzDFYwNUGH2
 epyt_flow/simulation/events/system_event.py,sha256=0KI2iaAaOyC9Y-FIfFVazeKT_4ORQRp26gWyMBUu_3c,2396
 epyt_flow/simulation/scada/__init__.py,sha256=ZFAxJVqwEVsgiyFilFetnb13gPhZg1JEOPWYvKIJT4c,90
 epyt_flow/simulation/scada/advanced_control.py,sha256=5h7dmSMcNlTE7TMZa8gQVnOCGMf7uZy60r9aOfKDxMc,4487
-epyt_flow/simulation/scada/scada_data.py,sha256=YBgVfs2L85XQxHRcC4-X-yTudB2E8p2oYCxqazPrI9k,110586
+epyt_flow/simulation/scada/scada_data.py,sha256=SlJEcAB06JNCZBl0IO8nv-axamcvznzUAg5SwCdjc2U,110591
 epyt_flow/simulation/scada/scada_data_export.py,sha256=0BwDgV-5qZx17wIyWQ8Nl2TPgho3mBI49027RDq8sDA,11217
 epyt_flow/uncertainty/__init__.py,sha256=ZRjuJL9rDpWVSdPwObPxFpEmMTcgAl3VmPOsS6cIyGg,89
 epyt_flow/uncertainty/model_uncertainty.py,sha256=-2QT2AffZerKZyZ_w_mmeqYpfBALyPDvV61sCrvcK1o,13966
 epyt_flow/uncertainty/sensor_noise.py,sha256=zJVULxnxVPSSqc6UW0iwZ9O-HGf9dn4CwScPqf4yCY0,2324
-epyt_flow/uncertainty/uncertainties.py,sha256=X-o7GZUC0HELtzpoXIAJaAeYOw35N05TuRoSmStcCpI,17669
+epyt_flow/uncertainty/uncertainties.py,sha256=jzaAwv5--HGc-H4-SwB0s-pAnzhhFuc06IXck7rC5l8,17902
 epyt_flow/uncertainty/utils.py,sha256=gq66c9-QMOxOqI6wgWLyFxjVV0fbG0_8Yzd6mQjNYNo,5315
-epyt_flow-0.6.0.dist-info/LICENSE,sha256=-4hYIY2BLmCkdOv2_PehEwlnMKTCes8_oyIUXjKtkug,1076
-epyt_flow-0.6.0.dist-info/METADATA,sha256=8dlCwOkZghE4xDbbWWQ2dOjMBRGo8m48cZuzhmJ0_ds,7087
-epyt_flow-0.6.0.dist-info/WHEEL,sha256=Wyh-_nZ0DJYolHNn1_hMa4lM7uDedD_RGVwbmTjyItk,91
-epyt_flow-0.6.0.dist-info/top_level.txt,sha256=Wh_kd7TRL8ownCw3Y3dxx-9C0iTSk6wNauv_NX9JcrY,10
-epyt_flow-0.6.0.dist-info/RECORD,,
+epyt_flow-0.7.0.dist-info/LICENSE,sha256=-4hYIY2BLmCkdOv2_PehEwlnMKTCes8_oyIUXjKtkug,1076
+epyt_flow-0.7.0.dist-info/METADATA,sha256=UCqXTyaYY6EEBHf85PKDVH2sFglzFvWK-30vBrGP2mI,9420
+epyt_flow-0.7.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+epyt_flow-0.7.0.dist-info/top_level.txt,sha256=Wh_kd7TRL8ownCw3Y3dxx-9C0iTSk6wNauv_NX9JcrY,10
+epyt_flow-0.7.0.dist-info/RECORD,,

{epyt_flow-0.6.0.dist-info → epyt_flow-0.7.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (71.1.0)
+Generator: setuptools (75.3.0)
 Root-Is-Purelib: true
 Tag: py3-none-any