Metadata-Version: 2.1
Name: waco
Version: 0.1.0
Summary: Simulate the diffusion of contaminants in water networks.
Home-page: https://andreaponti5.github.io/waco
Author: Andrea Ponti
Author-email: ponti.andrea97@gmail.com
License: MIT
Project-URL: Documentation, https://andreaponti5.github.io/waco
Project-URL: Source, https://github.com/andreaponti5/waco
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wntr

<img width="550" src="https://raw.githubusercontent.com/andreaponti5/waco/1051a60fe33bb7cf123186b926f503dc50e0ca0d/docs/img/logo_title.svg" alt="WaCo Logo" title="WaCo">

<hr />



[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)



WaCo is a library for simulating contaminations in water networks built on-top of the [WNTR](https://github.com/USEPA/WNTR) library.  

For further details, consult the [documentation](https://andreaponti5.github.io/waco).



# Installation

The only requirement is the [WNTR](https://github.com/USEPA/WNTR) library that is used for the hydraulic simulations:



* Python >= 3.9

* wntr >= 1.1.0



The latest release of WaCo can be easily installed via `pip`.



```shell

pip install waco

```



You can also install the latest developement version directly from GitHub.



```shell

pip install --upgrade git+https://github.com/andreaponti5/waco

```



# Getting Started

WaCo is composed by two modules:



* `sim`: contains the functionalities to perform hydraulic simulations for extracting the demands and the contaminant diffusion in water networks. It mainly acts as a wrapper around the WNTR library.

* `analyzer`: contains the functionalities to extract the detection times and the volumes of contaminated water from the simulations.



> **Note:** Refer to the [API Reference](https://andreaponti5.github.io/waco/api_reference/sim/) for more details about the two modules.



To extract the detection times you need to simulate the diffusion of contaminant with the `sim` and then use the `analyzer` module.



```python

import waco

import wntr



wn = wntr.network.WaterNetworkModel("examples/networks/Anytown.inp")

trace = waco.sim.contamination(wn=wn)

det_time = waco.analyzer.detection_time(trace)

```



The detection times are returned in a Dataframe containing the time when the contaminant exceeds a given threshold in a node considering a specific injection point.



| **node** | **inj_node** | **time** |

|----------|:------------:|:--------:|

| 1        |      1       |    0     |

| 1        |      2       |  18900   |

| ...      |     ...      |   ...    |

| 9        |      21      |  18900   |

| 9        |      22      |   5400   |



To extract the volume of contaminated water prior detection you also need to compute the demand at each node using the `sim` module.



```python

demand = waco.sim.water_demand(wn)

contam_vol = waco.analyzer.contaminated_volume(trace=trace,

                                               det_time=det_time,

                                               demand=demand)

```



The volumes are returned in a Dataframe containing the volume of contaminated water prior detection in each node considering a specific injection point.



| **node** | **inj_node** | **volume** |

|----------|:------------:|:----------:|

| 1        |      1       |  0.031545  |

| 1        |      2       |  0.116008  |

| ...      |     ...      |    ...     |

| 9        |      21      |  0.118453  |

| 9        |      22      |  0.102254  |

