Release notes

v0.4.0 (August 26, 2021)

  • Changed the following network component attributes:

    • Pipe check_valve_flag and cv attributes were merged and renamed check_valve

    • Pipe, Valve, and Pump status now refers to the current simulation status and is read-only, the user can set the initial status using initial_status

    • Valve setting now refers to the current simulation setting and is read-only, the user can set the initial setting using initial_setting

  • 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 wn.options.user.

  • Added a FunctionCondition which 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 setting.

  • Updated the WNTRSimulator to use wn.options.time.start_clocktime.

  • 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 wn.options.hydraulic.required_pressure).

  • 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)

  • The run_sim method for the EpanetSimulator now includes the option to define convergence error behavior.

    • If the simulation does not converge and convergence_error is True, an error is raised.

    • If the simulation does not converge and convergence_error is False, partial results are returned, a warning is issued, and results object error_code is set to 0.

    The default setting for convergence_error when using the EpanetSimulator is False.

  • The default setting for convergence_error in the WNTRSimulator was changed to False.

  • Updated the add_outage method on pumps so it can be used with the EpanetSimulator. Added a remove_outage method on pumps.

  • Added a convert_controls_to_rules method 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.

  • Updated the expected_demand and average_expected_demand metrics 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_network that plot valve layers.

  • Added a function to generate a randomly ordered colormap (random_colormap). Updated custom_colormap so that the number of bins is not an optional argument.

  • Added pressure_exponent to 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.

  • Changed plot_network to 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).

  • The pump_cost function was updated to use pump energy, instead of recomputing those values.

  • Bug fix in the pump_energy calculation 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 at method.

  • 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.solver are now in wn.options.hydraulic

    • Reaction options that were in wn.options.quality now stored in wn.options.reactions

    • wn.options.quality.mode is now wn.options.quality.quality.parameter

    • wn.options.hydraulic.units has been updated to wn.options.hydraulic.inpfile_units to 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
      
    • Junction attributes required_pressure and minimum_pressure are 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_pressure was changed to required_pressure to 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_exponent to 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 support for tank volume curves in the WNTRSimulator. Tank volume curves are also now used in annual_network_cost. Tank curves can also be visualized using the function plot_tank_volume_curve.

  • Added method to get tank volume at a given level get_volume.

  • Added Travis CI tests for Python 3.8

  • Updated tests

  • Updated documentation

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, write

  • 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.

  • Updated tests

  • Updated documentation

v0.2.2.1 (June 16, 2020)

  • Fixed 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

  • Updated tests

  • Updated documentation

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).

    • get_graph now returns a NetworkX MultiDiGraph. That method can also be used to return a weighted graph. The method weighted_graph has been removed.

    • Topographic metrics that were part of the WntrMultiDiGraph class are now located in the topographic module.

  • Added valve_segments method to groups links and nodes into segments based on the location of isolation valves.

  • Added generate_valve_layer method to generate valve layers based on random or strategic placement.

  • Updated plot_pump_curve to 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.

  • Updated plot_fragility_curve and plot_pump_curve to 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_network to add labels to node and link colorbars.

  • Added optional input argument for detection limit to mass_contaminant_consumed calculation. 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)

  • Updated documentation

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

    • PSV valves

    • 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

  • 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.

  • Updated query_node_attribute and query_link_attribute to return a pandas Series instead of a dictionary (API change)

  • Added describe to 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 tests

  • 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.

  • Updated documentation.

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.

  • Updated documentation.

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

  • Updated controls classes to include Control and Rule objects (API change, see Control and Rule)

  • Added ability to get the names of all required objects that are queried or acted upon by the control/rule (see requires)

  • Modified the structure of the Options object to group options into types (API change, see Options)

  • Created water network model objects for different types of valves (see PRValve, PSValve, PBValve, FCValve, TCValve, and GPValve) and pumps (see HeadPump and PowerPump)

  • Created a Pattern object that contains a list of values (see Pattern)

    • 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)

    • 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)

    • 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.

    • Expected demand and average daily expected demand can be calculated using new metrics (see expected_demand and average_expected_demand). The metric ‘average_water_consumed’ has been removed.

  • 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 get_graph).

  • 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 binary_pattern).

  • Added ENsaveinpfile to the EPANET toolkit (see ENsaveinpfile)

  • Updated documentation

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 plot_network)

  • Changed argument in the WNTRSimulator specifying demand-driven or pressure dependent demand (API change, see WNTRSimulator)

  • 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)

  • Updated documentation

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.

  • Updated documentation

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

  • Updated documentation

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