Merge branch 'main' of https://github.com/USEPA/WNTR into demos

.github/workflows/build_deploy_pages.yml

@@ -21,7 +21,7 @@ jobs:
           git remote -v
       - uses: actions/setup-python@v2
         with: 
-          python-version: '3.10'
+          python-version: '3.11'
       - name: Install package
         run: |
           pip install -e .

.github/workflows/build_tests.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest] 
     steps:
     - uses: actions/checkout@v2
@@ -41,13 +41,12 @@ jobs:
         name: wntr_${{ matrix.python-version }}_${{ matrix.os }}.whl
         path: dist/wntr*
 
-  test:
-    name: Test install and usage of wntr
+  install_import:
     needs: build
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest]    
     steps:
     - name: Set up Python 
@@ -64,17 +63,17 @@ jobs:
     - name: Install wntr
       run: |
         python -m pip install --upgrade pip
-        pip install wheel numpy scipy networkx pandas matplotlib
+        pip install wheel numpy scipy networkx pandas matplotlib setuptools
         pip install --no-index --pre --find-links=. wntr
     - name: Usage of wntr
       run: |
         python -c "import wntr"
 
-  create_coverage_reports:
+  pytest_coverage:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ['3.9', '3.11']
+        python-version: ['3.9', '3.10', '3.11', '3.12']
         os: [windows-latest, macOS-latest, ubuntu-latest]
     steps:
     - uses: actions/checkout@v2
@@ -88,16 +87,7 @@ jobs:
         python -m pip install --upgrade pip
         pip install -r requirements.txt
         python -m pip install -e .
-    - name: Run Tests on Windows
-      if: matrix.os == 'windows-latest'
-      run: | # the following skips windows rst doctests that rely on geopandas (gis.rst and model_io.rst) because skipif is not working properly
-        coverage erase
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest  --doctest-modules --doctest-glob="*.rst" wntr
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" --ignore-glob="*model_io.rst" --ignore-glob="*gis.rst" documentation
-      env:
-        COVERAGE_FILE: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
     - name: Run Tests
-      if: matrix.os != 'windows-latest'
       run: | 
         coverage erase
         coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest  --doctest-modules --doctest-glob="*.rst" wntr
@@ -112,13 +102,13 @@ jobs:
         path: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
 
   combine_reports:
-    needs: [ create_coverage_reports ]
+    needs: [ pytest_coverage ]
     runs-on: ubuntu-latest
     steps:
     - name: Set up Python 
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
     - uses: actions/checkout@v2
     - name: Install coverage
       run: |
@@ -157,14 +147,14 @@ jobs:
         path: htmlcov
 
   combine_reports_upload_coveralls:
-    needs: [ create_coverage_reports ]
+    needs: [ pytest_coverage ]
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
     - name: Set up Python 
       uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
     - uses: actions/checkout@v2
     - name: Install coverage
       run: |

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - name: build the sdist
         run: |
           python -m pip install --upgrade build

.gitignore

@@ -5,6 +5,7 @@ build/
 wntr.egg-info/
 dist/
 docker/
+/.vscode
 
 *.pyd
 *.pyc

documentation/disaster_models.rst

