Model I/O

The following section describes the data and file formats that can used for the WaterNetworkModel input and output (I/O).

EPANET INP file

The read_inpfile function builds a WaterNetworkModel from an EPANET INP file. The EPANET INP file can be in the EPANET 2.00.12 or 2.2.0 format. The function can also be used to append information from an EPANET INP file into an existing WaterNetworkModel.

>>> import wntr

>>> wn = wntr.network.read_inpfile('networks/Net3.inp')

Note

The WaterNetworkModel can also be created from an EPANET INP file as shown below. This is equivalent to using the read_inpfile function.

>>> wn = wntr.network.WaterNetworkModel('networks/Net3.inp')

The write_inpfile function creates an EPANET INP file from a WaterNetworkModel. By default, files are written in the LPS (liter per second) EPANET unit convention. The EPANET INP file will not include features not supported by EPANET (i.e., custom element attributes). EPANET INP files can be saved in the EPANET 2.00.12 or 2.2.0 format.

>>> wntr.network.write_inpfile(wn, 'filename.inp', version=2.2)

Dictionary representation

The to_dict function creates a dictionary from a WaterNetworkModel. The dictionary contains the following keys:

  • nodes (which contains junctions, tanks, and reservoirs)

  • links (which contains pipes, pumps, and valves)

  • patterns

  • curves

  • sources

  • controls

  • options

Each of these entries contains a dictionary or list of dictionaries with keys corresponding to object attributes. A small subset of the dictionary is printed below.

>>> wn_dict = wntr.network.to_dict(wn)
>>> wn_dict['links'][0] 
    {'name': '20', 'link_type': 'Pipe', 'start_node_name': '3', 'end_node_name': '20', ...

The from_dict function is used to create a WaterNetworkModel from a dictionary. Dictionary representations of the model are always written in SI units (m, kg, s). The function can also be used to append information from a dictionary into an existing WaterNetworkModel.

>>> wn2 = wntr.network.from_dict(wn_dict)

Note

to_dict and from_dict are also methods on the WaterNetworkModel.

GeoDataFrame representation

The to_gis function is used to create a collection of GeoDataFrames from a WaterNetworkModel. The collection of GeoDataFrames is stored in a WaterNetworkGIS object which contains a GeoDataFrame for each of the following model components:

  • junctions

  • tanks

  • reservoirs

  • pipes

  • pumps

  • valves

Note that patterns, curves, sources, controls, and options are not stored in the GeoDataFrame representation. See Geospatial capabilities for more information on the the WaterNetworkGIS object and the use of GeoDataFrames in WNTR.

>>> wn_gis = wntr.network.to_gis(wn)

Individual GeoDataFrames are obtained as follows (Note that the example network, Net3, has no valves and thus the GeoDataFrame for valves is empty).

>>> wn_gis.junctions 
>>> wn_gis.tanks 
>>> wn_gis.reservoirs 
>>> wn_gis.pipes 
>>> wn_gis.pumps 
>>> wn_gis.valves

The from_gis function is used to create a WaterNetworkModel object from a collection of GeoDataFrames. The GeoDataFrames can either be stored in a WaterNetworkGIS object or in a dictionary with keys for each model component (junctions, tanks, reservoirs, pipes, pumps, and valves). The function can also be used to append information from GeoDataFrames into an existing WaterNetworkModel.

>>> wn2 = wntr.network.from_gis(wn_gis)

A WaterNetworkModel created from GeoDataFrames only contains the junction, tank, reservoir, pipe, pump, and valve attributes and topographic connectivity of the network. The network will not contain patterns, curves, rules, controls, or sources. The water network model options are set to default values. Additional functionality could be added to WNTR in a future release.

Note

to_gis and from_gis are also methods on the WaterNetworkModel.

Graph representation

The to_graph method is used to create a NetworkX graph from a WaterNetworkModel. See NetworkX graph for more information on the use of NetworkX graphs in WNTR.

>>> G = wntr.network.to_graph(wn)

The ability to create a WaterNetworkModel from a NetworkX graph could be added in a future version of WNTR.

Note

to_graph is also a method on the WaterNetworkModel.

JSON file

The write_json function writes a JSON (JavaScript Object Notation) file from a WaterNetworkModel. The JSON file is a formatted version of the dictionary representation.

>>> wntr.network.write_json(wn, 'Net3.json')

The read_json function creates a WaterNetworkModel from a JSON file. The function can also be used to append information from a JSON file into an existing WaterNetworkModel.

>>> wn2 = wntr.network.read_json('Net3.json')

Note that these methods do not check for a valid dictionary/JSON schema prior to building a model. They simply ignore extraneous or invalid dictionary keys.

GeoJSON files

The write_geojson function writes a collection of GeoJSON files from a WaterNetworkModel. The GeoJSON files can be loaded into geographic information system (GIS) platforms for further analysis and visualization.

>>> wntr.network.write_geojson(wn, 'Net3')

This creates the following GeoJSON files for junctions, tanks, reservoirs, pipes, and pumps:

  • Net3_junctions.geojson

  • Net3_tanks.geojson

  • Net3_reservoirs.geojson

  • Net3_pipes.geojson

  • Net3_pumps.geojson

A GeoJSON file for valves, Net3_valves.geojson, is not created since Net3 has no valves. Note that patterns, curves, sources, controls, and options are not stored in the GeoJSON files.

The read_geojson function creates a WaterNetworkModel from a dictionary of GeoJSON files. The function can also be used to append information from GeoJSON files into an existing WaterNetworkModel.

>>> geojson_files = {'junctions': 'Net3_junctions.geojson',
...                  'tanks': 'Net3_tanks.geojson',
...                  'reservoirs': 'Net3_reservoirs.geojson',
...                  'pipes': 'Net3_pipes.geojson',
...                  'pumps': 'Net3_pumps.geojson'}
>>> wn2 = wntr.network.read_geojson(geojson_files)

Note

write_geojson and read_geojson are also methods on the WaterNetworkGIS object.

Shapefile files

The write_shapefile function creates Shapefile files from a WaterNetworkModel. The Shapefiles can be loaded into GIS platforms for further analysis and visualization.

>>> wntr.network.write_shapefile(wn, 'Net3')

This creates the following Shapefile directories for junctions, tanks, reservoirs, pipes, and pumps:

  • Net3_junctions

  • Net3_tanks

  • Net3_reservoirs

  • Net3_pipes

  • Net3_pumps

A Shapefile for valves, Net3_valves, is not created since Net3 has no valves. Note that patterns, curves, sources, controls, and options are not stored in the Shapefile files.

The read_shapefile function creates a WaterNetworkModel from a dictionary of Shapefile directories. The function can also be used to append information from Shapefiles into an existing WaterNetworkModel.

>>> shapefile_dirs = {'junctions': 'Net3_junctions',
...                   'tanks': 'Net3_tanks',
...                   'reservoirs': 'Net3_reservoirs',
...                   'pipes': 'Net3_pipes',
...                   'pumps': 'Net3_pumps'}
>>> wn2 = wntr.network.read_shapefile(shapefile_dirs)

Note

write_shapefile and read_shapefile are also methods on the WaterNetworkGIS object.