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