@@ -93,7 +93,8 @@ The earthquake properties can be plotted on the network using the following exam
 
     >>> plt.tight_layout()
     >>> plt.savefig('network_pga.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-network:
 .. figure:: figures/network_pga.png
    :width: 640

documentation/environment.yml

@@ -1,6 +1,6 @@
 name: wntr
 dependencies:
-    - python=3.10
+    - python=3.11
     - numpy
     - scipy
     - networkx

documentation/fragility.rst

@@ -54,6 +54,7 @@ The following example defines a fragility curve with two damage states: Minor da
 
     >>> plt.tight_layout()
     >>> plt.savefig('fragility_curve.png', dpi=300)
+    >>> plt.close()
 
 :numref:`fig-fragility` illustrates the fragility curve as a function of peak ground acceleration.  
 For example, if the peak ground acceleration is 0.3 at 
@@ -108,7 +109,8 @@ To plot the damage state on the network, the state (i.e., Major) can be converte
 
     >>> plt.tight_layout()
     >>> plt.savefig('damage_state.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-damage-state:
 .. figure:: figures/damage_state.png
    :width: 640

documentation/gis.rst

@@ -427,6 +427,7 @@ the hydrants snapped to the junctions in Net1.
     >>> bounds = ax.axis('equal')
     >>> plt.tight_layout()
     >>> plt.savefig('snap_points.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-snap-points:
 .. figure:: figures/snap_points.png
@@ -511,6 +512,7 @@ illustrates the valve layer created by snapping points to lines in Net1.
     >>> bounds = ax.axis('equal')
     >>> plt.tight_layout()
     >>> plt.savefig('snap_lines.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-snap-lines:
 .. figure:: figures/snap_lines.png
@@ -615,7 +617,8 @@ The pipes are colored based upon their maximum earthquake probability.
     >>> bounds = ax.axis('equal')
     >>> plt.tight_layout()
     >>> plt.savefig('intersect_earthquake.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-intersect-earthquake:
 .. figure:: figures/intersect_earthquake.png
    :width: 640
@@ -699,6 +702,7 @@ The pipes are colored based upon their weighted mean landslide probability.
     >>> bounds = ax.axis('equal')
     >>> plt.tight_layout()
     >>> plt.savefig('intersect_landslide.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-intersect-landslide:
 .. figure:: figures/intersect_landslide.png
@@ -807,6 +811,7 @@ the census tracts (polygons) is different than the junction and pipe attributes.
     >>> bounds = ax.axis('equal')
     >>> plt.tight_layout()
     >>> plt.savefig('intersect_demographics.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-intersect-demographics:
 .. figure:: figures/intersect_demographics.png

documentation/graphics.rst

@@ -63,7 +63,8 @@ which can be further customized by the user.
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_basic_network.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-network-2:
 .. figure:: figures/plot_basic_network.png
    :width: 640
@@ -118,7 +119,8 @@ See https://matplotlib.org for more colormap options.
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_subplot_basic_network.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-network-3:
 .. figure:: figures/plot_subplot_basic_network.png
    :width: 800
@@ -267,7 +269,8 @@ The following example uses simulation results from above, and converts the graph
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_pump_curve.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-interactive-timeseries:
 .. figure:: figures/interactive_timeseries.png
    :width: 640
@@ -331,7 +334,8 @@ The following example plots a pump curve (:numref:`fig-pump`).
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_pump_curve.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-pump:
 .. figure:: figures/plot_pump_curve.png
    :width: 640
@@ -380,7 +384,8 @@ level of the tank is included in the figure.
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_tank_volume_curve.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-tank:
 .. figure:: figures/plot_tank_volume_curve.png
    :width: 800
@@ -420,6 +425,7 @@ The valves and valve segments are plotted on the network (:numref:`fig-valve_seg
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_valve_segment.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-valve_segment:
 .. figure:: figures/plot_valve_segment.png
@@ -447,7 +453,8 @@ valves surrounding each valve is plotted on the network
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_valve_segment_attributes.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-valve_segment_attributes:
 .. figure:: figures/plot_valve_segment_attributes.png
    :width: 640

documentation/installation.rst

@@ -8,7 +8,7 @@ Installation
 ======================================
 .. include:: <isonum.txt>
 
-WNTR requires 64-bit Python (tested on versions 3.9, 3.10, and 3.11) along with several 
+WNTR requires 64-bit Python (tested on versions 3.9, 3.10, 3.11, and 3.12) along with several 
 Python package dependencies. 
 See :ref:`requirements` and :ref:`optional_dependencies` for more information.
 WNTR can be installed as a Python package as briefly described below. 
@@ -58,7 +58,7 @@ Step 1: Setup the Python environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 	Python can be installed on Windows, Linux, and Mac OS X operating systems.
-	WNTR requires 64-bit Python (tested on versions 3.9, 3.10, and 3.11) along with several Python package dependencies.
+	WNTR requires 64-bit Python (tested on versions 3.9, 3.10, 3.11, and 3.12) along with several Python package dependencies.
 	Python distributions, such as Anaconda, are recommended to manage 
 	the Python environment.  Anaconda can be downloaded from https://www.anaconda.com/products/individual.
 	Additional instructions for setting up a Python environment independent of Anaconda are available at https://docs.python.org/.
@@ -240,7 +240,7 @@ To test WNTR, developers can run software tests locally using the following comm
 Requirements
 -------------
 
-Requirements for WNTR include 64-bit Python (tested on versions 3.9, 3.10, and 3.11) along with several Python packages. 
+Requirements for WNTR include 64-bit Python (tested on versions 3.9, 3.10, 3.11, and 3.12) along with several Python packages. 
 Users should have experience using Python (https://www.python.org/), including the installation of additional Python packages. The following Python packages are required:
 
 * NumPy :cite:p:`vacv11`: used to support large, multi-dimensional arrays and matrices, 
@@ -285,8 +285,7 @@ To install optional dependencies, run::
 .. note:: 
    Proper installation of geopandas requires installing several geopandas dependencies, including 
    fiona, pyproj, and shapely.  See https://geopandas.org/en/stable/getting_started/install.html for more information.
-   On Linux and Mac OS X, installing geopandas through the conda-forge channel will install the dependencies.
-   On Windows, the dependencies must be installed manually, see https://geoffboeing.com/2014/09/using-geopandas-windows/ for more information.
+   On Windows, the dependencies can be installed manually, see https://geoffboeing.com/2014/09/using-geopandas-windows/ for more information.
 
 .. The following is not shown in the UM
    WNTR includes a beta version of a Pyomo hydraulic simulator which requires installing 

documentation/layers.rst

@@ -80,6 +80,7 @@ The valve layer can be included in water network graphics (:numref:`fig-random-v
 
     >>> plt.tight_layout()
     >>> plt.savefig('random_valve_layer.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-random-valve-layer:
 .. figure:: figures/random_valve_layer.png
@@ -104,6 +105,7 @@ The valve layer can be included in water network graphics (:numref:`fig-strategi
 
     >>> plt.tight_layout()
     >>> plt.savefig('strategic_valve_layer.png', dpi=300)
+    >>> plt.close()
 
 .. _fig-strategic-valve-layer:
 .. figure:: figures/strategic_valve_layer.png

documentation/morph.rst

@@ -82,6 +82,7 @@ This initial set of operations can generate new branch pipes, pipes in series, a
 This cycle repeats until the network can no longer be reduced.  
 The user can specify if branch trimming, series pipe merge, and/or parallel pipe merge should be included in the skeletonization operations.  
 The user can also specify a maximum number of cycles to include in the process. 
+The user can also specify a list of junctions and pipes which should be excluded from skeletonization operations.
 
 .. only:: latex
 
@@ -147,7 +148,8 @@ approximately 3000 to approximately 1000 (:numref:`fig-skel-example`).
 
     >>> plt.tight_layout()
     >>> plt.savefig('skel_example.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-skel-example:
 .. figure:: figures/skel_example.png
    :width: 800
@@ -202,7 +204,8 @@ Pressure differences are very small in this example.
 
     >>> plt.tight_layout()
     >>> plt.savefig('skel_hydraulics.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-skel-hydraulics:
 .. figure:: figures/skel_hydraulics.png
    :width: 640

documentation/resultsobject.rst

@@ -153,7 +153,8 @@ Data can be plotted as a time series, as shown in :numref:`fig-plot-timeseries`:
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_timeseries.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-plot-timeseries:
 .. figure:: figures/plot_timeseries.png
    :width: 640
@@ -182,7 +183,8 @@ plotted in a similar manner.
 
     >>> plt.tight_layout()
     >>> plt.savefig('plot_network.png', dpi=300)
-
+    >>> plt.close()
+
 .. _fig-plot-network:
 .. figure:: figures/plot_network.png
    :width: 640

documentation/whatsnew.rst

@@ -1,6 +1,10 @@
 Release notes
 ================
 
+.. _whatsnew_120:
+
+.. include:: whatsnew/v1.2.0.rst
+
 .. _whatsnew_110:
 
 .. include:: whatsnew/v1.1.0.rst

documentation/whatsnew/v1.2.0.rst

@@ -0,0 +1,11 @@
+v1.2.0 (main)
+---------------------------------------------------
+WNTR version 1.2.0 includes the following updates:
+
+* Added basic and geospatial jupyter notebook demos, updated documentation, dropped Python 3.7 and 3.8 from testing https://github.com/USEPA/WNTR/pull/419
+* Fix: plot_network bug due to changed networkx draw function behavior https://github.com/USEPA/WNTR/pull/417
+* Fix: Addressing bug caused when units="SI" in a call to write_inp() https://github.com/USEPA/WNTR/pull/410
+* Added EpanetException class and subclasses that allow for cleaner error reporting during IO https://github.com/USEPA/WNTR/pull/381
+* Added google analytics key https://github.com/USEPA/WNTR/pull/406
+* Documentation updates to install WNTR without Anaconda https://github.com/USEPA/WNTR/pull/403
+* Added setuptools and removed readthedocs config https://github.com/USEPA/WNTR/pull/396