diff --git a/documentation/advancedsim.rst b/documentation/advancedsim.rst index 7fed20831..4a8be4fe7 100644 --- a/documentation/advancedsim.rst +++ b/documentation/advancedsim.rst @@ -208,13 +208,13 @@ The SciPy method ``sparse.linalg.spsolve`` can be used to solve the system of eq :math:`b` is the residual of the model, and :math:`x` is the solution to the system of equations. -* Get the variables values. This returns the values for :math:`u` and :math:`v`, which were both initialized to be 1. +* Get the variables' values. This returns the values for :math:`u` and :math:`v`, which were both initialized to be 1. * Solve the system of equations and return the solution. -* Add the solution back to the variables values. +* Add the solution back to the variables' values. -* Load the variable values back into the model. +* Load the variables' values back into the model. * Evaluate the residuals of the model. If the maximum absolute value of the residuals is too high, the solve can be repeated. diff --git a/documentation/disaster_models.rst b/documentation/disaster_models.rst index 6b946ec59..8e86fdaa5 100644 --- a/documentation/disaster_models.rst +++ b/documentation/disaster_models.rst @@ -153,7 +153,7 @@ and check valves next to reservoirs. .. note:: The power outage is added to the WaterNetworkModel as a Rule. If the WaterNetworkModel includes Controls that impact pumps, - it is recommended that those Controls are converted to Rules using + it is recommended that those Controls are converted to Rules to ensure that the power outage is evaluated in a consistent manner. The method :class:`~wntr.network.model.WaterNetworkModel.convert_controls_to_rules` converts all Controls to Rules, with an option input argument to set priority. @@ -182,7 +182,7 @@ The following example adds fire flow conditions at a specific node. Environmental change --------------------- -Environmental change is a long term problem for water distribution +Environmental change is a long-term problem for water distribution systems. Changes in the environment could lead to reduced water availability, damage from weather incidents, diff --git a/documentation/framework.rst b/documentation/framework.rst index 5acee0be2..946cb0fcd 100644 --- a/documentation/framework.rst +++ b/documentation/framework.rst @@ -37,7 +37,7 @@ run simulations are described in more detail below, followed by a list of softwa :class:`~wntr.morph` Contains methods to modify water network model morphology, including network skeletonization, modifying node coordinates, and splitting or breaking pipes. :class:`~wntr.gis` Contains geospatial capabilities, including a function to convert the water network model to GeoDataFrames. :class:`~wntr.graphics` Contains functions to generate graphics. - :class:`~wntr.epanet` Contains EPANET 2.00.12 and and EPANET 2.2.0 compatibility class and methods for WNTR. + :class:`~wntr.epanet` Contains EPANET 2.00.12 and EPANET 2.2.0 compatibility class and methods for WNTR. :class:`~wntr.utils` Contains helper functions. ================================================= ============================================================================================================================================================================================================================================================================= @@ -106,7 +106,7 @@ Current WNTR limitations include: * Use of the "MAP" file option in EPANET will **not** automatically assign node coordinates from that file. -**WNTR reads in and writes all sections of EPANET INP files**. This includes the following sections: +**WNTR reads and writes all sections of EPANET INP files**. This includes the following sections: [BACKDROP], [CONTROLS], [COORDINATES], @@ -156,7 +156,7 @@ Known discrepancies between the WNTRSimulator and EpanetSimulator are listed bel * **Tank draining**: The EpanetSimulator (and EPANET) continue to supply water from tanks after they reach their minimum elevation. This can result in incorrect system pressures. - See issues https://github.com/USEPA/WNTR/issues/210 and https://github.com/OpenWaterAnalytics/EPANET/issues/623. + See issues at the following sites: https://github.com/USEPA/WNTR/issues/210 and https://github.com/OpenWaterAnalytics/EPANET/issues/623. The EPANET dll in WNTR will be updated when an EPANET release is available. * **Pump controls and patterns**: Pumps have speed settings which are adjustable by controls and/or patterns. With the EpanetSimulator, diff --git a/documentation/getting_started.rst b/documentation/getting_started.rst index 2569eb801..92439c11d 100644 --- a/documentation/getting_started.rst +++ b/documentation/getting_started.rst @@ -21,7 +21,7 @@ This example demonstrates how to: .. note:: If WNTR is installed using PyPI or Anaconda, the examples folder is not included. - The examples folder can be downloaded by going to https://github.com/USEPA/WNTR, select the "Clone or download" button and then select "Download ZIP." + The examples folder can be downloaded by going to https://github.com/USEPA/WNTR, selecting the "Clone or download" button, and then selecting "Download ZIP." Uncompress the zip file using standard software tools (e.g., unzip, WinZip) and store them in a folder. The following example assumes the user is running the example from the examples folder. @@ -70,14 +70,14 @@ A Jupyter Notebook, an open-sourced web-based application, can be accessed throu associated software available at https://jupyter.org. These demonstrations include the following: * `Pipe break demo `_: - This demostration runs multiple hydraulic simulations to compute the impact that different individual pipe breaks/closures have on network pressure. - It also plots the pressure and population impacts for all junctions effected by the pipe breaks/closures. + This demonstration runs multiple hydraulic simulations to compute the impact that different individual pipe breaks/closures have on network pressure. + It also plots the pressure and population impacts for all junctions affected by the pipe breaks/closures. * `Segment pipe break demo `_: - This demostration runs multiple hydraulic simulations to compute the impact that different pipe segment breaks/closures (identified by isolation - valve locations) have on network pressure. It also plots the pressure and population impacts for all junctions effected by the pipe segment breaks/closures. + This demonstration runs multiple hydraulic simulations to compute the impact that different pipe segment breaks/closures (identified by isolation + valve locations) have on network pressure. It also plots the pressure and population impacts for all junctions affected by the pipe segment breaks/closures. * `Fire flow demo `_: - This demostration runs multiple hydraulic simulations with and without fire fighting flow demand to multiple fire hydrant nodes. - It also plots the pressure and population impacts for junctions effected by the additional fire fighting flow demand. + This demonstration runs multiple hydraulic simulations with and without fire fighting flow demand to multiple fire hydrant nodes. + It also plots the pressure and population impacts for junctions affected by the additional fire fighting flow demand. * `Earthquake demo `_: This demostration runs hydraulic simulations of earthquake damage with and without repair efforts. It plots fragility curves, peak ground acceleration, peak ground velocity, repair rate, leak probability, and damage states. In addition, it compares diff --git a/documentation/gis.rst b/documentation/gis.rst index 942bf5c93..9cbacafb0 100644 --- a/documentation/gis.rst +++ b/documentation/gis.rst @@ -47,7 +47,7 @@ The following section describes capabilities in WTNR that use GeoPandas GeoDataF .. note:: Functions that use GeoDataFrames require the Python package **geopandas** [JVFM21]_ - and **rtree** [rtree]_, both are optional dependencies of WNTR. + and **rtree** [rtree]_. Both are optional dependencies of WNTR. Note that **shapely** is installed with geopandas. The following examples use a water network generated from Net1.inp. @@ -101,7 +101,7 @@ Individual GeoDataFrames are obtained as follows (Note that the example network, >>> wn_gis.pumps # doctest: +SKIP >>> wn_gis.valves # doctest: +SKIP -For example, the junctions GeoDataFrame contains the following information +For example, the junctions GeoDataFrame contains the following information: .. doctest:: :skipif: gpd is None @@ -264,7 +264,7 @@ Several important points on CRS are listed below. * Projected CRSs are preferred for more accurate distance calculations. The following example reads a GeoJSON file and overrides the CRS to change it from EPSG:4326 to EPSG:3857. -(Note, this does not change the coordinates in the geometry column). +(Note, this does not change the coordinates in the geometry column.) .. doctest:: :skipif: gpd is None @@ -294,8 +294,8 @@ The following example reads a GeoJSON file and overrides the CRS to change it fr >>> hydrant_data = gpd.read_file(examples_dir+'/data/Net1_hydrant_data.geojson') -The following example reads a GeoJSON file and transforms the CRS to EPSG:3857 -(Note, this transforms the coordinates in the geometry column). +The following example reads a GeoJSON file and transforms the CRS to EPSG:3857. +(Note, this transforms the coordinates in the geometry column.) .. doctest:: :skipif: gpd is None @@ -372,7 +372,7 @@ Snap hydrants to junctions GIS data which include the network hydrant locations is useful in a resilience analysis. In particular, this information identifies which junctions could have their demands increased to simulate the opening -of hydrants to fight fires or flush contaminated water out of the network either of which could caused by a disaster scenario. +of hydrants to fight fires or flush contaminated water out of the network, either of which could caused by a disaster scenario. The following example highlights the process to snap hydrants to junctions. The example dataset of hydrant locations is a GeoDataFrame with a `geometry` column that contains ``shapely.geometry.Point`` geometries and a `demand` column that defines fire flow requirements. @@ -631,7 +631,7 @@ the order in which the geometries intersect, as shown below: Assign landslide probability to pipes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Landslide hazard zones GIS data can be used to identify pipes with the potential to be effected during a landslide. +Landslide hazard zones GIS data can be used to identify pipes with the potential to be affected during a landslide. The following example highlights the process to assign landslide probabilities to pipes. The landslide hazard zones example dataset is a GeoDataFrame with a `geometry` column that contains ``shapely.geometry.LineString`` geometries and a `Pr` column which contains the probability of damage from a landslide in that zone. diff --git a/documentation/hydraulics.rst b/documentation/hydraulics.rst index 5f3a89b2c..0c755bda5 100644 --- a/documentation/hydraulics.rst +++ b/documentation/hydraulics.rst @@ -278,8 +278,8 @@ in the following example. EPANET specifications. When using the WNTRSimulator, the required pressure, minimum pressure, and pressure exponent can vary throughout the network. -By default, each junction's required pressure, minimum pressure, and pressure exponent is set to None and the global value -in the hydraulic options are used to define the PDD constraint for that junction. +By default, each junction's required pressure, minimum pressure, and pressure exponent is set to None and the global value is used +in the hydraulic options to define the PDD constraint for that junction. If the user defines required pressure, minimum pressure, or pressure exponent on a junction, those values will override the required pressure, minimum pressure, and pressure exponent defined in the global hydraulic options when defining the PDD constraint for that junction. @@ -295,7 +295,7 @@ junction 121. The ability to use spatially variable required pressure, minimum pressure, and pressure exponent is only available when using the WNTRSimulator. -The EpanetSimulator always uses values in the global hydraulic options. +The EpanetSimulator always uses the global values in the hydraulic options. .. _leak_model: @@ -358,13 +358,13 @@ The following example adds a leak to the water network model. Pause and restart ------------------ -The WNTRSimulator includes the ability to +The WNTRSimulator includes the ability to: * Reset initial values and re-simulate using the same water network model. Initial values include simulation time, tank head, reservoir head, pipe status, pump status, and valve status. -* Pause a hydraulic simulation, change network operations, and then restart the simulation +* Pause a hydraulic simulation, change network operations, and then restart the simulation. -* Save the water network model and results to files and reload for future analysis +* Save the water network model and results to files and reload for future analysis. These features are helpful when evaluating various response action plans or when simulating long periods of time where the time resolution might vary. diff --git a/documentation/installation.rst b/documentation/installation.rst index bf93ade19..44b762dc6 100644 --- a/documentation/installation.rst +++ b/documentation/installation.rst @@ -199,7 +199,7 @@ and building the documentation. .. 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 developer has a C++ compiler on their path. + during the setup process. This requires that the developer has a C++ compiler located in a folder specified in their PATH. When installing WNTR through PyPI or conda, the shared object files do not need to be built and no compiler is needed. diff --git a/documentation/morph.rst b/documentation/morph.rst index 83cf224b1..6a1234ad0 100644 --- a/documentation/morph.rst +++ b/documentation/morph.rst @@ -17,7 +17,7 @@ Network skeletonization in WNTR follows the procedure outlined in [WCSG03]_. The skeletonization process retains all tanks, reservoirs, valves, and pumps, along with all junctions and pipes that are associated with controls. Junction demands and demand patterns are retained in the skeletonized model, as described below. Merged pipes are assigned equivalent properties for diameter, length, and roughness to approximate the updated system behavior. -Pipes that fall below a user defined pipe diameter threshold are candidates for removal based on three operations, including: +Pipes that fall below a user-defined pipe diameter threshold are candidates for removal based on three operations, including: 1. **Branch trimming**: Dead-end pipes that are below the pipe diameter threshold are removed from the model (:numref:`fig-branch-trim`). The demand and demand pattern assigned to the dead-end junction is moved to the junction that is retained in the model. diff --git a/documentation/reference.rst b/documentation/reference.rst index 422332ace..15f12a23d 100644 --- a/documentation/reference.rst +++ b/documentation/reference.rst @@ -16,15 +16,15 @@ References .. [BaRR13] Barker, K., Ramirez-Marquez, J.E., and Rocco, C.M. (2013). Resilience-based network component importance measures. Reliability Engineering and System Safety, 117, 89-97. -.. [Bieni19] Bieniek, T., van Andel, B., and Bø, T.I. (2019). Bidirectional UTM-WGS84 converter for python, Retrieved on February 5, 2019 from https://github.com/Turbo87/utm +.. [Bieni19] Bieniek, T., van Andel, B., and Bø, T.I. (2019). Bidirectional UTM-WGS84 converter for python, Retrieved on February 5, 2019 from https://github.com/Turbo87/utm. .. [CrLo02] Crowl, D.A., and Louvar, J.F. (2011). Chemical Process Safety: Fundamentals with Applications, 3 edition. Upper Saddle River, NJ: Prentice Hall, 720p. -.. [ELLT12] Eto, J.H., LaCommare, K.H., Larsen, P.H., Todd, A., and Fisher, E. (2012). An Examination of Temporal Trends in Electricity Reliability Based on Reports from U.S. Electric Utilities. Lawrence Berkeley National Laboratory Report Number LBNL-5268E. Berkeley, CA: Ernest Orlando Lawrence Berkeley National Laboratory, 68p +.. [ELLT12] Eto, J.H., LaCommare, K.H., Larsen, P.H., Todd, A., and Fisher, E. (2012). An Examination of Temporal Trends in Electricity Reliability Based on Reports from U.S. Electric Utilities. Lawrence Berkeley National Laboratory Report Number LBNL-5268E. Berkeley, CA: Ernest Orlando Lawrence Berkeley National Laboratory, 68p. -.. [JVFM21] Jordahl, K., Van den Bossche, J., Fleischmann, M, McBride, J. and others (2021) geopandas, 10.5281/zenodo.5573592 +.. [JVFM21] Jordahl, K., Van den Bossche, J., Fleischmann, M, McBride, J. and others (2021) geopandas, 10.5281/zenodo.5573592. -.. [Folium] python-visualization/folium. (n.d.). Retrieved on February 5, 2019 from https://github.com/python-visualization/folium +.. [Folium] python-visualization/folium. (n.d.). Retrieved on February 5, 2019 from https://github.com/python-visualization/folium. .. [GaCl18] Gazoni, E. and Clark, C. (2018) openpyxl - A Python library to read/write Excel 2010 xlsx/xlsm files, Retrieved on May 4, 2018 from https://openpyxl.readthedocs.io. @@ -50,7 +50,7 @@ References .. [Ross00] Rossman, L.A. (2000). EPANET 2 Users Manual. Cincinnati, OH: U.S. Environmental Protection Agency. U.S. Environmental Protection Agency Technical Report, EPA/600/R--00/057, 200p. -.. [rtree] Toblerity/rtree. (n.d.). Retrieved on March 17, 2022 from https://github.com/Toblerity/rtree +.. [rtree] Toblerity/rtree. (n.d.). Retrieved on March 17, 2022 from https://github.com/Toblerity/rtree. .. [RWTS20] Rossman, L., Woo, H., Tryby M., Shang, F., Janke, R., and Haxton, T. (2020) EPANET 2.2 User Manual. U.S. Environmental Protection Agency, Washington, DC, EPA/600/R-20/133. @@ -70,7 +70,7 @@ References .. [WaWC06] Walski, T., Weiler, J. Culver, T. (2006). Using Criticality Analysis to Identify Impact of Valve Location. Water Distribution Systems Analysis Symposium. Cincinnati, OH, American Society of Civil Engineers: 1-9. -.. [WWQP06] Wald, D.J., Worden, B.C., Quitoriano, V., and Pankow, K.L. (2006). ShakeMap manual: Technical manual, user's guide, and software guide. United States Geologic Survey, Retrieved on April 25, 2017 from http://pubs.usgs.gov/tm/2005/12A01/ +.. [WWQP06] Wald, D.J., Worden, B.C., Quitoriano, V., and Pankow, K.L. (2006). ShakeMap manual: Technical manual, user's guide, and software guide. United States Geologic Survey, Retrieved on April 25, 2017 from http://pubs.usgs.gov/tm/2005/12A01/. .. [WCSG03] Walski, T.M., Chase, D.V., Savic, D.A., Grayman, W., Beckwith, S. (2003). Advanced Water Distribution Modeling and Management. HAESTAD Press, Waterbury, CT, 693p. diff --git a/documentation/resilience.rst b/documentation/resilience.rst index 74e8c11ca..080cfb1f8 100644 --- a/documentation/resilience.rst +++ b/documentation/resilience.rst @@ -74,7 +74,7 @@ WNTR includes additional topographic metrics to help compute resilience. measure of the number of branches in a network. A node with degree 0 is not connected to the network. Terminal nodes have degree 1. A node connected to every node (including itself) has a degree equal to the number of nodes in the network. - The average node degree is a system wide metric used to describe the number of + The average node degree is a system-wide metric used to describe the number of connected links in a network. Link density Link density is the ratio between the total number of links and the maximum @@ -114,7 +114,7 @@ WNTR includes additional topographic metrics to help compute resilience. Shortest path lengths Shortest path lengths is the minimum number of links between a source node and all other nodes in the network. Shortest path length is a value between 0 and the number of links in the network. - The average shortest path length is a system wide metric used to describe the number + The average shortest path length is a system-wide metric used to describe the number of links between a node and all other nodes. Valve segmentation Valve segmentation groups links and nodes into segments based on the location of isolation valves. @@ -343,7 +343,7 @@ The following examples compute hydraulic metrics, including: >>> pressure_above_threshold = wntr.metrics.query(pressure, np.greater, ... threshold) -* Water service availability (Note that for Net3, the simulated demands are never less than the expected demand, and water service availability is always 1 (for junctions that have positive demand) or NaN (for junctions that have demand equal to 0). +* Water service availability [Note that for Net3, the simulated demands are never less than the expected demand, and water service availability is always 1 (for junctions that have positive demand) or NaN (for junctions that have demand equal to 0)]. .. doctest:: @@ -483,7 +483,7 @@ The following examples use the results from the chemical water quality simulatio >>> flowrate = results.link['flowrate'].loc[:,wn.pipe_name_list] >>> EC = wntr.metrics.extent_contaminant(quality, flowrate, wn, detection_limit) -* Population impacted by mass consumed over a specified threshold. +* Population impacted by mass consumed over a specified threshold .. doctest:: diff --git a/documentation/users.rst b/documentation/users.rst index d1c987adb..3073c43b3 100644 --- a/documentation/users.rst +++ b/documentation/users.rst @@ -36,9 +36,9 @@ Publications * Antonowicz, A., & Urbaniak, A. (2022). Optimization of the process of restoring the continuity of the WDS based on the matrix and genetic algorithm approach. Bulletin of the Polish Academy of Sciences: Technical Sciences, e141594-e141594. -* Bjerke, M. (2019). Leak Detection in Water Distribution Networks using Gated Recurrent Neural Networks, Master's thesis, Norwegian University of Science and Technology (NTNU) +* Bjerke, M. (2019). Leak Detection in Water Distribution Networks using Gated Recurrent Neural Networks, Master's thesis, Norwegian University of Science and Technology (NTNU). -* Bunn, B. B. (2018). An operational model of interdependent water and power distribution infrastructure systems. Naval Postgraduate School, Monterey, CA +* Bunn, B. B. (2018). An operational model of interdependent water and power distribution infrastructure systems. Naval Postgraduate School, Monterey, CA. * Fan, X., Zhang, X., & Yu, X. B. (2021). Machine learning model and strategy for fast and accurate detection of leaks in water supply network. Journal of Infrastructure Preservation and Resilience, 2(1), 1-21. @@ -62,7 +62,7 @@ Publications * Marlim, M. S., & Kang, D. (2022). Contaminant Flushing in Water Distribution Networks Incorporating Customer Faucet Control. Sustainability, 14(4), 2249. -* Mazumder, R. K., Salman, A. M., Li, Y., & Yu, X. (2019). A Decision-making Framework for Water Distribution Systems using Fuzzy Inference and Centrality Analysis. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, Seoul, South Korea, May 26-30, 2019 +* Mazumder, R. K., Salman, A. M., Li, Y., & Yu, X. (2019). A Decision-making Framework for Water Distribution Systems using Fuzzy Inference and Centrality Analysis. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13, Seoul, South Korea, May 26-30, 2019. * Mazumder, R. K., Salman, A. M., & Li, Y. (2020). Post-disaster sequential recovery planning for water distribution systems using topological and hydraulic metrics. Structure and Infrastructure Engineering, 1-16. @@ -84,9 +84,9 @@ Publications * Randeniya, A., Radhakrishnan, M., Sirisena, T. A. J. G., Maish, I., & Pathirana, A. (2022). Equity–performance trade-off in water rationing regimes with domestic storage. Water Supply, 22(5), 4781-4797. -* Sharma, N., Tabandeh, A., & Gardoni, P. (2019). Recovery optimization of interdependent infrastructure: a multi-scale approach. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13 +* Sharma, N., Tabandeh, A., & Gardoni, P. (2019). Recovery optimization of interdependent infrastructure: a multi-scale approach. 13th International Conference on Applications of Statistics and Probability in Civil Engineering, ICASP13. -* Sharma, N., Tabandeh, A., & Gardoni, P. (2020). Regional resilience analysis: A multiscale approach to optimize the resilience of interdependent infrastructure. Computer‐Aided Civil and Infrastructure Engineering, 35(12), 1315-1330. +* Sharma, N., Tabandeh, A., & Gardoni, P. (2020). Regional resilience analysis: A multiscale approach to optimize the resilience of interdependent infrastructure. Computer-Aided Civil and Infrastructure Engineering, 35(12), 1315-1330. * Tabandeh, S. (2018). Societal risk and resilience analysis: A multi-scale approach to model the dynamics of infrastructure-social systems (Doctoral dissertation, University of Illinois at Urbana-Champaign). diff --git a/documentation/waterquality.rst b/documentation/waterquality.rst index bdc261fac..fa784d531 100644 --- a/documentation/waterquality.rst +++ b/documentation/waterquality.rst @@ -133,7 +133,7 @@ In the example below, the strength of the source is changed from 1000 to 1500. When creating a water network model from an EPANET INP file, the sources that are defined in the [SOURCES] section are added to the water network model. -These sources are given the name 'INP#' where # is an integer related to the number of sources in the INP file. +These sources are given the name 'INP#' where # is an integer representing the number of sources in the INP file. .. The following is not shown in the UM _wq_pdd: