QEPANET​ ​for​ ​QGIS​ ​features

v​ ​0.92
1. Contents
This document describes the main features, usage scenarios and graphical user interface of the
QEPANET​ ​plugin​ ​for​ ​QGIS.

2. Introduction
EPANET is a well known and widely used tool for hydraulic modelling of water distribution
networks. QGIS is a widely used desktop GIS software. Both softwares are free and open-source.
Since a water distribution network has an intrinsic spatial component, coupling EPANET with QGIS
provides an integrated modelling environment offering on the one side the solid EPANET
simulation engine, and on the other the rich spatial tools of QGIS. The QEPANET plugin for QGIS
is​ ​an​ ​attempt​ ​to​ ​reach​ ​this​ ​aim​ ​(fig.​ ​1).
There are other plugins serving the same purpose, but none of them provides a set of dedicated
tools to create and edit the network, relying instead on the standard QGIS editing tools. This
design choice renders those plugins easier to approach, since the tools to be used are already
known to the average QGIS user, but it forgets explicitly account for the topological aspects of the
network. QEPANET, instead, offers a set of tools that are aware of the EPANET network
specifications and constraints, and so guarantees that the network created will be always
compatible​ ​with​ ​the​ ​modelling​ ​engine.

Figure​ ​1.​ ​QGIS​ ​showing​ ​an​ ​hydraulic​ ​network​ ​and​ ​the​ ​QEPANET​ ​panel.
3. Main​ ​user​ ​requirements
The​ ​main​ ​user​ ​requirements​ ​that​ ​have​ ​led​ ​the​ ​design​ ​of​ ​QEPANET​ ​are:
● Provide a set of easy to use tools to draw and manage the hydraulic network. The benefit of
this approach (as already outlined) lies mainly in the ability to control the network creation
and editing, and to ensure that the network is always in a consistent state and compatible
with the modelling engine. In addition, it is also easier to handle the attributes of the
network​ ​elements,​ ​providing​ ​default​ ​values​ ​and​ ​errors​ ​checks;
● Use the standard EPANET .inp file format to store all the data needed. This approach
streamlines the work of the modeller, as there is only one file to be used both inside QGIS
and as the EPANET input. In addition, QEPANET can open for visualization and editing any
standard EPANET inp file, widening its application to the countless EPANET network
already​ ​existing.

4. Main​ ​features
QEPANET​ ​offers​ ​the​ ​following​ ​features:
● The ability to load and save EPANET .inp files, that are used to store all the network
information.
● A set of tools allowing the creation and deletion of the network elements (junctions,
reservoirs, tanks, pipes, pumps and valves). These tools try to preserve the consistency of
the network. For instance, when a pipe is created, at its two ends two junctions are created
or, when a new pipe touches an existing one along its segment, a new junction is created
on​ ​the​ ​intersection​ ​point.
● For every type of network element, a panel where the properties of the element can be set:
every​ ​new​ ​element​ ​will​ ​have​ ​these​ ​properties​ ​as​ ​default).
● The option to load a raster DEM in QGIS that will be used to assign the elevations to the
network​ ​nodes.
● The option to specify, for every node, an elevation correction value (delta z) to account for
nodes​ ​not​ ​lying​ ​on​ ​the​ ​ground,​ ​but​ ​below​ ​or​ ​above​ ​it.
● The option to use the SI or imperial systems of units. All the properties of the network
elements​ ​will​ ​abide​ ​to​ ​the​ ​system​ ​chosen.
● Support to edit all the main EPANET options regarding hydraulics, quality, reactions, times,
energy​ ​and​ ​report.
● A​ ​graphical​ ​pattern​ ​editor,​ ​to​ ​create​ ​and​ ​edit​ ​patterns.
● A​ ​graphical​ ​curve​ ​editor,​ ​to​ ​create​ ​and​ ​edit​ ​volume,​ ​pump,​ ​efficiency,​ ​and​ ​headloss​ ​curves.
● A​ ​utility​ ​button​ ​to​ ​launch​ ​the​ ​EPANET​ ​simulation​ ​(uses​ ​the​ ​standard​ ​EPANET​ ​libraries).
● A tool to analyse the simulation results, by means of graphs showing the values of the
simulated variables along time and by means of thematic maps showing the state of the
network​ ​at​ ​a​ ​given​ ​simulation​ ​step.

