epyt-flow 0.7.3__tar.gz → 0.8.1__tar.gz

epyt_flow-0.8.1/CITATION.cff

@@ -0,0 +1,61 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Artelt
+  given-names: André
+  orcid: "https://orcid.org/0000-0002-2426-3126"
+- family-names: Kyriakou
+  given-names: Marios S.
+  orcid: "https://orcid.org/0000-0002-2324-8661"
+- family-names: Vrachimis
+  given-names: Stelios G.
+  orcid: "https://orcid.org/0000-0001-8862-5205"
+- family-names: Eliades
+  given-names: Demetrios G.
+  orcid: "https://orcid.org/0000-0001-6184-6366"
+- family-names: Hammer
+  given-names: Barbara
+  orcid: "https://orcid.org/0000-0002-0935-5591"
+- family-names: Polycarpou
+  given-names: Marios M.
+  orcid: "https://orcid.org/0000-0001-6495-9171"
+contact:
+- family-names: Artelt
+  given-names: André
+  orcid: "https://orcid.org/0000-0002-2426-3126"
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Artelt
+    given-names: André
+    orcid: "https://orcid.org/0000-0002-2426-3126"
+  - family-names: Kyriakou
+    given-names: Marios S.
+    orcid: "https://orcid.org/0000-0002-2324-8661"
+  - family-names: Vrachimis
+    given-names: Stelios G.
+    orcid: "https://orcid.org/0000-0001-8862-5205"
+  - family-names: Eliades
+    given-names: Demetrios G.
+    orcid: "https://orcid.org/0000-0001-6184-6366"
+  - family-names: Hammer
+    given-names: Barbara
+    orcid: "https://orcid.org/0000-0002-0935-5591"
+  - family-names: Polycarpou
+    given-names: Marios M.
+    orcid: "https://orcid.org/0000-0001-6495-9171"
+  date-published: 2024-11-12
+  doi: 10.21105/joss.07104
+  issn: 2475-9066
+  issue: 103
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 7104
+  title: "EPyT-Flow: A Toolkit for Generating Water Distribution Network
+    Data"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.07104"
+  volume: 9
+title: "EPyT-Flow: A Toolkit for Generating Water Distribution Network
+  Data"

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: epyt-flow
-Version: 0.7.3
+Version: 0.8.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
@@ -31,6 +31,8 @@ Requires-Dist: openpyxl>=3.1.2
 Requires-Dist: falcon>=3.1.3
 Requires-Dist: multiprocess>=0.70.16
 Requires-Dist: geopandas>=0.14.4
