epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/uncertainty/utils.py

@@ -0,0 +1,206 @@
+"""
+Module provides some helper functions regarding the implementation of uncertainty.
+"""
+import numpy as np
+from scipy.ndimage import gaussian_filter1d
+
+
+def smoothing(pattern: np.ndarray, sigma: float = 10.) -> np.ndarray:
+    """
+    Smoothes a given pattern by applying a Gaussian filter.
+
+    Parameters
+    ----------
+    pattern : `numpy.ndarray`
+        The original pattern
+    sigma : `float`, optional
+        Standard deviation for the Gaussian filter.
+
+        The default is 10.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        The smoothed pattern.
+    """
+    return gaussian_filter1d(pattern, sigma=sigma)
+
+
+def scale_to_range(pattern: np.ndarray, min_value: float, max_value: float) -> np.ndarray:
+    """
+    Scales a given pattern to an interval.
+
+    Parameters
+    ----------
+    pattern : `numpy.ndarray`
+        The pattern to be scaled.
+    min_value : `float`
+        Lower bound of the pattern.
+    max_value : `float`
+        Upper bound of the pattern.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        The scaled pattern.
+    """
+    if min_value is None or max_value is None:
+        return pattern
+
+    min_pattern_val = np.min(pattern)
+    max_pattern_val = np.max(pattern)
+
+    return [(x - min_pattern_val) / (max_pattern_val - min_pattern_val) * (max_value - min_value)
+            + min_value for x in pattern]
+
+
+def generate_random_gaussian_noise(n_samples: int):
+    """
+    Generates Gaussian noise using a random mean ([0,1]) and random standard deviation ([0,1]).
+
+    Parameters
+    ----------
+    n_samples : `int`
+        Number of random samples.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        Gaussian noise.
+    """
+    return np.random.normal(np.random.rand(), np.random.rand(), size=n_samples)
+
+
+def generate_deep_random_gaussian_noise(n_samples: int, mean: float = None):
+    """
+    Generates random Gaussian noise where the standard deviations (and mean) are changing over time.
+
+    Parameters
+    ----------
+    n_samples : `int`
+        Number of random samples.
+    mean : `float`, optional
+        Fixed mean at all points in time.
+        If None, random means are generated.
+
+        The default is None.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        Random Gaussian noise.
+    """
+    noise = []
+
+    if mean is None:
+        mean = create_deep_random_pattern(n_samples, min_value=-1., max_value=1.)
+    else:
+        mean = [mean] * n_samples
+    rand_std = create_deep_random_pattern(n_samples)
+    noise = np.array([np.random.normal(m, s) for m, s in zip(mean, rand_std)])
+
+    return noise
+
+
+def create_deep_random_pattern(n_samples: int, min_value: float = 0., max_value: float = 1.,
+                               init_value: float = None) -> np.ndarray:
+    """
+    Generates a random pattern.
+
+    Parameters
+    ----------
+    n_samples : `int`
+        Number of random samples -- i.e. length of the pattern.
+    min_value : `float`, optional
+        Lower bound of the pattern.
+
+        The default is zero.
+    max_value : `float`, optional
+        Upper bound of the pattern.
+
+        The default is one.
+    init_value : `float`, optional
+        Value of the first sample in the pattern.
+        If None, a random value is used.
+
+        The default is None.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        Random pattern.
+    """
+    pattern = []
+    start_value = init_value
+
+    while len(pattern) < n_samples:
+        if len(pattern) != 0:
+            start_value = pattern[-1]
+
+        pattern += _create_deep_random_pattern(start_value, min_value=min_value,
+                                               max_value=max_value)
+
+    pattern = pattern[:n_samples]
+
+    # Scaling to value range
+    pattern = scale_to_range(pattern, min_value, max_value)
+
+    return np.array(pattern)
+
+
+def _create_deep_random_pattern(start_value: float = None, min_length: int = 2, max_length: int = 5,
+                                min_value: float = None, max_value: float = None) -> np.ndarray:
+    """
+    Generates a random pattern of random length.
+
+    Parameters
+    ----------
+    start_value : `float`, optional
+        First value in the pattern.
+        If None, a random value is used.
+
+        The default is None.
+    min_length : `int`, optional
+        Minium length of the pattern.
+
+        The default is 2.
+    max_length : `int`
+        Maximum length of the pattern.
+
+        The default is 5.
+    min_value : `float`, optional
+        Lower bound of the pattern.
+
+        The default is zero.
+    max_value : `float`, optional
+        Upper bound of the pattern.
+
+        The default is one.
+
+    Returns
+    -------
+    `numpy.ndarray`
+        Random pattern.
+    """
+    pattern = []
+
+    # Random parameters of pattern
+    if start_value is None:
+        start_value = np.random.rand()
+    length = np.random.randint(low=min_length, high=max_length)
+    vec = np.random.choice([-.1, .1])
+
+    # Generate pattern
+    cur_value = start_value
+    pattern.append(start_value)
+
+    for _ in range(length):
+        cur_value = cur_value + np.random.rand() * vec
+        pattern.append(cur_value)
+        if min_value is not None and max_value is not None:
+            if cur_value < min_value:
+                vec = .1
+            elif cur_value > max_value:
+                vec = -.1
+
+    return pattern

