Model I/O

The following section describes data and file formats that can used for 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 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 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 Net3 has no valves and 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 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. 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 GIS platforms for further analysis and visualization.

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

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

  • Net3_junctions.geojson

  • Net3_tanks.geojson

  • Net3_reservoirs.geojson

  • Net3_pipes.geojson

  • Net3_pumps.geojson

  • Note, 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 a 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, pumps, and valves:

  • Net3_junctions

  • Net3_tanks

  • Net3_reservoirs

  • Net3_pipes

  • Net3_pumps

  • Note, 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 a methods on the WaterNetworkGIS object.