4.1. EPANET​ ​options​ ​not​ ​covered​ ​by​ ​QEPANET

QEPANET does not cover all the options available in EPANET. In particular, water quality is not
implemented​ ​(yet).
5. Usage​ ​scenarios
For​ ​QEPANET,​ ​these​ ​usage​ ​scenarios​ ​can​ ​be​ ​outlined:
1. QEPANET used to build a new network and run a simulation: this is the main scenario. The
user opens QGIS, and using the QEPANET tools builds a new georeferenced network,
launches​ ​the​ ​simulation​ ​and​ ​analyses​ ​the​ ​results.
2. QEPANET used to georeference an existing network. The user imports an existing inp file
and​ ​then​ ​uses​ ​the​ ​QEPANET​ ​and​ ​QGIS​ ​tools​ ​to​ ​georeference​ ​it.
3. QEPANET used to analyse existing simulation results. The user imports an existing inp file
and​ ​then​ ​uses​ ​the​ ​QEPANET​ ​output​ ​analyser​ ​to​ ​open​ ​its​ ​associated​ ​out​ ​file.

6. Data​ ​structure
QEPANET needs six QGIS layers, one for each of the six network element types: junctions,
reservoirs,​ ​tanks,​ ​pipes,​ ​pumps​ ​and​ ​valves.
Since the plugin relies only on the EPANET inp file to store data on the file system, the six layers
are “Temporary scratch layers”, created when a new QEPANET project is started or an inp file is
opened.

6.1. A​ ​few​ ​notes​ ​on​ ​the​ ​.inp​ ​file

QEPANET uses some data (e.g.: the elevation delta z) that is not part of the standard .inp file
specification. These data is saved at the end of the .inp file, after the [END] tag, in a series of
sections​ ​whose​ ​names​ ​start​ ​with​ ​the​ ​prefix​ ​“QEPANET”​ ​(e.g.:​ ​[QEPANET-JUNCTIONS]).

This part of the .inp file is completely ignored by EPANET when a simulation is run, and it is only
used by the QEPANET plugin to populate some table fields. If this part of the file is not present
(like​ ​in​ ​inp​ ​files​ ​not​ ​created​ ​by​ ​QEPANET),​ ​QEPANET​ ​will​ ​set​ ​the​ ​values​ ​of​ ​those​ ​fields​ ​to​ ​zero.

If the .inp file with the extra information is opened in a software like EPANET 2.0, an error message
is​ ​displayed,​ ​but​ ​the​ ​file​ ​remains​ ​valid.

7. Graphical​ ​user​ ​interface

All the QEPANET tools are organised in a docking panel (fig. 2). The panel is made of several
sections:
● A​ ​set​ ​of​ ​controls​ ​to​ ​create,​ ​open,​ ​and​ ​save​ ​the​ ​project.
● A​ ​set​ ​of​ ​network​ ​editing​ ​tools.
● A collapsible panel containing the controls used to select the QGIS layers that the plugin
will​ ​work​ ​on.
● Six collapsible panels containing the controls used to set the properties for every type of
network​ ​element​ ​(junctions,​ ​reservoirs,​ ​tanks,​ ​pipes,​ ​pumps,​ ​valves).
● An “Options” collapsible panel containing the controls used to set the general EPANET
options.
 ● A “Tools” collapsible panel containing the controls used to access the tools to manage
patterns​ ​and​ ​curves.
● An “EPANET” collapsible panel containing the controls used to run the simulation and open
the​ ​output​ ​analyser.

Figure​ ​2.​ ​The​ ​plugin​ ​dockable​ ​panel.

7.1. Controls​ ​to​ ​create,​ ​open,​ ​and​ ​save​ ​the​ ​project

QEPANET stores all the network information inside a standard EPANET inp file. Therefore at the
top​ ​of​ ​the​ ​docking​ ​panel​ ​are​ ​located​ ​four​ ​buttons​ ​allowing​ ​to​ ​(fig.​ ​3):
● Create​ ​a​ ​new​ ​empty​ ​inp​ ​file.
● Open​ ​an​ ​existing​ ​inp​ ​file​ ​and​ ​rebuild​ ​the​ ​network​ ​from​ ​its​ ​contents.
● Save​ ​the​ ​currently​ ​open​ ​inp​ ​file.
● Save​ ​the​ ​currently​ ​open​ ​inp​ ​file​ ​as​ ​a​ ​new​ ​file.

