wntr.epanet.io module

The wntr.epanet.io module contains methods for reading/writing EPANET input and output files.

Contents

InpFile() EPANET INP file reader and writer class.
BinFile([result_types, network, energy, …]) EPANET binary output file reader class.

class wntr.epanet.io.InpFile[source]

Bases: object

EPANET INP file reader and writer class.

This class provides read and write functionality for EPANET INP files. The EPANET Users Manual provides full documentation for the INP file format.

Methods

read(inp_files[, wn]) Method to read an EPANET INP file and load data into a water network model object.
write(filename, wn[, units]) Write a water network model into an EPANET INP file.
read(inp_files, wn=None)[source]

Method to read an EPANET INP file and load data into a water network model object.

Parameters:
inp_files : str or list

An EPANET INP input file or list of INP files to be combined

Returns:
:class:`~wntr.network.model.WaterNetworkModel`

A water network model object

write(filename, wn, units=None)[source]

Write a water network model into an EPANET INP file.

Parameters:
filename : str

Name of the EPANET INP file.

units : str, int or FlowUnits

Name of the units being written to the EPANET INP file.

class wntr.epanet.io.BinFile(result_types=None, network=False, energy=False, statistics=False, convert_status=True)[source]

Bases: object

EPANET binary output file reader class.

This class provides read functionality for EPANET binary output files.

Parameters:
results_type : list of ResultType, default=None

If None, then all results will be saved (node quality, demand, link flow, etc.). Otherwise, a list of result types can be passed to limit the memory used. This can also be specified in a save_results_line call, but will default to this list.

network : bool, default=False

Save a new WaterNetworkModel from the description in the output binary file. Certain elements may be missing, such as patterns and curves, if this is done.

energy : bool, default=False

Save the pump energy results.

statistics : bool, default=False

Save the statistics lines (different from the stats flag in the inp file) that are automatically calculated regarding hydraulic conditions.

convert_status : bool, default=True

Convert the EPANET link status (8 values) to simpler WNTR status (3 values). By default, this is done, and the encoded-cause status values are converted simple state values, instead.

Returns:
:class:`~wntr.sim.results.SimulationResults`

A WNTR results object will be created and added to the instance after read.

Methods

finalize_save(good_read, sim_warnings) Post-process data before writing results.
read(filename[, custom_handlers]) Read a binary file and create a results object.
save_energy_line(pump_idx, pump_name, values) Save pump energy from the output file.
save_ep_line(period, result_type, values) Save an extended period set of values.
save_network_desc_line(element, values) Save network description meta-data and element characteristics.
setup_ep_results(times, nodes, links[, …]) Set up the results object (or file, etc.) for save_ep_line() calls to use.
setup_ep_results(times, nodes, links, result_types=None)[source]

Set up the results object (or file, etc.) for save_ep_line() calls to use.

The basic implementation sets up a dictionary of pandas DataFrames with the keys being member names of the ResultsType class. If the items parameter is left blank, the function will use the items that were specified during object creation. If this too was blank, then all results parameters will be saved.

save_ep_line(period, result_type, values)[source]

Save an extended period set of values.

Each report period contains all the hydraulics and quality values for the nodes and links. Nodes and link values are provided in the same order as the names are specified in the prolog.

The result types for node data are: ResultType.demand, ResultType.head, ResultType.pressure and ResultType.quality.

The result types for link data are: ResultType.linkquality, ResultType.flowrate, and ResultType.velocity.

Parameters:
period : int

The report period

result_type : str

One of the type strings listed above

values : numpy.array

The values to save, in the node or link order specified earlier in the file

save_network_desc_line(element, values)[source]

Save network description meta-data and element characteristics.

This method, by default, does nothing. It is available to be overloaded, but the core implementation assumes that an INP file exists that will have a better, human readable network description.

Parameters:
element : str

The information being saved

values : numpy.array

The values that go with the information

save_energy_line(pump_idx, pump_name, values)[source]

Save pump energy from the output file.

This method, by default, does nothing. It is available to be overloaded in order to save information for pump energy calculations.

Parameters:
pump_idx : int

the pump index

pump_name : str

the pump name

values : numpy.array

the values to save

finalize_save(good_read, sim_warnings)[source]

Post-process data before writing results.

This method, by default, does nothing. It is available to be overloaded in order to post process data.

Parameters:
good_read : bool

was the full file read correctly

sim_warnings : int

were there warnings issued during the simulation

read(filename, custom_handlers=False)[source]

Read a binary file and create a results object.

Parameters:
filename : str

An EPANET BIN output file

custom_handlers : bool, optional

If true, then the the custom, by-line handlers will be used. (save_ep_line(), setup_ep_results(), finalize_save(), etc.) Otherwise read will use a faster, all-at-once reader that reads all results.

Returns:
object

returns a WaterNetworkResults object

.. note:: Overloading

This function should not be overloaded. Instead, overload the other functions to change how it saves the results. Specifically, overload setup_ep_results(), save_ep_line() and finalize_save() to change how extended period simulation results in a different format (such as directly to a file or database).

exception wntr.epanet.io.NoSectionError[source]

Bases: exceptions.Exception