wntr.network.options module

The wntr.network.options module includes simulation options.

Note

This module has been changed in version 0.2.3 to incorporate the new options that EPANET 2.2 requires. It also reorganizes certain options to better align with EPANET nomenclature. This change is not backwards compatible, particularly when trying to use pickle files with older options.

Classes

Options	Water network model options class.
TimeOptions	Options related to simulation and model timing.
GraphicsOptions	Options related to graphics.
HydraulicOptions	Options related to hydraulic model.
ReportOptions	Options related to EPANET report outputs.
ReactionOptions	Options related to water quality reactions.
QualityOptions	Options related to water quality modeling.
EnergyOptions	Options related to energy calculations.
UserOptions	Options defined by the user.

class wntr.network.options.TimeOptions(duration: int = 0, hydraulic_timestep: int = 3600, quality_timestep: int = 360, rule_timestep: int = 360, pattern_timestep: int = 3600, pattern_start: int = 0, report_timestep: int = 3600, report_start: int = 0, start_clocktime: int = 0, statistic: str = 'NONE', pattern_interpolation: bool = False)

Bases: _OptionsBase

Options related to simulation and model timing. These options are named according to the EPANET 2.2 “Times” settings.

Parameters

• duration (int) – Simulation duration (seconds), by default 0.

• hydraulic_timestep (int >= 1) – Hydraulic timestep (seconds), by default 3600 (one hour).

• quality_timestep (int >= 1) – Water quality timestep (seconds), by default 360 (five minutes).

• rule_timestep (int >= 1) – Rule timestep (seconds), by default 360 (five minutes).

• pattern_timestep (int >= 1) – Pattern timestep (seconds), by default 3600 (one hour).

• pattern_start (int) – Time offset (in seconds) to find the starting pattern step; changes where in pattern the pattern starts out, not what time the pattern starts, by default 0.

• report_timestep (int >= 1) – Reporting timestep (seconds), by default 3600 (one hour).

• report_start (int) – Start time of the report (in seconds) from the start of the simulation, by default 0.

• start_clocktime (int) – Time of day (in seconds from midnight) at which the simulation begins, by default 0 (midnight).

• statistic (str) – Provide statistics rather than time series report in the report file. Options are “AVERAGED”, “MINIMUM”, “MAXIUM”, “RANGE”, and “NONE” (as defined in the EPANET User Manual). Defaults to “NONE”.

• pattern_interpolation (bool) – Only used by the WNTRSimulator. Defaults to False. If True, interpolation will be used determine pattern values between pattern timesteps. If False, patterns cause step-like behavior where the pattern value corresponding to the most recent pattern timestep is used until the next pattern timestep. For example, given the pattern [1, 1.2, 1.6], a pattern timestep of 1 hour, and a pattern_interpolation value of False, a value of 1 is used at 0 hours and every time strictly less than 1 hour. A value of 1.2 is used at hour 1 and every time strictly less than 2 hours. With a pattern_interpolation value of True, a value of 1 is used at 0 hours and a value of 1.2 is used at 1 hour. However, at an intermediat time such as 0.5 hours, interpolation is used, resulting in a value of 1.1. Using interpolation with a shorter hydraulic_timestep can make problems with large changes in patterns (e.g., large changes in demand) easier to solve.

class wntr.network.options.GraphicsOptions(dimensions: Optional[list] = None, units: Optional[str] = None, offset: Optional[list] = None, image_filename: Optional[str] = None, map_filename: Optional[str] = None)

Bases: _OptionsBase

Options related to graphics.

May be used to contain custom, user defined values. These options are taken from the EPANET “[BACKDROP]” section. Additionally, the “MAP” option (map_filename), which identifies a file containing node coordinates in the EPANET “[OPTIONS]” section, is also included here.

Parameters

• dimensions (4-tuple or list) – Dimensions for backdrop image in the order (LLx, LLy, URx, URy). By default, EPANET will make the image match the full extent of node coordinates (set to None).

• units (str) – Units for backdrop image dimensions. Must be one of FEET, METERS, DEGREES or NONE, by default “NONE”.

• offset (2-tuple or list) – Offset for the network in order (X, Y), by default None (no offset).

• image_filename (string) – Filename where image is located, by default None.

• map_filename (string) – Filename used to store node coordinates in (node, x, y) format. This option is from the EPANET “[OPTIONS]” section. See note below.

Note

Because the format of the MAP file is uncertain, file will need to be processed by the user to assign coordinates to nodes, if desired. Remember that node coordinates have impact only on graphics and do not impact simulation results. If the map_filename is not None, then no [COORDINATES] will be written out to INP files (to save space, since the simulator does not use that section). This can be overwritten in the write_inpfile commands.