Figure​ ​3.​ ​Controls​ ​to​ ​create,​ ​open,​ ​save​ ​and​ ​save​ ​as​ ​the​ ​project.
 7.2. Network​ ​editing​ ​tools
QEPANET provides a set of tools to easily create the network elements: junctions, reservoirs,
tanks, pipes, pumps and valves (fig. 4). In addition there is a tool to move the network elements
and​ ​a​ ​tool​ ​to​ ​select​ ​and​ ​delete​ ​network​ ​elements.
When an element is created, it is assigned the default properties set in the corresponding element
properties​ ​panel​ ​(see​ ​below).
When a node (junction, reservoir or tank) is created, if a DEM has been selected in the “Layers”
panel,​ ​it​ ​is​ ​assigned​ ​the​ ​elevation​ ​of​ ​the​ ​DEM​ ​at​ ​its​ ​location.
When a link (pipe, pump or valve) is created, and it does not starts (or ends) with a node, a
junction​ ​is​ ​created​ ​at​ ​its​ ​start​ ​(or​ ​end)​ ​to​ ​maintain​ ​the​ ​network​ ​in​ ​a​ ​consistent​ ​state.
Pumps and valves are links, therefore two-dimensional elements, in accordance to the EPANET
network​ ​model.​ ​Pumps​ ​and​ ​valves​ ​have​ ​a​ ​standard​ ​length​ ​of​ ​1​ ​m.

Figure​ ​4.​ ​Network​ ​editing​ ​tools.

7.3. Network​ ​elements​ ​properties

The six network elements properties panels are used to set the default properties of the six
network components. The units used are defined when the QEPANET project is created and
depend​ ​on​ ​the​ ​system​ ​of​ ​units​ ​selected.

7.3.1. Junctions
The “Junction properties” panel (fig. 5) allows the user to set the default junction properties, that
will​ ​be​ ​assigned​ ​to​ ​every​ ​newly​ ​created​ ​junction:
● Demand
● Delta​ ​Z
● Pattern​ ​(if​ ​any)
● Emitter​ ​coefficient

Figure​ ​5.​ ​Junction​ ​properties​ ​panel.

 7.3.2. Reservoirs
The “Reservoir properties” panel (fig. 6) allows the user to set the default reservoir properties, that
will​ ​be​ ​assigned​ ​to​ ​every​ ​newly​ ​created​ ​reservoir:
● Delta​ ​Z
● Pressure​ ​head
● Pattern​ ​(if​ ​any)

Figure​ ​6.​ ​Reservoir​ ​properties​ ​panel

7.3.3. Tanks
The “Tanks properties” panel (fig. 7) allows the user to set the default tank properties, that will be
assigned​ ​to​ ​every​ ​newly​ ​created​ ​tank:
● Delta​ ​Z
● Initial​ ​level
● Minimum​ ​level
● Maximum​ ​level
● Diameter
● Volume
● Curve​ ​(if​ ​any)

Figure​ ​7.​ ​Tank​ ​properties​ ​panel.

7.3.4. Pipes
The “Pipes properties” panel (fig. 8) allows the user to set the default pipe properties, that will be
assigned​ ​to​ ​every​ ​newly​ ​created​ ​pipe:
● Demand
● Diameter
● Minor​ ​loss
 ● Roughness. Based on the pipe material: for every material a range of viable values is
presented.
● Status.
● Vertex distance: this option is used to create intermediate vertices along each pipe, to
account for the real-world length of pipes. If the value is set to 0, the pipe will not have any
intermediate​ ​vertices.

Figure​ ​8.​ ​Pipe​ ​properties​ ​panel.

