epyt-flow 0.6.0__tar.gz → 0.7.1__tar.gz

{epyt_flow-0.6.0 → epyt_flow-0.7.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.1
 Name: epyt-flow
-Version: 0.6.0
+Version: 0.7.1
 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
 Project-URL: Homepage, https://github.com/WaterFutures/EPyT-Flow
-Project-URL: Documentation, https://epyt-flow.readthedocs.io/en/latest/
+Project-URL: Documentation, https://epyt-flow.readthedocs.io/en/stable/
 Project-URL: Repository, https://github.com/WaterFutures/EPyT-Flow.git
 Project-URL: Issues, https://github.com/WaterFutures/EPyT-Flow/issues
 Keywords: epanet,water,networks,hydraulics,quality,simulations
@@ -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 → epyt_flow-0.7.1}/README.md

@@ -86,7 +86,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__":
@@ -107,14 +107,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
 
@@ -135,6 +170,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 → epyt_flow-0.7.1}/REQUIREMENTS.txt

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

epyt_flow-0.7.1/epyt_flow/VERSION

@@ -0,0 +1 @@
+0.7.1

{epyt_flow-0.6.0 → epyt_flow-0.7.1}/epyt_flow/data/benchmarks/leakdb.py

@@ -509,6 +509,7 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
         if not os.path.exists(f_inp_in):
             with ScenarioSimulator(f_inp_in=network_config.f_inp_in) as wdn:
                 wdn.set_general_parameters(**general_params)
+                wdn.epanet_api.setTimePatternStep(hydraulic_time_step)
 
                 wdn.epanet_api.deletePatternsAll()
 

{epyt_flow-0.6.0 → epyt_flow-0.7.1}/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-0.6.0 → epyt_flow-0.7.1}/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:
     """