class wntr.network.options.HydraulicOptions(headloss: str = 'H-W', hydraulics: Optional[str] = None, hydraulics_filename: Optional[str] = None, viscosity: float = 1.0, specific_gravity: float = 1.0, pattern: str = '1', demand_multiplier: float = 1.0, demand_model: str = 'DD', minimum_pressure: float = 0.0, required_pressure: float = 0.07, pressure_exponent: float = 0.5, emitter_exponent: float = 0.5, trials: int = 200, accuracy: float = 0.001, unbalanced: str = 'STOP', unbalanced_value: Optional[int] = None, checkfreq: int = 2, maxcheck: int = 10, damplimit: int = 0, headerror: float = 0, flowchange: float = 0, inpfile_units: str = 'GPM', inpfile_pressure_units: Optional[str] = None)

Bases: _OptionsBase

Options related to hydraulic model. These options are named according to the settings in the EPANET “[OPTIONS]” section. Unless specified, these options are valid for both EPANET 2.0 and 2.2.

Parameters

• headloss (str) – Formula to use for computing head loss through a pipe. Options are “H-W”, “D-W”, and “C-M”, by default “H-W”.

• hydraulics (str) – Indicates if a hydraulics file should be read in or saved; options are None, “USE” and “SAVE”, by default None.

• hydraulics_filename (str) – Filename to use if hydraulics is not None, by default None.

• viscosity (float) – Kinematic viscosity of the fluid, by default 1.0.

• specific_gravity (float) – Specific gravity of the fluid, by default 1.0.

• pattern (str) – Name of the default pattern for junction demands. By default, the default pattern is the pattern named “1”. If this is set to None (or if pattern “1” does not exist), then junctions with demands but without patterns will be held constant.

• demand_multiplier (float) – The demand multiplier adjusts the values of baseline demands for all junctions, by default 1.0.

• emitter_exponent (float) – The exponent used when computing flow from an emitter, by default 0.5.

• minimum_pressure (float) – (EPANET 2.2 only) The global minimum nodal pressure, by default 0.0.

• required_pressure (float) – (EPANET 2.2 only) The required nodal pressure, by default 0.07 (m H2O)

• pressure_exponent (float) – (EPANET 2.2 only) The pressure exponent, by default 0.5.

• trials (int) – Maximum number of trials used to solve network hydraulics, by default 200.

• accuracy (float) – Convergence criteria for hydraulic solutions, by default 0.001.

• headerror (float) – (EPANET 2.2 only) Augments the accuracy option by adjusting the head error convergence limit, by default 0 (off).

• flowchange (float) – (EPANET 2.2 only) Augments the accuracy option by adjusting the flow change convergence limit, by default 0 (off).

• unbalanced (str) – Indicate what happens if a hydraulic solution cannot be reached. Options are “STOP” and “CONTINUE”, by default “STOP”.

• unbalanced_value (int) – Number of additional trials if unbalanced == "CONTINUE", by default None.

• checkfreq (int) – Number of solution trials that pass between status checks, by default 2.

• maxcheck (int) – Number of solution trials that pass between status check, by default 10.

• damplimit (float) – Accuracy value at which solution damping begins, by default 0 (no damping).

• demand_model (str) – Demand model for EPANET 2.2; acceptable values are “DD” and “PDD”, by default “DD”. EPANET 2.0 only contains demand driven analysis, and will issue a warning if this option is not set to DD.

• inpfile_units (str) – Units for the INP file; options are “CFS”, “GPM”, “MGD”, “IMGD”, “AFD”, “LPS”, “LPM”, “MLD”, “CMH”, and “CMD”. This only changes the units used in generating the INP file – it has no impact on the units used in WNTR, which are always SI units (m, kg, s).

• inpfile_pressure_units (str) – Pressure units for the INP file, by default None (uses pressure units from inpfile_units)

class wntr.network.options.ReactionOptions(bulk_order: float = 1.0, wall_order: float = 1.0, tank_order: float = 1.0, bulk_coeff: float = 0.0, wall_coeff: float = 0.0, limiting_potential: Optional[float] = None, roughness_correl: Optional[float] = None)

Bases: _OptionsBase

Options related to water quality reactions. From the EPANET “[REACTIONS]” options.

Parameters

• bulk_order (float) – Order of reaction occurring in the bulk fluid, by default 1.0.

• wall_order (float) – Order of reaction occurring at the pipe wall; must be either 0 or 1, by default 1.0.

• tank_order (float) – Order of reaction occurring in the tanks, by default 1.0.

• bulk_coeff (float) – Global reaction coefficient for bulk fluid and tanks, by default 0.0.

• wall_coeff (float) – Global reaction coefficient for pipe walls, by default 0.0.

• limiting_potential (float) – Specifies that reaction rates are proportional to the difference between the current concentration and some limiting potential value, by default None (off).