7.3.5. Pumps
The “Pumps properties” panel (fig. 9) allows the user to set the default pump properties, that will be
assigned​ ​to​ ​every​ ​newly​ ​created​ ​pump:
● Parameter​ ​(power​ ​or​ ​head).
● Head​ ​(only​ ​active​ ​when​ ​the​ ​head​ ​parameter​ ​is​ ​selected)
● Power​ ​(only​ ​active​ ​when​ ​the​ ​power​ ​parameter​ ​is​ ​selected)
● Speed
● Speed​ ​pattern​ ​(if​ ​any)
● Initial​ ​status​ ​(open​ ​or​ ​closed)

Figure​ ​9.​ ​Pump​ ​properties​ ​panel.

 7.3.6. Valves
The “Valves properties” panel (fig. 10) allows the user to set the default valve properties, that will
be​ ​assigned​ ​to​ ​every​ ​newly​ ​created​ ​valve:
● Type​ ​(PRV,​ ​PSV,​ ​PBV,​ ​FCV,​ ​TCV,​ ​GPV)
● Pressure
● Head​ ​loss​ ​curve​ ​(only​ ​active​ ​with​ ​GPV​ ​valves)
● Minor​ ​loss
● Status​ ​(none,​ ​open,​ ​closed)

Figure​ ​10.​ ​Valve​ ​properties​ ​panel.

7.4. Options​ ​panel

The options panel (fig. 11) is used to set the EPANET general simulation options. It includes six
buttons​ ​to​ ​access​ ​six​ ​dialog​ ​allowing​ ​the​ ​user​ ​to​ ​set​ ​properties​ ​related​ ​to:
● Hydraulics
● Quality
● Reactions
● Times
● Energy
● Report
The​ ​panels​ ​are​ ​detailed​ ​in​ ​the​ ​following​ ​sections.

Figure​ ​11.​ ​Options​ ​panel.

 7.4.1. Hydraulics
The “Hydraulics” options panel” (fig. 12) contains the main project properties. It is shown also when
a​ ​new​ ​project​ ​is​ ​created.
The units system selected (SI metric or imperial) will define the units used across all the plugin
controls.

Figure​ ​12.​ ​Hydraulics​ ​options​ ​panel.

7.4.2. Quality
The​ ​“Quality”​ ​options​ ​panel​ ​contains​ ​the​ ​properties​ ​related​ ​to​ ​water​ ​quality​ ​(fig.​ ​13).
 Figure​ ​13.​ ​Quality​ ​options​ ​panel.

7.4.3. Reactions
The​ ​“Reactions”​ ​option​ ​panel​ ​contains​ ​the​ ​properties​ ​related​ ​to​ ​reactions​ ​(fig.​ ​14).

Figure​ ​14.​ ​Reactions​ ​options​ ​panel.

7.4.4. Times
The​ ​“Times”​ ​options​ ​panel​ ​contains​ ​the​ ​properties​ ​related​ ​to​ ​time​ ​settings​ ​(fig.​ ​15).
 Figure​ ​15.​ ​Times​ ​options​ ​panel.

7.4.5. Energy
The​ ​“Energy”​ ​options​ ​panel​ ​contains​ ​the​ ​properties​ ​related​ ​to​ ​energy​ ​(fig.​ ​16).

Figure​ ​16.​ ​Energy​ ​options​ ​panel.

7.4.6. Report
The​ ​“Report”​ ​panel​ ​contains​ ​the​ ​properties​ ​related​ ​to​ ​reporting​ ​(fig.​ ​17)
 Figure​ ​17.​ ​Report​ ​options​ ​panel.

7.5. Tools​ ​panel

The​ ​tools​ ​panel​ ​(fig.​ ​18)​ ​collects​ ​miscellaneous​ ​tools.​ ​These​ ​include:
● A button to create new, empty layers for the six network element types. Typically, these
layers are automatically created when a new project is created, or when an existing project
is​ ​open,​ ​so​ ​the​ ​use​ ​of​ ​this​ ​tool​ ​is​ ​rather​ ​limited.
● A​ ​text​ ​box​ ​to​ ​set​ ​the​ ​snap​ ​tolerance​ ​used​ ​by​ ​the​ ​network​ ​editing​ ​tools.
● A​ ​button​ ​to​ ​access​ ​the​ ​pattern​ ​editor​ ​(see​ ​below).
● A​ ​button​ ​to​ ​access​ ​the​ ​curve​ ​editor​ ​(see​ ​below)