+Requires-Dist: svgpath2mpl>=1.0.0
+Requires-Dist: Deprecated>=1.2.14
 Requires-Dist: psutil
 
 [![pypi](https://img.shields.io/pypi/v/epyt-flow.svg)](https://pypi.org/project/epyt-flow/)
@@ -40,6 +42,7 @@ Requires-Dist: psutil
 [![Documentation Status](https://readthedocs.org/projects/epyt-flow/badge/?version=stable)](https://epyt-flow.readthedocs.io/en/stable/?badge=stable)
 [![Downloads](https://static.pepy.tech/badge/epyt-flow)](https://pepy.tech/project/epyt-flow)
 [![Downloads](https://static.pepy.tech/badge/epyt-flow/month)](https://pepy.tech/project/epyt-flow)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.07104/status.svg)](https://doi.org/10.21105/joss.07104)
 
 # EPyT-Flow -- EPANET Python Toolkit - Flow
 
@@ -121,7 +124,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, plot_timeseries_data
+from epyt_flow.utils import to_seconds
 
 
 if __name__ == "__main__":
@@ -144,16 +147,10 @@ if __name__ == "__main__":
 
         # 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$")
+        scada_data.plot_pressures()
 
         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$")
+        scada_data.plot_flows()
 ```
 ### Generated plots
 
@@ -194,15 +191,19 @@ MIT license -- see [LICENSE](LICENSE)
 
 If you use this software, please cite it as follows:
 
-```
-@misc{github:epytflow,
-        author = {André Artelt, Marios S. Kyriakou, Stelios G. Vrachimis, Demetrios G. Eliades, Barbara Hammer, Marios M. Polycarpou},
-        title = {EPyT-Flow -- EPANET Python Toolkit - Flow},
-        year = {2024},
-        publisher = {GitHub},
-        journal = {GitHub repository},
-        howpublished = {\url{https://github.com/WaterFutures/EPyT-Flow}}
-    }
+```bibtex
+@article{Artelt2024,
+    doi = {10.21105/joss.07104},
+    url = {https://doi.org/10.21105/joss.07104},
+    year = {2024},
+    publisher = {The Open Journal},
+    volume = {9},
+    number = {103},
+    pages = {7104},
+    author = {André Artelt and Marios S. Kyriakou and Stelios G. Vrachimis and Demetrios G. Eliades and Barbara Hammer and Marios M. Polycarpou},
+    title = {EPyT-Flow: A Toolkit for Generating Water Distribution Network Data},
+    journal = {Journal of Open Source Software}
+}
 ```
 
 ## How to get Support?

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/README.md

@@ -5,6 +5,7 @@
 [![Documentation Status](https://readthedocs.org/projects/epyt-flow/badge/?version=stable)](https://epyt-flow.readthedocs.io/en/stable/?badge=stable)
 [![Downloads](https://static.pepy.tech/badge/epyt-flow)](https://pepy.tech/project/epyt-flow)
 [![Downloads](https://static.pepy.tech/badge/epyt-flow/month)](https://pepy.tech/project/epyt-flow)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.07104/status.svg)](https://doi.org/10.21105/joss.07104)
 
 # EPyT-Flow -- EPANET Python Toolkit - Flow
 
@@ -86,7 +87,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, plot_timeseries_data
+from epyt_flow.utils import to_seconds
 
 
 if __name__ == "__main__":
@@ -109,16 +110,10 @@ if __name__ == "__main__":
 
         # 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$")
+        scada_data.plot_pressures()
 
         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$")
+        scada_data.plot_flows()
 ```
 ### Generated plots
 
@@ -159,15 +154,19 @@ MIT license -- see [LICENSE](LICENSE)
 
 If you use this software, please cite it as follows:
 
-```
-@misc{github:epytflow,
-        author = {André Artelt, Marios S. Kyriakou, Stelios G. Vrachimis, Demetrios G. Eliades, Barbara Hammer, Marios M. Polycarpou},
-        title = {EPyT-Flow -- EPANET Python Toolkit - Flow},
-        year = {2024},
-        publisher = {GitHub},
-        journal = {GitHub repository},
-        howpublished = {\url{https://github.com/WaterFutures/EPyT-Flow}}
-    }
+```bibtex
+@article{Artelt2024,
+    doi = {10.21105/joss.07104},
+    url = {https://doi.org/10.21105/joss.07104},
+    year = {2024},
+    publisher = {The Open Journal},
+    volume = {9},
+    number = {103},
+    pages = {7104},
+    author = {André Artelt and Marios S. Kyriakou and Stelios G. Vrachimis and Demetrios G. Eliades and Barbara Hammer and Marios M. Polycarpou},
+    title = {EPyT-Flow: A Toolkit for Generating Water Distribution Network Data},
+    journal = {Journal of Open Source Software}
+}
 ```
 
 ## How to get Support?

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/REQUIREMENTS.txt

@@ -9,4 +9,6 @@ openpyxl>=3.1.2
 falcon>=3.1.3
 multiprocess>=0.70.16
 geopandas>=0.14.4
+svgpath2mpl>=1.0.0
+Deprecated>=1.2.14
 psutil

epyt_flow-0.8.1/epyt_flow/VERSION

@@ -0,0 +1 @@
+0.8.1

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/epyt_flow/data/benchmarks/leakdb.py

@@ -491,9 +491,9 @@ def load_scenarios(scenarios_id: list[int], use_net1: bool = True,
 
         return dem_final
 
-    week_pattern_url = "https://github.com/KIOS-Research/LeakDB/raw/master/CCWI-WDSA2018/" +\
+    week_pattern_url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/CCWI-WDSA2018/" +\
         "Dataset_Generator_Py3/weekPat_30min.mat"
-    year_offset_url = "https://github.com/KIOS-Research/LeakDB/raw/master/CCWI-WDSA2018/" +\
+    year_offset_url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/CCWI-WDSA2018/" +\
         "Dataset_Generator_Py3/yearOffset_30min.mat"
 
     download_if_necessary(os.path.join(download_dir, "weekPat_30min.mat"),

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/epyt_flow/data/networks.py

@@ -153,8 +153,7 @@ def load_net1(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Net1.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "asce-tf-wdst/Net1.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Net1.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -201,8 +200,7 @@ def load_net2(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Net2.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "asce-tf-wdst/Net2.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Net2.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -249,8 +247,7 @@ def load_net3(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Net3.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "asce-tf-wdst/Net3.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Net3.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -297,7 +294,7 @@ def load_net6(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Net6.inp")
-    url = "https://github.com/OpenWaterAnalytics/WNTR/raw/main/examples/networks/Net6.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Net6.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -344,8 +341,7 @@ def load_richmond(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Richmond_standard.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "exeter-benchmarks/Richmond_standard.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Richmond_standard.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -392,8 +388,7 @@ def load_micropolis(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "MICROPOLIS_v1.inp")
-    url = "https://github.com/OpenWaterAnalytics/EPyT/raw/main/epyt/networks/asce-tf-wdst/" + \
-          "MICROPOLIS_v1.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/MICROPOLIS_v1.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -440,8 +435,7 @@ def load_balerma(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Balerma.inp")
-    url = "https://github.com/OpenWaterAnalytics/EPyT/raw/main/epyt/networks/" + \
-          "asce-tf-wdst/Balerma.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Balerma.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -488,8 +482,7 @@ def load_rural(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "RuralNetwork.inp")
-    url = "https://github.com/OpenWaterAnalytics/EPyT/raw/main/epyt/networks/" + \
-          "asce-tf-wdst/RuralNetwork.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/RuralNetwork.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -536,8 +529,7 @@ def load_bwsn1(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "BWSN_Network_1.inp")
-    url = "https://github.com/OpenWaterAnalytics/EPyT/raw/main/epyt/networks/" + \
-          "asce-tf-wdst/BWSN_Network_1.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/BWSN_Network_1.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -584,8 +576,7 @@ def load_bwsn2(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "BWSN_Network_2.inp")
-    url = "https://github.com/OpenWaterAnalytics/EPyT/raw/main/epyt/networks/" + \
-          "asce-tf-wdst/BWSN_Network_2.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/BWSN_Network_2.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -632,8 +623,7 @@ def load_anytown(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Anytown.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "asce-tf-wdst/Anytown.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Anytown.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -727,7 +717,7 @@ def load_ctown(download_dir: str = get_temp_folder(), verbose: bool = True,
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "CTOWN.INP")
-    url = "https://github.com/scy-phy/www.batadal.net/raw/master/data/CTOWN.INP"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/CTOWN.INP"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -783,8 +773,7 @@ def load_kentucky(wdn_id: int = 1, download_dir: str = get_temp_folder(),
         raise ValueError(f"Unknown network 'ky{wdn_id}.inp'")
 
     f_in = os.path.join(download_dir, f"ky{wdn_id}.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          f"asce-tf-wdst/ky{wdn_id}.inp"
+    url = f"https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/ky{wdn_id}.inp"
 
     download_if_necessary(f_in, url, verbose)
     return load_inp(f_in, flow_units_id=flow_units_id)
@@ -836,8 +825,7 @@ def load_hanoi(download_dir: str = get_temp_folder(),
         :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`.
     """
     f_in = os.path.join(download_dir, "Hanoi.inp")
-    url = "https://raw.githubusercontent.com/OpenWaterAnalytics/EPyT/main/epyt/networks/" + \
-          "asce-tf-wdst/Hanoi.inp"
+    url = "https://filedn.com/lumBFq2P9S74PNoLPWtzxG4/EPyT-Flow/Networks/Hanoi.inp"
 
     download_if_necessary(f_in, url, verbose)
     config = load_inp(f_in, flow_units_id=flow_units_id)

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/epyt_flow/gym/scenario_control_env.py

@@ -1,12 +1,15 @@
 """
 Module provides a base class for control environments.
 """
+import os
+import uuid
 from abc import abstractmethod, ABC
 from typing import Union
 import warnings
 import numpy as np
 
-from ..simulation import ScenarioSimulator, ScenarioConfig, ScadaData
+from ..simulation import ScenarioSimulator, ScenarioConfig, ScadaData, ToolkitConstants
+from ..utils import get_temp_folder
 
 
 class ScenarioControlEnv(ABC):
@@ -21,12 +24,32 @@ class ScenarioControlEnv(ABC):
         If True, environment is automatically reset if terminated.
 
         The default is False.
+
+    Attributes
+    ----------
+    _scenario_sim : :class:`~epyt_flow.simulation.scenario_simulator.ScenarioSimulator`, protected
+        Scenario simulator of the control scenario.
+    _scenario_config : :class:`~epyt_flow.simulation.scenario_config.ScenarioConfig`
+        Scenario configuration.
+    _sim_generator : Generator[Union[:class:`~epyt_flow.simulation.scada.scada_data.ScadaData`, dict], bool, None], protected
+        Generator for running the step-wise simulation.
+    _hydraulic_scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`, protected
+        SCADA data from the hydraulic simulation -- only used if EPANET-MSX is used in the control scenario.
     """
     def __init__(self, scenario_config: ScenarioConfig, autoreset: bool = False, **kwds):
-        self.__scenario_config = scenario_config
+        if not isinstance(scenario_config, ScenarioConfig):
+            raise TypeError("'scenario_config' must be an instance of " +
+                            "'epyt_flow.simulation.ScenarioConfig' " +
+                            "but not of '{type(scenario_config)}'")
+        if not isinstance(autoreset, bool):
+            raise TypeError("'autoreset' must be an instance of 'bool' " +
+                            f"but not of '{type(autoreset)}'")
+
+        self._scenario_config = scenario_config
         self._scenario_sim = None
         self._sim_generator = None
         self.__autoreset = autoreset
+        self._hydraulic_scada_data = None
 
         super().__init__(**kwds)
 
@@ -54,15 +77,27 @@ class ScenarioControlEnv(ABC):
         """
         try:
             if self._sim_generator is not None:
-                self._sim_generator.send(True)
                 next(self._sim_generator)
+                self._sim_generator.send(True)
         except StopIteration:
             pass
 
         if self._scenario_sim is not None:
             self._scenario_sim.close()
 
-    def reset(self) -> ScadaData:
+    def contains_events(self) -> bool:
+        """
+        Check if the scenario contains any events.
+
+        Returns
+        -------
+        `bool`
+            True is the scenario contains any events, False otherwise.
+        """
+        return len(self._scenario_config.system_events) != 0 or \
+            len(self._scenario_config.sensor_reading_events) != 0
+
+    def reset(self) -> Union[tuple[ScadaData, bool], ScadaData]:
         """
         Resets the environment (i.e. simulation).
 
@@ -75,20 +110,38 @@ class ScenarioControlEnv(ABC):
             self._scenario_sim.close()
 
         self._scenario_sim = ScenarioSimulator(
-            scenario_config=self.__scenario_config)
-        self._sim_generator = self._scenario_sim.run_simulation_as_generator(support_abort=True)
+            scenario_config=self._scenario_config)
+
+        if self._scenario_sim.f_msx_in is not None:
+            # Run hydraulic simulation first
+            hyd_export = os.path.join(get_temp_folder(), f"epytflow_env_MSX_{uuid.uuid4()}.hyd")
+            sim = self._scenario_sim.run_hydraulic_simulation
+            self._hydraulic_scada_data = sim(hyd_export=hyd_export)
+
+            # Run advanced quality analysis (EPANET-MSX) on top of the computed hydraulics
+            gen = self._scenario_sim.run_advanced_quality_simulation_as_generator
+            self._sim_generator = gen(hyd_export, support_abort=True)
+        else:
+            gen = self._scenario_sim.run_hydraulic_simulation_as_generator
+            self._sim_generator = gen(support_abort=True)
 
         return self._next_sim_itr()
 
-    def _next_sim_itr(self) -> ScadaData:
+    def _next_sim_itr(self) -> Union[tuple[ScadaData, bool], ScadaData]:
         try:
             next(self._sim_generator)
-            r = self._sim_generator.send(False)
+            scada_data = self._sim_generator.send(False)
+
+            if self._scenario_sim.f_msx_in is not None:
+                cur_time = int(scada_data.sensor_readings_time[0])
+                cur_hyd_scada_data = self._hydraulic_scada_data.\
+                    extract_time_window(cur_time, cur_time)
+                scada_data.join(cur_hyd_scada_data)
 
             if self.autoreset is True:
-                return r
+                return scada_data
             else:
-                return r, False
+                return scada_data, False
         except StopIteration:
             if self.__autoreset is True:
                 return self.reset()
@@ -112,6 +165,10 @@ class ScenarioControlEnv(ABC):
                 - EN_CLOSED  = 0
                 - EN_OPEN    = 1
         """
+        if self._scenario_sim.f_msx_in is not None:
+            raise RuntimeError("Can not execute actions affecting the hydraulics "+
+                               "when running EPANET-MSX")
+
         pump_idx = self._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
         pump_link_idx = self._scenario_sim.epanet_api.getLinkPumpIndex(pump_idx + 1)
         self._scenario_sim.epanet_api.setLinkStatus(pump_link_idx, status)
@@ -127,6 +184,10 @@ class ScenarioControlEnv(ABC):
         speed : `float`
             New pump speed.
         """
+        if self._scenario_sim.f_msx_in is not None:
+            raise RuntimeError("Can not execute actions affecting the hydraulics "+
+                               "when running EPANET-MSX")
+
         pump_idx = self._scenario_sim.epanet_api.getLinkPumpNameID().index(pump_id)
         pattern_idx = self._scenario_sim.epanet_api.getLinkPumpPatternIndex(pump_idx + 1)
 
@@ -154,6 +215,10 @@ class ScenarioControlEnv(ABC):
                 - EN_CLOSED  = 0
                 - EN_OPEN    = 1
         """
+        if self._scenario_sim.f_msx_in is not None:
+            raise RuntimeError("Can not execute actions affecting the hydraulics "+
+                               "when running EPANET-MSX")
+
         valve_idx = self._scenario_sim.epanet_api.getLinkValveNameID().index(valve_id)
         valve_link_idx = self._scenario_sim.epanet_api.getLinkValveIndex()[valve_idx]
         self._scenario_sim.epanet_api.setLinkStatus(valve_link_idx, status)
@@ -173,11 +238,65 @@ class ScenarioControlEnv(ABC):
         qual_value : `float`
             New quality source value.
         """
+        if self._scenario_sim.f_msx_in is not None:
+            raise RuntimeError("Can not execute actions affecting the hydraulics "+
+                               "when running EPANET-MSX")
+
         node_idx = self._scenario_sim.epanet_api.getNodeIndex(node_id)
         pattern_idx = self._scenario_sim.epanet_api.getPatternIndex(pattern_id)
         self._scenario_sim.epanet_api.setNodeSourceQuality(node_idx, 1)
         self._scenario_sim.epanet_api.setPattern(pattern_idx, np.array([qual_value]))
 
+    def set_node_species_source_value(self, species_id: str, node_id: str, source_type: int,
+                                      pattern_id: str, source_strength: float) -> None:
+        """
+        Sets the species source at a particular node to a specific value -- i.e.
+        setting the species injection amount at a particular location.
+
+        Parameters
+        ----------
+        species_id : `str`
+            ID of the species.
+        node_id : `str`
+            ID of the node.
+        source_type : `int`
+            Type of the external species injection source -- must be one of
+            the following EPANET toolkit constants:
+
+                - EN_CONCEN     = 0
+                - EN_MASS       = 1
+                - EN_SETPOINT   = 2
+                - EN_FLOWPACED  = 3
+
+            Description:
+
+                - E_CONCEN Sets the concentration of external inflow entering a node
+                - EN_MASS Injects a given mass/minute into a node
+                - EN_SETPOINT Sets the concentration leaving a node to a given value
+                - EN_FLOWPACED Adds a given value to the concentration leaving a node
+        pattern_id : `str`
+            ID of the source pattern.
+        source_strength : `float`
+            Amount of the injected species (source strength) --
+            i.e. interpreation of this number depends on `source_type`
+        """
+        if self._scenario_sim.f_msx_in is None:
+            raise RuntimeError("You are not running EPANET-MSX")
+
+        source_type_ = "None"
+        if source_type == ToolkitConstants.EN_CONCEN:
+            source_type_ = "CONCEN"
+        elif source_type == ToolkitConstants.EN_MASS:
+            source_type_ = "MASS"
+        elif source_type == ToolkitConstants.EN_SETPOINT:
+            source_type_ = "SETPOINT"
+        elif source_type == ToolkitConstants.EN_FLOWPACED:
+            source_type_ = "FLOWPACED"
+
+        self._scenario_sim.epanet_api.setMSXPattern(pattern_id, [1])
+        self._scenario_sim.epanet_api.setMSXSources(node_id, species_id, source_type_,
+                                                    source_strength, pattern_id)
+
     @abstractmethod
     def step(self, *actions) -> Union[tuple[ScadaData, float, bool], tuple[ScadaData, float]]:
         """

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/epyt_flow/serialization.py

@@ -47,6 +47,7 @@ NETWORK_TOPOLOGY_ID                     = 26
 PUMP_STATE_EVENT_ID                     = 28
 PUMP_SPEED_EVENT_ID                     = 29
 VALVE_STATE_EVENT_ID                    = 30
+SPECIESINJECTION_EVENT_ID               = 31
 
 
 def my_packb(data: Any) -> bytes:
@@ -452,9 +453,15 @@ def save_to_file(f_out: str, data: Any, use_compression: bool = True) -> None:
 def __encode_bsr_array(array: scipy.sparse.bsr_array
                        ) -> tuple[tuple[int, int], tuple[list[float], tuple[list[int], list[int]]]]:
     shape = array.shape
-    data = array.data.flatten().tolist()
-    rows = array.nonzero()[0].tolist()
-    cols = array.nonzero()[1].tolist()
+    data = []
+    rows = []
+    cols = []
+
+    array_ = array.tocsr()   # Bug workaround: BSR arrays do not implement __getitem__
+    for i, j in zip(*array_.nonzero()):
+        rows.append(int(i))
+        cols.append(int(j))
+        data.append(float(array_[i, j]))
 
     return shape, (data, (rows, cols))
 

{epyt_flow-0.7.3 → epyt_flow-0.8.1}/epyt_flow/simulation/events/__init__.py

@@ -1,5 +1,6 @@
 from .system_event import *
 from .leakages import *
+from .quality_events import *
 from .sensor_reading_event import *
 from .sensor_faults import *
 from .sensor_reading_attack import *