epyt_flow/utils.py

@@ -0,0 +1,306 @@
+"""
+Module provides helper functions.
+"""
+import os
+import math
+import tempfile
+import zipfile
+from pathlib import Path
+import requests
+from tqdm import tqdm
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def time_points_to_one_hot_encoding(time_points: list[int], total_length: int) -> list[int]:
+    """
+    Converts a list of time points into a one-hot-encoding.
+
+    Parameters
+    ----------
+    time_points : `list[int]`
+        Time points to be one-hot-encoded.
+    total_length : `int`
+        Length of final one-hot-encoding.
+
+    Returns
+    -------
+    `list[int]`
+        One-hot-encoded time points.
+    """
+    results = [0] * total_length
+
+    for t in time_points:
+        results[t] = 1
+
+    return results
+
+
+def volume_to_level(tank_volume: float, tank_diameter: float) -> float:
+    """
+    Computes the water level in a tank containing a given volume of water.
+
+    Parameters
+    ----------
+    tank_volume : `float`
+        Water volume in the tank.
+    tank_diameter : `float`
+        Diameter of the tank.
+
+    Returns
+    -------
+    `float`
+        Water level in tank.
+    """
+    if not isinstance(tank_volume, float):
+        raise TypeError("'tank_volume' must be an instace of 'float' " +
+                        f"but not of '{type(tank_volume)}'")
+    if tank_volume < 0:
+        raise ValueError("'tank_volume' can not be negative")
+    if not isinstance(tank_diameter, float):
+        raise TypeError("'tank_diameter' must be an instace of 'float' " +
+                        f"but not of '{type(tank_diameter)}'")
+    if tank_diameter <= 0:
+        raise ValueError("'tank_diameter' must be greater than zero")
+
+    return (4. / (math.pow(tank_diameter, 2) * math.pi)) * tank_volume
+
+
+def plot_timeseries_data(data: np.ndarray, labels: list[str] = None, x_axis_label: str = None,
+                         y_axis_label: str = None, show: bool = True) -> None:
+    """
+    Plots a single or multiple time series.
+
+    Parameters
+    ----------
+    data : `numpy.ndarray`
+        Time series data -- each row in `data` corresponds to a complete time series.
+    labels : `list[str]`, optional
+        Labels for each time series in `data`.
+        If None, no labels are shown.
+
+        The default is None.
+    x_axis_label : `str`, optional
+        X axis label.
+
+        The default is None.
+    y_axis_label : `str`, optional
+        Y axis label.
+
+        The default is None.
+    show : `bool`, optional
+        If True, the plot/figure is shown in a window.
+
+        The default is True.
+    """
+    if not isinstance(data, np.ndarray):
+        raise TypeError(f"'data' must be an instance of 'numpy.ndarray' but not of '{type(data)}'")
+    if len(data.shape) != 2:
+        raise ValueError("'data' must be a 2d array where each row corresponds to a time series " +
+                         "-- use '.reshape(1, -1)' in case of single time series")
+    if labels is not None:
+        if not isinstance(labels, list) or not all(isinstance(label, str) for label in labels):
+            raise TypeError("'labels' must be a instance of 'list[str]'")
+    if x_axis_label is not None:
+        if not isinstance(x_axis_label, str):
+            raise TypeError("'x_axis_label' must be an instance of 'str' " +
+                            f"but not of '{type(x_axis_label)}'")
+    if y_axis_label is not None:
+        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 not isinstance(show, bool):
+        raise TypeError(f"'show' must be an instance of 'bool' but not of '{type(show)}'")
+
+    plt.figure()
+
+    labels = labels if labels is not None else [None] * data.shape[0]
+
+    for i in range(data.shape[0]):
+        plt.plot(data[i, :], ".-", label=labels[i])
+
+    if not any(label is None for label in labels):
+        plt.legend()
+
+    if x_axis_label is not None:
+        plt.xlabel(x_axis_label)
+    if y_axis_label is not None:
+        plt.ylabel(y_axis_label)
+
+    if show is True:
+        plt.show()
+
+
+def plot_timeseries_prediction(y: np.ndarray, y_pred: np.ndarray,
+                               confidence_interval: np.ndarray = None, show: bool = True) -> None:
+    """
+    Plots the prediction (e.g. forecast) of *single* time series together with the
+    ground truth time series. In addition, confidence intervals can be plotted as well.
+
+    Parameters
+    ----------
+    y : `numpy.ndarray`
+        Ground truth values.
+    y_pred : `numpy.ndarray`
+        Predicted values.
+    confidence_interval : `numpy.ndarray`, optional
+        Confidence interval (upper and lower value) for each prediction in `y_pred`.
+        If not None, the confidence interval is plotted as well.
+
+        The default is None.
+    show : `bool`, optional
+        If True, the plot/figure is shown in a window.
+
+        The default is True.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+    if not isinstance(show, bool):
+        raise TypeError(f"'show' must be an instance of 'bool' but not of '{type(show)}'")
+
+    plt.figure()
+
+    if confidence_interval is not None:
+        plt.fill_between(range(len(y_pred)),
+                         y_pred - confidence_interval[0],
+                         y_pred + confidence_interval[1],
+                         alpha=0.5)
+    plt.plot(y_pred, ".-", label="Prediction")
+    plt.plot(y, ".-", label="Ground truth")
+    plt.legend()
+
+    if show is True:
+        plt.show()
+
+
+def download_if_necessary(download_path: str, url: str, verbose: bool = True) -> None:
+    """
+    Downloads a file from a given URL if it does not already exist in a given path.
+
+    Note that if the path (folder) does not already exist, it will be created.
+
+    Parameters
+    ----------
+    download_path : `str`
+        Local path to the file -- if this path does not exist, the file will be downloaded from
+        the provided 'url' and stored in 'download_dir'.
+    url : `str`
+        Web-URL.
+    verbose : `bool`, optional
+        If True, a progress bar is shown while downloading the file.
+
+        The default is True.
+    """
+    folder_path = str(Path(download_path).parent.absolute())
+    create_path_if_not_exist(folder_path)
+
+    if not os.path.isfile(download_path):
+        response = requests.get(url, stream=verbose, allow_redirects=True, timeout=1000)
+
+        if verbose is True:
+            content_length = int(response.headers.get('content-length', 0))
+            with open(download_path, "wb") as file, tqdm(desc=download_path,
+                                                         total=content_length,
+                                                         unit='B',
+                                                         unit_scale=True,
+                                                         unit_divisor=1024) as progress_bar:
+                for data in response.iter_content(chunk_size=1024):
+                    size = file.write(data)
+                    progress_bar.update(size)
+        else:
+            with open(download_path, "wb") as f_out:
+                f_out.write(response.content)
+
+
+def create_path_if_not_exist(path_in: str) -> None:
+    """
+    Creates a directory and all its parent directories if they do not already exist.
+
+    Parameters
+    ----------
+    path_in : `str`
+        Path to be created.
+    """
+    Path(path_in).mkdir(parents=True, exist_ok=True)
+
+
+def unpack_zip_archive(f_in: str, folder_out: str) -> None:
+    """
+    Unpacks a .zip archive.
+
+    Parameters
+    ----------
+    f_in : `str`
+        Path to the .zip file.
+    folder_out : `str`
+        Path to the folder where the unpacked files will be stored.
+    """
+    with zipfile.ZipFile(f_in, "r") as f:
+        f.extractall(folder_out)
+
+
+def get_temp_folder() -> str:
+    """
+    Gets a path to a temporary folder -- i.e. a folder for storing temporary files.
+
+    Returns
+    -------
+    `str`
+        Path to a temporary folder.
+    """
+    return tempfile.gettempdir()
+
+
+def to_seconds(days: int = None, hours: int = None, minutes: int = None) -> int:
+    """
+    Converts a timestamp (i.e. days, hours, minutes) into seconds.
+
+    Parameters
+    ----------
+    days : `int`, optional
+        Days.
+    hours : `int`, optional
+        Hours.
+    minutes : `int`, optional
+        Minutes.
+
+    Returns
+    -------
+    `int`
+        Timestamp in seconds.
+    """
+    sec = 0
+
+    if days is not None:
+        if not isinstance(days, int):
+            raise TypeError(f"'days' must be an instance of 'int' but not of {type(days)}")
+        if days <= 0:
+            raise ValueError("'days' must be positive")
+
+        sec += 24*60*60 * days
+    if hours is not None:
+        if not isinstance(hours, int):
+            raise TypeError(f"'hours' must be an instance of 'int' but not of {type(hours)}")
+        if hours <= 0:
+            raise ValueError("'hours' must be positive")
+
+        sec += 60*60 * hours
+    if minutes is not None:
+        if not isinstance(minutes, int):
+            raise TypeError(f"'minutes' must be an instance of 'int' but not of {type(minutes)}")
+        if minutes <= 0:
+            raise ValueError("'minutes' must be positive")
+
+        sec += 60 * minutes
+
+    return sec

epyt_flow-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 EPyT-Flow Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

epyt_flow-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.1
+Name: epyt-flow
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/WaterFutures/EPyT-Flow
+Project-URL: Documentation, https://epytflow.readthedocs.io/en/latest/
+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
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: epyt >=1.1.3
+Requires-Dist: requests >=2.31.0
+Requires-Dist: scipy >=1.11.4
+Requires-Dist: u-msgpack-python >=2.8.0
+Requires-Dist: networkx >=3.2.1
+Requires-Dist: scikit-learn >=1.4.0
+Requires-Dist: tqdm >=4.66.2
+Requires-Dist: openpyxl >=3.1.2
+Requires-Dist: falcon >=3.1.3
+Requires-Dist: multiprocess >=0.70.16
+Requires-Dist: psutil
+
+# EPyT-Flow -- EPANET Python Toolkit - Flow
+
+EPyT-Flow is a Python package building on top of [EPyT](https://github.com/OpenWaterAnalytics/EPyT) 
+for providing easy access to water distribution network simulations.
+It aims to provide a high-level interface for the easy generation of hydraulic and water quality scenario data.
+However, it also provides access to low-level functions by [EPANET](https://github.com/USEPA/EPANET2.2) 
+and [EPANET-MSX](https://github.com/USEPA/EPANETMSX/).
+
+EPyT-Flow provides easy access to popular benchmark data sets for event detection and localization.
+Furthermore, it also provides an environment for developing and testing control algorithms.
+
+![](https://github.com/WaterFutures/EPyT-Flow/blob/main/docs/_static/net1_plot.png?raw=true)
+
+## Installation
+
+EPyT-Flow supports Python 3.9 - 3.12
+
+Note that [EPANET and EPANET-MSX sources](epyt_flow/EPANET/) are compiled and overrite the binaries
+shipped by EPyT IF EPyT-Flow is installed on a Linux system. By this we not only aim to achieve
+a better performance of the simulations but also avoid any compatibility problems of pre-compiled binaries.
+
+### PyPI
+
+```
+pip install epyt-flow
+```
+
+### Git
+Download or clone the repository:
+```
+git clone https://github.com/WaterFutures/EPyT-Flow.git
+cd EPyT-Flow
+```
+
+Install all requirements as listed in [REQUIREMENTS.txt](REQUIREMENTS.txt):
+```
+pip install -r REQUIREMENTS.txt
+```
+
+Install the toolbox:
+```
+pip install .
+```
+
+## Quick Example
+
+<a target="_blank" href="https://colab.research.google.com/github/WaterFutures/EPyT-Flow/blob/main/docs/examples/basic_usage.ipynb">
+<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
+</a>
+
+```python
+from epyt_flow.data.benchmarks import load_leakdb_scenarios
+from epyt_flow.simulation import ScenarioSimulator
+from epyt_flow.utils import to_seconds
+
+
+if __name__ == "__main__":
+    # Load first Hanoi scenario from LeakDB
+    network_config, = load_leakdb_scenarios(scenarios_id=["1"], use_net1=False)
+
+    # Create scenario
+    with ScenarioSimulator(scenario_config=network_config) as sim:
+        # Set simulation duration to two days
+        sim.set_general_parameters(simulation_duration=to_seconds(days=2))
+
+        # Place pressure sensors at nodes "13", "16", "22", and "30"
+        sim.set_pressure_sensors(sensor_locations=["13", "16", "22", "30"])
+
+        # Place a flow sensor at link/pipe "1"
+        sim.set_flow_sensors(sensor_locations=["1"])
+
+        # Run entire simulation
+        scada_data = sim.run_simulation()
+
+        # Show sensor readings over the entire simulation
+        print(f"Pressure readings: {scada_data.get_data_pressures()}")
+        print(f"Flow readings: {scada_data.get_data_flows()}")
+```
+
+## Documentation
+
+Documentation is available on readthedocs: [https://epytflow.readthedocs.io/en/latest/](https://epytflow.readthedocs.io/en/latest/)
+
+## License
+
+MIT license -- see [LICENSE](LICENSE)
+
+## How to Cite?
+
+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}}
+    }
+```
+
+## 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).