v1.0.0 (March 30, 2023)¶
WNTR version 1.0.0 has undergone extensive testing with a wide range of water distribution system models and analysis options. The software has also successfully been used by external research groups and in analysis that uses large-scale water distribution system models. See User community for a list of publications and software that uses WNTR.
Updated copyright and added EPANET license #336.
Updated the setup process and documentation #335.
Bug fix to allow for np.float and np.int in type checking #334.
Updated environment variable for CIBW_ENVIRONMENT to build extensions. #316.
v0.5.0 (November 17, 2022)¶
Convert between water network models and GIS formatted data (GeoPandas GeoDataFrames) and GIS formatted files (GeoJSON and Shapefiles)
Snap GeoPandas point data to elements in a water network model
Find the intersection between GeoPandas points, line or polygons and elements in a water network model
Set and convert GeoDataFrame coordinate reference systems
See Geospatial capabilities section of the user manual for more information.
Removed the read_inpfile, write_inpfile, read_json, and write_json methods from the WaterNetworkModel. This functionality is still available using wntr.network.read_inpfile, wntr.network.write_inpfile, wntr.network.read_json and wntr.network.write_json and is located with other read/write functions #302.
WaterNetworkModel method get_graph renamed to_graph. Deprecation warning added.
Added additional options to the EPANET toolkit, including the ability to set size limits and hydraulic initialization. Added additional functions, including ENgetnodeid, ENgetnodetype, and ENgetlinktype. #298
The _evaluator and _network_isolation binaries are no longer distributed with the code. The setup.py file now includes an optional argument to build the binaries. Developer installation instructions have been updated. #294, #305, #311, #313, #314
Bug fix in pump cost metric #306
Bug fix in rules when link is active #301
v0.4.2 (June 23, 2022)¶
v0.4.1 (March 2, 2022)¶
Added a function to compute the modified resilience index,
wntr.metrics.modified_resilience_index. The modified resilience index is a measure of total surplus power. The metric can be computed as a timeseries for each junction or as a system average timeseries. #226
Added a function to compute tank capacity,
wntr.metrics.tank_capacity. Tank capacity is the ratio of water volume to the maximum water volume for each tank and is reported as a timeseries. #226
Added functionality to convert the water network model to a dictionary or JSON formatted file and create a water network model from a dictionary or JSON formatted file. The new functionality is located in
read_json. These can also be called using methods on the WaterNetworkModel object. #233
Updated the WNTRSimulator to use
Added the ability to set the random seed when sampling damage states from fragility curves. #246
Added methods to update parameters used to define rules and controls. #241
wntr.morph.break_pipeto include pipe vertices. #248
Updated the EpanetSimulator to be thread safe (only available for EPANET version 2.2). #236
Updated rules parsing mechanism for the EPANET INP files. #228
Added an assert statement to ensure that the hydraulic, quality, pattern and rule timesteps are an integer and are not less than 1 second. #229
Added the Jupyter Notebook demos into the testing framework. #237
Fixed assert statement in add_tank to check for bool, str, or int #251
Corrected text in the time series string representation. #238
Removed private attribute on pumps associated with power outage controls which is no longer needed. #225
v0.4.0 (August 26, 2021)¶
Changed the following network component attributes:
cvattributes were merged and renamed
Pipe, Valve, and Pump
statusnow refers to the current simulation status and is read-only, the user can set the initial status using
settingnow refers to the current simulation setting and is read-only, the user can set the initial setting using
Added slots to water network model options,
wn.options, to define available option names. This update helps eliminate the use of incorrect or deprecated options. The user can still create custom options under
FunctionConditionwhich calls a function to determine if a control needs activated or not. If the function returns True, then the control is activated. This class is used internally to check if valves are connected to an upstream or downstream source (reservoir or tank). The class can also be used directly to define custom controls.
Added the ability to use pattern interpolation when running the WNTRSimulator (
wn.options.time.pattern_interpolation) Interpolation with a shorter hydraulic timestep can make problems with large changes in patterns (e.g., large changes in demand) easier to solve. By default, the same step-like behavior from EPANET is used.
Removed custom handlers from the EPANET bin filer reader.
Added a metric to compute pump energy
Added type checking for input into wn.add_* methods.
Updated the WNTRSimulator link results to include
Updated the WNTRSimulator to use
Updated Net 1, Net 2, and Net 3 network model files to match EPANET versions. The network files were updated to include a tank overflow entry and 3 digit coordinates. Hydraulic, water quality, and reporting timestep were also updated in Net 3.
Bug fix in io to differentiate between PRESSURE EXPONENT and PRESSURE hydraulic options.
Bug fix to enforce EPANET lower limit for required pressure (0.1 in psi or m). If the user sets a lower limit below 0.1 m, the value of 0.1 m is used in the INP file and a warning is issued. Note, the lower limit is also the default value in EPANET (and therefore the default for
Updated documentation example that creates a weighted graph.
Updated all tests to use unittest. Removed Travis CI testing framework, all tests are run through GitHub Actions.
v0.3.1 (June 16, 2021)¶
run_simmethod for the EpanetSimulator now includes the option to define convergence error behavior.
If the simulation does not converge and
convergence_erroris True, an error is raised.
If the simulation does not converge and
convergence_erroris False, partial results are returned, a warning is issued, and results object
error_codeis set to 0.
The default setting for
convergence_errorwhen using the EpanetSimulator is False.
The default setting for
convergence_errorin the WNTRSimulator was changed to False.
add_outagemethod on pumps so it can be used with the EpanetSimulator. Added a
remove_outagemethod on pumps.
convert_controls_to_rulesmethod on the water network model. In some instances, mixing controls and rules has unexpected consequences. By converting all controls to rules, the user can specify the priority for each rule.
average_expected_demandmetrics to optionally specify a demand category.
Added a function to compute valve segment attributes from a valve layer (
valve_segment_attributes). This includes the number of valves surrounding each valve, the increase in segment demand if a given valve is removed, and the increase in segment pipe length if a given valve is removed.
Added graphics options to plot valve layers and valve segment attributes (
plot_valve_layer). Removed options in
plot_networkthat plot valve layers.
Added a function to generate a randomly ordered colormap (
custom_colormapso that the number of bins is not an optional argument.
pressure_exponentto junction properties. This allows the user to define pressure exponents that vary throughout the network (used only by the WNTRSimualtor). Similar attributes exist to define minimum and required pressure on each junction. By default, each junction’s pressure exponent is set to None and the global value in the hydraulic options are used to define the PDD constraint for that junction.
Updated controls to create speed rules for pumps.
plot_networkto return a matplotlib axes object rather than networkx nodes and edges objects. This helps use the axes to layer additional data (such as valve segment attributes).
pump_costfunction was updated to use pump energy, instead of recomputing those values.
Bug fix in the
pump_energycalculation and added additional tests. The function, which was returning power in Watts, now returns energy in Joules.
Bug fix for value controls read in from EPANET INP files. Key words ABOVE and BELOW had been assigned to >= and <=, respectively. This was changed to > and <, respectively.
Bug fix for plotting directed networks with a colorbar
Bug fix for patterns, pattern start was doubly counted in the
Added NotImplementedError for D-W and C-M headloss when using the WNTRSimualtor.
Suppressed the OptimizeWarning from scipy.optimize that often occurs when fitting a pump curve. This is not an error.
Updated network component attributes that store simulation results to be read-only.
Changed results object names for friction factor (
friction_factor), link quality (
quality), and reaction rate (
reaction_rate) to match names used in EPANET.
Updated API documentation to include a table of class properties for each network class (Junction, Tank, Pipe, etc.).
Added support for Python 3.9
v0.3.0 (November 2, 2020)¶
Added EPANET 2.2.0 as the default engine in the EpanetSimulator.
When creating a WaterNetworkModel,
wn, from an EPANET INP file, the DEMAND MODEL, MINIMUM PRESSURE, and REQUIRED PRESSURE along with other options are used to populate the WaterNetworkModel. These options are stored in
wn.options. These options are also used when writing an INP file. INP files created using EPANET 2.00.12 are compatible with this update.
The option to run demand-driven and pressure dependent demand analysis is stored in
wn.options.hydraulic.demand_model. If no demand model is specified, demand-driven analysis is used. Note, demand-driven analysis can be specified as DD or DDA and pressure dependent demand analysis can be specified as PDA or PDD to maintain compatibility with EPANET 2.2.0:
wn.options.hydraulic.demand_model = 'DD' # specify demand-driven analysis wn.options.hydraulic.demand_model = 'PDD' # specify pressure dependent demand analysis
The EPANET 2.2.0 binaries for Mac and PC come from the Open Water Analytics EPANET 2.2.0 repository (https://github.com/OpenWaterAnalytics/EPANET). The Linux binary was built on Ubuntu and comes from the OWA group using the same source as the Windows and Mac binaries.
The user can switch between EPANET version 2.00.12 and 2.2.0 as shown below:
sim = wntr.sim.EpanetSimulator(wn) results1 = sim.run_sim(version=2.0) # results using EPANET 2.00.12 results2 = sim.run_sim(version=2.2) # results using EPANET 2.2.0
EPANET 2.00.12 only runs demand-driven analysis
Certain WaterNetworkModel option names have been updated to better align with EPANET nomenclature (API change). Key changes are noted below:
Hydraulics options that were in
wn.options.solverare now in
Reaction options that were in
wn.options.qualitynow stored in
wn.options.hydraulic.unitshas been updated to
wn.options.hydraulic.inpfile_unitsto make it clear that these units are only used when writing an INP file
The following changes were made to handle new options in EPANET 2.2.0 INP files.
If the WaterNetworkModel is created from a EPANET 2.2.0 INP file, the global hydraulic options for required and minimum pressure are defined from the REQUIRED PRESSURE and MINIMUM PRESSURE in the INP file. The default values used in EPANET are shown below:
wn.options.hydraulic.required_pressure = 0.07 # 0.1 psi = 0.07 m wn.options.hydraulic.minimum_pressure = 0
minimum_pressureare set to None by default and the global hydraulic options are used in the WNTRSimulator. If the user defines required pressure or minimum pressure on a junction, that value will override the global value when using the WNTRSimulator. Note that junction attribute
nominal_pressurewas changed to
required_pressureto better align with EPANET nomenclature (API change).
Tanks attributes include an indicator for tank overflow. This can be used in the EpanetSimulator using EPANET 2.2.
The keyword argument mode has been removed from the WNTRSimulator. DD and PDD are now defined using
wn.options.hydraulic.demand_model(as shown above) to make use of the new EPANET 2.2.0 options (API change). If the WaterNetworkModel is created from a EPANET 2.2.0 INP file, this option is defined from the DEMAND MODEL in the INP file.
The WNTRSimulator uses the exponent defined in
wn.options.hydraulic.pressure_exponentto model the PDA pressure-demand relationship. The exponent had been set to 0.5 before, and could not be modified through options. If the WaterNetworkModel is created from a EPANET 2.2.0 INP file, this option is defined from the PRESSURE EXPONENT in the INP file.
While the WaterNetworkModel can store spatially variable minimum and required pressure that are used in the WNTRSimulator, those values cannot be saved when writing an INP file, rather the minimum and required pressure values in the options are saved. This impacts the ability to use those junction attributes in the EpanetSimulator. This note has been added to the Discrepancies section of the user manual.
Added support for multi-point pump curves in the WNTRSimulator. The points are fit to the same function that is used for 3-point curves.
Added method to get tank volume at a given level
Added Travis CI tests for Python 3.8
v0.2.3 (September 4, 2020)¶
Fixed bug in
reset_initial_values. The method now resets controls and additional network attributes needed to reset the model to initial conditions.
Fixed bug for valve settings in the EPANET INP file writer,
Fixed bug in emitter coefficient unit conversion
Included conda install instructions
Added methods to add and remove fire fighting demand to a junction
Added pipe criticality and fire flow examples
Minor updates to support NetworkX 2.5
Added binaries for Python 3.8
Added testing capabilities through GitHub Actions. This includes a quick check run on Linux using Python 3.8 and a complete build run on Windows, Linux, and MacOS using Python 3.6, 3.7 and 3.8. The GitHub Action tests are initiated after push and pull requests to the master and dev branches.
v0.2.2.1 (June 16, 2020)¶
assign_demand. The function now reassigns demands using the demand_timeseries_list and uses the demand multiplier to create a new pattern.
Fixed issues in WNTRSimulator controls, including
Fixed a bug in tank controls that are used when a pipe entering/leaving the tank has a CV
Fixed a bug in the PSV headloss constraint, which now uses elevation at the start node
Added a tolerance threshold to ValueCondition and TankLevelCondition
Added a tolerance threshold to the condition that activates FCV
v0.2.2 (March 23, 2020)¶
WntrMultiDiGraph class has been removed and WNTR now uses the NetworkX MultiDiGraph class directly. Methods associated with WntrMultiDiGraph have been relocated (API change).
valve_segmentsmethod to groups links and nodes into segments based on the location of isolation valves.
generate_valve_layermethod to generate valve layers based on random or strategic placement.
plot_pump_curveto include the pump curve based on head curve coefficients, the optional input argument add_polyfit was removed (API change). Bug fix in x and y labels.
plot_pump_curveto use an existing matplotlib axes and return a matplotlib axes so users can customize the graphics. The optional input argument figsize was removed (API change).
Added optional input arguments to
plot_networkto add labels to node and link colorbars.
Added optional input argument for detection limit to
mass_contaminant_consumedcalculation. The default detection limit for mass consumed, volume consumed, and extent of contamination is 0.
Efficiency updates for skeletonize and other network morphology functions. The functions can now make changes to the original water network model or a deepcopy of the model.
Added NotImplementedErrors for PBV and GPV valves, when using the WNTRSimualtor
Updated methods to be compatible with NetworkX 2.4 and Pandas 1.0
Added required dependencies to setup.py. Required and optional dependencies are included in requirements.txt
Dropped testing for Python 3.5 (matplotlib requires Python >= 3.6)
v0.2.1 (Aug 13, 2019)¶
Added a c++ extension module for algebraic modeling to facilitate model development and maintenance. This module
makes modeling relatively easy but still enables efficient constraint and jacobian evaluations.
reduces the burden of code maintenance.
makes the WNTRSimulator more flexible.
Added a c++ extension module for efficiently detecting portions of the network that are isolated from tanks and reservoirs.
Support was added in the WNTRSimulator for
Global demand multipliers
Improved the flexibility of controls by adding a ControlManager object. This object tracks changes and ensures that the hydraulic model gets updated appropriately.
Updated the controls for valves to improve the robustness of the WNTRSimulator. These changes ensure that, for example, when all of the downstream links of a PSV are closed, the PSV gets opened or closed appropriately.
Fixed a bug in the start_node and end_node properties for links
Fixed a bug in the controls for PRVs
Flushed out missing WaterNetworkModel methods (e.g., prv_name_list)
Dropped support and testing for Python 2
Updated tests (primarily added new tests for the new c++ extension module for algebraic modeling)
Added Appveyor testing
Updated documentation for the new algebraic modeling module
Added conda-forge distribution mechanism
v0.1.7 (July 23, 2019)¶
Added a module for network morphology (see
morph), which includes methods to
Reduce network size through skeletonization (see
Note that methods to scale node coordinates and split pipes used to reside on the water network model object (API change)
Added additional graphics options, including:
Fixed bugs in network cost, average expected demand, population, and spectral gap metrics.
Fixed bug in reading initial water quality from INP files.
Added a read-only base_demand attribute to junctions. Base demand is defined using the first demand in the demand_timeseries_list.
describeto return the number of links, nodes, patterns, etc in a WaterNetworkModel
Added a pull request template.
Dropped Travis CI tests for Python 3.4
Added Travis CI tests for Python 3.7
Updated documentation, including installation instructions and a section on network morphology and graphics. Removed example files and integrated code examples directly into the documentation.
v0.1.6 (September 11, 2018)¶
Introduced a known discrepancy between the WNTRSimulator and EpanetSimulator to model pump speed controls. See Discrepancies.
Pumps have speed settings which are adjustable by controls and/or patterns. With the EpanetSimulator, controls and patterns adjust the actual speed. With the WNTRSimulator, pumps have a ‘base speed’ (similar to junction demand and reservoir head), controls adjust the base speed, and speed patterns are a are a multiplier on the base speed. Results from the two simulators can match by scaling speed patterns and using controls appropriately.
Fixed bugs in the EPANET INP file reader/writer that impacted some model files, including issues with time controls, pump price and pattern, general purpose valves, and the demand section.
Included constant power pumps in annual network cost metric.
Updated the way hydraulic and reporting timesteps are handled. If the reporting timestep is greater than the hydraulic timestep, then it is reset and a warning message is raised.
Restricted software tests to use Plotly version 2.x. Plotly version 3 is not yet compatible with network graphics.
v0.1.5 (May 29, 2018)¶
Replaced the use of Pandas Panels with a dictionary of Pandas DataFrames (Pandas is deprecating Panels). This changes the way users interact with simulation results.
Removed ‘expected_demand’ and ‘type’ from simulation results. Expected demand can be computed using
expected_demand. Node and link type is stored in the WaterNetworkModel and is no longer used to compute metrics.
Removed simulation_results example, example code is now embedded in the documentation.
Updated metrics to use simulation results in the new format and to clarify names.
Input arguments are now more explicit, e.g. pass a DataFrame with junction demands instead of an entire Panel with information that might not be used.
Updated the following metric names: changed fdv (fraction of delivered volume) to water_service_availability, todini to todini_index, cost to annual_network_cost, ghg_emissions to annual_ghg_emissions.
Removed the following metrics: fdd (fraction of delivered demand) and fdq (fraction of delivered quality), these can be computed with simple queries on demand and quality simulation results.
Improved error messages when simulation does not converge.
Updated default options for the WNTRSimulator.
Bug fix in node registries for the use of patterns.
Changed default colormap in network graphics from jet to Spectral_r.
v0.1.4 (February 23, 2018)¶
v0.1.4 includes several changes that improve simulation stability and tests to ensure that simulations run using WNTR match EPANET simulations. In addition to the publicly available software tests on https://travis-ci.org/sandialabs/WNTR, WNTR is also tested on private servers using several large water utility network models.
Added a faster EPANET binary output file reader
Updated the order in which controls operate to match EPANET
Added ability to get the names of all required objects that are queried or acted upon by the control/rule (see
Modified the structure of the Options object to group options into types (API change, see
Created a Pattern object that contains a list of values (see
A Pattern object can be called to get the pattern value at a specific time
Created a TimeSeries object that contains a base value, Pattern object, and category (see
TimeSeries are used to store junction demand, source injection, pricing, pump speed, and reservoir head
A TimeSeries object can be called to get the timeseries value at a specific time
Created a Demands object to store a list of TimeSeries objects (see
Demands are used to store multiple demands at a single junction
A Demands object can be called to get the total demand at a specific time (does not include the demand multiplier)
Since a junction can have multiple demands, ‘base_demand’ is no longer a Junction attribute (API change). The Demands object can be used to extract the base value per demand.
Added support for flow control valves (FCV), multiple demands at a junction, variable reservoir head, and rule timesteps in the WNTRSimulator
Modified the dependence between the WaterNetworkModel and the NetworkX graph. The graph is now built from scratch when WaterNetworkModel.get_graph() is called. WaterNetworkModel.get_graph_deep_copy() has been removed (API change, see
Modified the WaterNetworkModel.add_pattern() to no longer accept start_time and end_time options. Binary patterns can be created using the Patterns object (API change, see
Added ENsaveinpfile to the EPANET toolkit (see
v0.1.3 (October 3, 2017)¶
Added method to compute pump energy and cost
Added methods to plot fragility curves and pump curves
Bug fix to support 24-hour clocktime format and correct tank volume curve name in EPANET INP files
Added ability to create network graphics in subplots (API change, see
Changed argument in the WNTRSimulator specifying demand-driven or pressure dependent demand (API change, see
Updated use of NetworkX to be compatible v2.0
Bug fix in method used to split pipes. The updated method modifies the original pipe and retains rules and controls associated with that pipe. (API change, see
split_pipe, replaces split_pipe_with_junction)
v0.1.2 (May 19, 2017)¶
Improved EPANET INP file reader/writer with unit conversions
Added EPANET binary file reader
Improved model option handling with the EpanetSimulator
Added water network compatibility with EPANET INP file SOURCES and RULES
Restructured code base (API change)
Added epanet package which contains an epanet toolkit, EPANET INP file reader/writer, and unit conversions. Removed pyepanet package.
Added graphics package which contains functions to plot networks. Renamed draw_graph to plot_network. Added a function to create network graphics using Plotly.
Reorganized metrics, network, scenario, sim, and utils packages
Removed Waterquality class from the scenario package. This functionality has been replaced with Source class in the water network model.
v0.1.1 (February 6, 2017)¶
Updated package for Python 3.4 and 3.5 compatibility
Added install requirements to setup.py
Bug fix in animation example
v0.1.0 (October 17, 2016)¶
This is the first official release of WNTR. Features include basic functionality to:
Generate water network models
Modify network structure and operations
Add disruptive incident and response/repair strategies
Simulate network hydraulics using pressure dependent demand or demand-driven hydraulic simulation
Run probabilistic simulations using fragility curves
Compute resilience using topographic, hydraulic, water quality/security, and economic metrics
Analyze results and generate graphics