Figure​ ​18.​ ​Tools​ ​panel.

7.5.1. Pattern​ ​editor

The pattern editor is used to create and manage patterns to be used as network element
properties.
The​ ​editor​ ​(fig.​ ​19)​ ​shows​ ​the​ ​list​ ​of​ ​the​ ​existing​ ​patterns​ ​(if​ ​any),​ ​and​ ​a​ ​set​ ​of​ ​buttons​ ​to:
● Create​ ​a​ ​new​ ​pattern​ ​from​ ​scratch.
● Import​ ​patterns​ ​from​ ​an​ ​inp​ ​file.
● Save​ ​the​ ​currently​ ​edited​ ​pattern.
● Delete​ ​the​ ​currently​ ​selected​ ​pattern.

The​ ​pattern​ ​can​ ​be​ ​drawn​ ​by​ ​adding​ ​rows​ ​to​ ​the​ ​table​ ​and​ ​setting​ ​the​ ​desired​ ​multiplier​ ​values.
 Figura​ ​19.​ ​Pattern​ ​editor.

7.5.2. Curve​ ​editor

The​ ​curve​ ​editor​ ​is​ ​used​ ​to​ ​create​ ​and​ ​manage​ ​curves​ ​to​ ​be​ ​used​ ​as​ ​network​ ​element​ ​properties.
The​ ​editor​ ​(fig.​ ​20)​ ​shows​ ​the​ ​list​ ​of​ ​the​ ​existing​ ​curves​ ​(if​ ​any),​ ​and​ ​a​ ​set​ ​of​ ​buttons​ ​to:
● Create​ ​a​ ​new​ ​curve​ ​from​ ​scratch.
● Import​ ​curves​ ​from​ ​an​ ​inp​ ​file.
● Save​ ​the​ ​currently​ ​edited​ ​curve.
● Delete​ ​the​ ​currently​ ​selected​ ​curve.

The curve can be drawn by adding rows to the table and setting the desired values in both
columns.​ ​The​ ​values​ ​units​ ​depend​ ​on​ ​the​ ​selected​ ​curve​ ​type:
● Type​ ​“Volume”:​ ​height​ ​and​ ​volume.
● Type​ ​“Pump”:​ ​flow​ ​and​ ​head.
● Type​ ​“Efficiency”:​ ​flow​ ​and​ ​efficiency.
● Type​ ​“Headloss”:​ ​flow​ ​and​ ​head​ ​loss.
 Figure​ ​20.​ ​Curve​ ​editor.

7.6. EPANET​ ​panel

The​ ​EPANET​ ​panel​ ​(fig.​ ​21)​ ​contains​ ​only​ ​two​ ​buttons:
● The “lighting” button allows the user to run an EPANET simulation. When pressed, the user
is prompted to select an inp file that will be used as input in EPANET. Then the simulation
will​ ​start,​ ​and​ ​the​ ​console​ ​output​ ​from​ ​EPANET​ ​will​ ​be​ ​shown​ ​in​ ​the​ ​text​ ​box​ ​below.
● The “Output analyser” button brings up the tool used to analyse the simulation outputs (see
below).
 Figure​ ​21.​ ​EPANET​ ​panel.

7.6.1. Output​ ​analyser

The output analyser is used to inspect the simulation results. It uses as input the out file produced
by​ ​EPANET​ ​at​ ​the​ ​end​ ​of​ ​a​ ​simulation​ ​run,​ ​and​ ​it​ ​is​ ​made​ ​of​ ​two​ ​sections:
● The “Graphs” section (fig. 22) shows in a graphical from the values of the selected
variable(s) along time for the network elements selected by the user (therefore it is possible
to compare values of several variables for several elements). The variables include
demand, head, pressure and quality for nodes, and flow, velocity, head loss and quality for
links.
● The “Maps” section (fig. 23) is used to create thematic maps of the network at a given
simulation period. The network elements colors are function of the value of the selected
variable.
Figure​ ​22.​ ​Output​ ​analyser​ ​-​ ​Graphs.
 Figure​ ​23.​ ​Output​ ​analyser​ ​-​ ​Maps.

8. 2
9. 2
10. 2