====================
Overview
====================

Water distribution systems (WDSs) are typically represented in a network format comprised of nodes (e.g., junctions, tanks, and reservoirs) and links (e.g., pipes, pumps, and valves). In order to examine how system properties such as nodal pressures and link flow rates vary over time, modeling software such as `EPANET`_ perform a series of steady state simulations by solving a series of hydraulic equations for each time step while accounting for status checks and control rules that influence system operation. The inherent properties of the different elements (such as node elevations and pipe diameters) strongly influence the resultant time-varying system attributes. Researchers, designers, planners, and operators of WDSs need to simulate and analyze system dynamics, and visualizing both static and time-varying attributes over the network layout can add spatial context to WDS system analysis.

.. _`EPANET`: https://www.epa.gov/water-research/epanet

Here we introduce VisWaterNet, an accessible, open-srouce Python package that presents a graphical representation of WDS characteristics and simulation results. VisWaterNet builds upon functions offered by `NetworkX`_ and `WNTR`_ to visualize WDS network attributes in `Matplotlib`_ figures.  

.. _`NetworkX`: https://networkx.org/documentation/stable/index.html
.. _`WNTR`: https://wntr.readthedocs.io/en/stable/index.html
.. _`Matplotlib`: https://matplotlib.org/stable/index.html

Users must provide an EPANET-compatible .INP file of the WDS network model through the Python interface. NetworkX is used to extract the network topology from the .INP file, and WNTR is used to derive hydraulic element characteristics and perform hydraulic simulations using the EPANET 2.2 engine. VisWaterNet offers the following options to visualize attribute data on the network plot :

1. varying node or link colors in a **continuous** manner, i.e., by varying node/link color according to a color gradient scale based on numerical data attributes 
2. varying node or link colors in a **discrete** manner, i.e., by grouping numerical data into specified intervals and varying node/link color based on the color assigned to the corresponding interval
3. varying node or link colors in a **categorical** manner, i.e., for attributes that can only belong to a fixed set of categories, each node/link color is assigned according to the corresponding category
4. varying node sizes and markers and link widths and linestyles to reinforce difference in color or represent a second dimension of data 

VisWaterNet also allows easy customization of WDS-specific network plots by offering the following features:

1. create a GIF to highlight the change in attributes over the simulation duration
2. create a basic network layout plot
3. import plotting data from an Excel file
4. import custom data generated by the user in a Python script
5. modify the appearance of a select number of nodes or links
6. label specific nodes or links
7. choose the units and number of significant figures for data legend labels
8. customize discrete data interval ranges and sizes
