From 9315431d3d8a6ed1fa024e7394cc575fc9a239e9 Mon Sep 17 00:00:00 2001 From: Terra Haxton Date: Wed, 5 Apr 2023 20:13:14 -0400 Subject: [PATCH] UM edits User manual edits based upon reviewer comments --- documentation/criticality.rst | 4 ++-- documentation/getting_started.rst | 12 ++++++------ documentation/gis.rst | 10 +++++----- documentation/graphics.rst | 2 +- documentation/installation.rst | 4 ++-- documentation/model_io.rst | 2 +- documentation/users.rst | 3 ++- 7 files changed, 19 insertions(+), 18 deletions(-) diff --git a/documentation/criticality.rst b/documentation/criticality.rst index d46633d85..ccc996c40 100644 --- a/documentation/criticality.rst +++ b/documentation/criticality.rst @@ -15,7 +15,7 @@ of elements and k elements fail. In water distribution systems analysis, N-1 contingency analysis is commonly called criticality analysis [WaWC06]_. WNTR is commonly used to run criticality analysis, where a series of simulations are run to determine the impact of -individuals failures on the system. +individual failures on the system. This framework can be expanded to include analysis where two or more elements fail at one time or in succession. Metrics such as water service availability and water pressure are commonly used to quantify impact. Analysis can include different components, including: @@ -28,7 +28,7 @@ to quantify impact. Analysis can include different components, including: In each case, a single element is changed in each simulation. The pipe, pump, or segment is closed in the case of pipe, pump, and segment criticality. Demand at hydrants is increased in the case of fire flow criticality. -Summary metrics are collected for each simulation to determine the relative impact of each simulation. +Summary metrics are collected for each simulation to determine the relative impact of each element. The `pipe criticality example `_ runs multiple hydraulic simulations to compute the impact that individual pipe closures have on water pressure. diff --git a/documentation/getting_started.rst b/documentation/getting_started.rst index aac12685b..2569eb801 100644 --- a/documentation/getting_started.rst +++ b/documentation/getting_started.rst @@ -11,7 +11,7 @@ To start using WNTR, open a Python console or IDE like Spyder and import the pac import wntr -WNTR comes with a simple `getting started example `_, shown below that uses the `EPANET Example Network 3 (Net3) INP file `_. +WNTR comes with a simple `getting started example `_, shown below, that uses the `EPANET Example Network 3 (Net3) INP file `_. This example demonstrates how to: * Import WNTR @@ -27,11 +27,11 @@ This example demonstrates how to: .. literalinclude:: ../examples/getting_started.py -Additional examples are included throughout the WNTR documentation. The examples provided in the documentation assume +Additional examples of Python code snippets are included throughout the WNTR documentation. The examples provided in the documentation assume that a user has experience using EPANET (https://www.epa.gov/water-research/epanet) and Python (https://www.python.org/), including the ability to install and use additional Python packages, such as those listed in :ref:`requirements` and :ref:`optional_dependencies`. -Several EPANET INP files and example files are also included in the WNTR repository in the `examples folder `_. -Example networks range from a simple 9 node network to a 3,000 node network. +Several EPANET INP files and Python code example files are also included in the WNTR repository in the `examples folder `_. +Example EPANET INP files are for networks that range from a simple 9 node network to a 3,000 node network. Additional network models can be downloaded from the University of Kentucky Water Distribution System Research Database at https://uknowledge.uky.edu/wdsrd. @@ -50,10 +50,10 @@ Example files can be run as follows: * Open the example file within an IDE like Spyder and run or step through the file. -Additional examples +Example Files ----------------------- -WNTR comes with additional examples that illustrate advanced use cases, including: +WNTR comes with Python code examples that illustrate advanced use cases, including: * `Pipe leak, stochastic simulation example `_: This example runs multiple hydraulic simulations of a pipe leak scenario where the location and duration are drawn from probability distributions. diff --git a/documentation/gis.rst b/documentation/gis.rst index d685adbb6..76095c0c6 100644 --- a/documentation/gis.rst +++ b/documentation/gis.rst @@ -171,7 +171,7 @@ Geometry >>> wn_gis = wntr.network.to_gis(wn, pumps_as_points=True, ... valves_as_points=True) - * Pipes that do not contain vertices are stored as a LineString while pipes that contain + * Pipes that do not contain vertices, interior vertex points that allow the visual depiction of curved pipes, are stored as a LineString while pipes that contain vertices are stored as a MultiLineString. .. _table-geometry-type: @@ -597,7 +597,7 @@ The pipes are colored based upon their maximum earthquake probability. >>> ax = earthquake_data.plot(column='Pr', alpha=0.5, cmap='bone', vmin=0, vmax=1) >>> ax = wntr.graphics.plot_network(wn, link_attribute=pipe_Pr['max'], link_width=1.5, - ... node_range=[0,1], link_range=[0,1], ax=ax) + ... node_range=[0,1], link_range=[0,1], ax=ax, link_colorbar_label='Earthquake Probability') .. doctest:: :skipif: gpd is None @@ -612,7 +612,7 @@ The pipes are colored based upon their maximum earthquake probability. :width: 800 :alt: Intersection of pipes with earthquake fault lines in EPANET example Net1 - Net1 with example earthquake fault lines intersected with pipes. + Net1 with example earthquake fault lines intersected with pipes, which are colored based upon their maximum earthquake probability. The intersect function can also be used to identify pipes that cross each fault simply by reversing the order in which the geometries intersect, as shown below: @@ -680,7 +680,7 @@ The pipes are colored based upon their weighted mean landslide probability. >>> ax = landslide_data.plot(column='Pr', alpha=0.5, cmap='bone', vmin=0, vmax=1) >>> ax = wntr.graphics.plot_network(wn, link_attribute=pipe_Pr['weighted_mean'], - ... link_width=1.5, node_range=[0,1], link_range=[0,1], ax=ax) + ... link_width=1.5, node_range=[0,1], link_range=[0,1], ax=ax, link_colorbar_label='Landslide Probability') .. doctest:: :skipif: gpd is None @@ -695,7 +695,7 @@ The pipes are colored based upon their weighted mean landslide probability. :width: 800 :alt: Intersection of junctions with landslide zones in EPANET example Net1 - Net1 with example landslide zones intersected with pipes. + Net1 with example landslide zones intersected with pipes, which are colored based upon their weighted mean landslide probability. **By reversing the order of GeoDataFrames in the intersection function**, the pipes that intersect each landslide zone and information about diff --git a/documentation/graphics.rst b/documentation/graphics.rst index 7d27a5d34..3ac9fe69b 100644 --- a/documentation/graphics.rst +++ b/documentation/graphics.rst @@ -350,7 +350,7 @@ The valves and valve segments are plotted on the network (:numref:`fig-valve_seg >>> cmap = wntr.graphics.random_colormap(N) # random color map helps view segments >>> ax = wntr.graphics.plot_network(wn, link_attribute=link_segments, node_size=0, ... link_width=2, node_range=[0,N], link_range=[0,N], node_cmap=cmap, - ... link_cmap=cmap, link_colorbar_label='Segment') + ... link_cmap=cmap, link_colorbar_label='Segment ID') >>> ax = wntr.graphics.plot_valve_layer(wn, valve_layer, add_colorbar=False, ... include_network=False, ax=ax) diff --git a/documentation/installation.rst b/documentation/installation.rst index e59fb381e..17dd1ff45 100644 --- a/documentation/installation.rst +++ b/documentation/installation.rst @@ -152,7 +152,7 @@ Step 2: Install WNTR .. note:: WNTR includes C++ code that is built into shared object files (e.g., pyd for Windows) - during the setup process. This requires that the user has a C++ compiler on their path. + during the setup process. This requires that the user has a C++ compiler (e.g., Visual Studio C++, GNU C++, MinGW) on their path. No compiler is needed when installing WNTR through PyPI (Option 1) or conda (Option 2). Step 3: Test installation @@ -197,7 +197,7 @@ and building the documentation. When installing WNTR through PyPI or conda, the shared object files do not need to be built and no compiler is needed. -If the developer does NOT have a C++ compiler, or would rather use prebuilt wheels, +If the developer does NOT have a C++ compiler, or would rather use prebuilt wheels (a pre-built binary package format for Python modules and libraries), the shared object files can be downloaded from WNTR GitHub Actions using the following steps: * Clone and setup the main branch of WNTR from the GitHub diff --git a/documentation/model_io.rst b/documentation/model_io.rst index 2d449a2eb..f4cfe1889 100644 --- a/documentation/model_io.rst +++ b/documentation/model_io.rst @@ -58,7 +58,7 @@ Dictionary representation ------------------------- The :class:`~wntr.network.io.to_dict` function -creates a dictionary from a WaterNetworkModel. +creates a dictionary, a Python data structure, from a WaterNetworkModel. The dictionary contains the following keys: * nodes (which contains junctions, tanks, and reservoirs) diff --git a/documentation/users.rst b/documentation/users.rst index ee4f3aea5..d1c987adb 100644 --- a/documentation/users.rst +++ b/documentation/users.rst @@ -9,7 +9,8 @@ User community This page is intended to capture research using WNTR and will be updated periodically. If users have related software or a publication that they would like -to add to this page, please let email the contacts or submit a pull request with the update. +to add to this page, please email the contacts listed on the WNTR GitHub webpage (https://github.com/USEPA/WNTR) +or submit a pull request with the update. Related software -----------------