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

read(inp_files, wn=None)[source]

Read an EPANET INP file and load data into a water network model object. Both EPANET 2.0 and EPANET 2.2 INP file options are recognized and handled.

Parameters
  • inp_files (str or list) – An EPANET INP input file or list of INP files to be combined

  • wn (WaterNetworkModel, optional) – An optional network model to append onto; by default a new model is created.

Returns

WaterNetworkModel – A water network model object

write(filename, wn, units=None, version=2.2, force_coordinates=False)[source]

Write a water network model into an EPANET INP file.

Note

Please note that by default, an EPANET 2.2 formatted file is written by WNTR. An INP file with version 2.2 options will not work with EPANET 2.0 (neither command line nor GUI). By default, WNTR will use the EPANET 2.2 toolkit.

Parameters
  • filename (str) – Name of the EPANET INP file.

  • units (str, int or FlowUnits) – Name of the units for the EPANET INP file to be written in.

  • version (float, {2.0, 2.2}) – Defaults to 2.2; use 2.0 to guarantee backward compatability, but this will turn off PDD mode and supress the writing of other EPANET 2.2-specific options. If PDD mode is specified, a warning will be issued.

  • force_coordinates (bool) – This only applies if self.options.graphics.map_filename is not None, and will force the COORDINATES section to be written even if a MAP file is provided. False by default, but coordinates are written by default since the MAP file is None by default.

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.

This class provides read functionality for EPANET binary output files.

Parameters
  • results_type (list of ResultType, default=None) –

    This parameter is only active when using a subclass of the BinFile that implements

    a custom reader or writer.

    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.

  • 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

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

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, convergence_error=False, darcy_weisbach=False, convert=True)[source]

Read a binary file and create a results object.

Parameters
  • filename (str) – An EPANET BIN output file

  • convergence_error (bool (optional)) – If convergence_error is True, an error will be raised if the simulation does not converge. If convergence_error is False, partial results are returned, a warning will be issued, and results.error_code will be set to 0 if the simulation does not converge. Default = False.

Returns

object – returns a WaterNetworkResults object

exception wntr.epanet.io.NoSectionError[source]

Bases: Exception