• roughness_correl (float) – Makes all default pipe wall reaction coefficients related to pipe roughness, according to functions as defined in EPANET, by default None (off).

Note

Remember to use positive numbers for growth reaction coefficients and negative numbers for decay coefficients. The time units for all reaction coefficients are in “per-second” and converted to/from EPANET units during I/O.

class wntr.network.options.QualityOptions(parameter: str = 'NONE', trace_node: Optional[str] = None, chemical_name: str = 'CHEMICAL', diffusivity: float = 1.0, tolerance: float = 0.01, inpfile_units: str = 'mg/L')

Bases: _OptionsBase

Options related to water quality modeling. These options come from the “[OPTIONS]” section of an EPANET INP file.

Parameters

• parameter (str) – Type of water quality analysis. Options are “NONE”, “CHEMICAL”, “AGE”, and “TRACE”, by default None.

• trace_node (str) – Trace node name if quality == "TRACE", by default None.

• chemical (str) – Chemical name for “CHEMICAL” analysis, by default “CHEMICAL” if appropriate.

• diffusivity (float) – Molecular diffusivity of the chemical, by default 1.0.

• tolerance (float) – Water quality solver tolerance, by default 0.01.

• inpfile_units (str) – Units for quality analysis if the parameter is set to CHEMICAL. This is only relevant for the INP file. This value must be either “mg/L” (default) or “ug/L” (miligrams or micrograms per liter). Internal WNTR units are always SI units (kg/m3).

class wntr.network.options.EnergyOptions(global_price: float = 0, global_pattern: Optional[str] = None, global_efficiency: Optional[float] = None, demand_charge: Optional[float] = None)

Bases: _OptionsBase

Options related to energy calculations. From the EPANET “[ENERGY]” settings.

Parameters

• global_price (float) – Global average cost per Joule, by default 0.

• global_pattern (str) – ID label of time pattern describing how energy price varies with time, by default None.

• global_efficiency (float) – Global pump efficiency as percent; i.e., 75.0 means 75%, by default None.

• demand_charge (float) – Added cost per maximum kW usage during the simulation period, by default None.

class wntr.network.options.ReportOptions(pagesize: Optional[list] = None, report_filename: Optional[str] = None, status: str = 'NO', summary: str = 'YES', energy: str = 'NO', nodes: bool = False, links: bool = False, report_params: Optional[dict] = None, param_opts: Optional[dict] = None)

Bases: _OptionsBase

Options related to EPANET report outputs. The values in this options class do not affect the behavior of the WNTRSimulator. These only affect what is written to an EPANET INP file and the results that are in the EPANET-created report file.

Parameters

• report_filename (str) – Provides the filename to use for outputting an EPANET report file, by default this will be the prefix plus “.rpt”.

• status (str) – Output solver status (“YES”, “NO”, “FULL”). “FULL” is only useful for debugging

• summary (str) – Output summary information (“YES” or “NO”)

• energy (str) – Output energy information

• nodes (None, "ALL", or list) – Output node information in report file. If a list of node names is provided, EPANET only provides report information for those nodes.

• links (None, "ALL", or list) – Output link information in report file. If a list of link names is provided, EPANET only provides report information for those links.

• pagesize (str) – Page size for EPANET report output

class wntr.network.options.UserOptions(**kwargs)

Bases: _OptionsBase

Options defined by the user.

Provides an empty class that accepts getattribute and setattribute methods to create user-defined options. For example, if using WNTR for uncertainty quantification, certain options could be added here that would never be used directly by WNTR, but which would be saved on pickling and could be used by the user-built analysis scripts.

class wntr.network.options.Options(time: Optional[TimeOptions] = None, hydraulic: Optional[HydraulicOptions] = None, report: Optional[ReportOptions] = None, quality: Optional[QualityOptions] = None, reaction: Optional[ReactionOptions] = None, energy: Optional[EnergyOptions] = None, graphics: Optional[GraphicsOptions] = None, user: Optional[UserOptions] = None)

Bases: _OptionsBase

Water network model options class.

These options mimic options in EPANET. The user attribute is a generic python class object that allows for dynamically created attributes that are user specific.

Parameters

• time (TimeOptions) – Contains all timing options for the scenarios

• hydraulic (HydraulicOptions) – Contains hydraulic solver parameters

• reaction (ReactionOptions) – Contains chemical reaction parameters

• quality (QualityOptions) – Contains water quality simulation options and source definitions

• energy (EnergyOptions) – Contains parameters for energy calculations

• report (ReportOptions) – Contains options for how for format and save report

• graphics (GraphicsOptions) – Contains EPANET graphics and background options and also the filename for external node coordinates, if used

• user (dict) – An empty dictionary that allows for user specified options

to_dict()

Dictionary representation of the options