$\resizebox*{0.05\textwidth}{!}{\includegraphics{dc-icon.eps}}$ Appendix A: DC Water Design Extension Manual

Subsections

DC Water Design Extension Manual

by STEFFEN MACKE

This Manual describes the DC Water Design Extension Version 2.00.

This Document uses Terminology from ArcView and EPANET. Please refer to the respective documentation for in-depth explanations.

What is the DC Water Design Extension?

The DC Water Design Extension is an Extension to ESRI's ArcView GIS software. Version 2.00 integrates the EPANET 2.00 hydraulic modeling software with ArcView. It allows to store, edit and retrieve EPANET hydraulic models including all options in ArcView. Also it is possible to run the EPANET hydraulic analysis from ArcView and load the results into the GIS. Loading of EPANET models to ArcView is not yet implemented.

Concepts

Network Traces

Network Traces are be useful to solve problems related to the network geometry. It is possible for example to check the connectivity of the network features in a model. Through specifying network features at which the trace should stop, it is possible to isolate supply zones.

Bit codes

Bit codes are stored as integer numbers in GIS data. They provide a powerful method to store hydraulic models in GIS data. The underlying principle is very simple:

The models are numbered
Each bit represents one supply zone
If the bit is set (1) than the network feature is used in the respective model. Otherwise (0), the feature is not used in the model.
The different values are assembled by arithmetic addition.

The bit numbering starts with 0. A temporary field should be used in order to correctly perform the addition of two bit codes. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$

Virtual Lines

Virtual Lines provide a concept to convert GIS point data (pumps or valves) into the lines used by the hydraulic analysis software. The conversion is done automatically when the GIS data is exported to the hydraulic model. Virtual Lines require exactly two pipes connected to each pump or valve. In addition, the two pipes must have the same digitizing direction (which will be the flow direction in the hydraulic model).

Installation

How to obtain the DC Water Design Extension

For DORSCH Consult staff, the DC Water Design Extension is available from the DC GIS Database (Lotus Notes).

All others can obtain the DC Water Design Extension including documentation and source code from the DC Water Design Extension homepage:

http://dcwaterdesign.sourceforge.net

To ease the installation process, the installer executable (setup program) is usually the best choice.

Requirements

ArcView 3.0 or higher
Windows 95, 98, ME, NT or 2000 in order to export EPANET files
EPANET 2.0 or higher is needed in order to run a hydraulic analysis
An (ANSI SQL compliant) ODBC connection is needed in order to import hydraulic analysis results

Setup

In order to install the DC Water Design Extension, one has to run the installer executable. After accepting the license (section 11.5), the installer prompts the user to select the installation path. The installation path should be the path to ArcView's EXT32 folder. Usually this should be the default path (c:\ESRI\av_gis30\arcview\EXT32). It might differ for custom ArcView installations. Than it has to be chosen which components of the extension should be installed. In general, one should install all the components of the extension.

If it is intended to use e.g. a newer version of the XSLT parser and the new version is already installed, $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ the user might choose not to install the XSLT parser that comes with the extension. However, this option should be left to the advanced user.

Usage

General Usage

Extension loading

Start ArcView
Open the Extensions Dialog (File->Extensions ...)
Select the DC Water Design Extension (Put a checkmark in the box on the left side).
After the Extension is loaded, the Setup Dialog provides information about several settings. The settings should not be changed without profound knowledge of their functionality.

Quick Start Guide

Load the Extension
Open a View
Add Themes to the View. The themes should describe the water supply network. Junctions, pipes and reservoirs would comprise a simple network. The attributes of the themes must adhere to the ArcView/EPANET Data Model (appendices 12,13). ArcView field aliases can be used to map the fields correctly.
Click on the EPANET Themes button. Select the appropriate Themes.
Choose ``Make EPANET Model'' from the DC Water Design menu
If the last step does not yield any errors, an EPANET input file can be created now. Choose ``Write EPANET File'' from the DC Water Design menu. Choose filename and location.
Fire up EPANET and open the created file (*.inp).

Project GUI

The DC Water Design Extension extends the Project GUI by adding a new Menu, called DC Water Design Extension. The Menu contains the following choices:

Setup

Shows the Setup Dialog.

The Setup Dialog includes an option to choose the language of the Extension. Currently supported are the following localizations:

English
German

Note that the Localization is not completed yet. It is therefore recommended that the language is set to English. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$

EPANET Tables

Displays the EPANET Tables Dialog.

The Tables in the dialog are used to to store non-spatial EPANET data with ArcView. Typical examples of such data are pump curves or hydraulic analysis options. Before it is possible to use a table with the DC Water Design Extension, it has to be loaded into ArcView. Refer to the ArcView documentation for information on how to load tables into ArcView.

Result Tables

Opens the Result Tables Dialog.

The Result Tables are used to store the results of a hydraulic analysis. There are two tables, one for node results and one for link results. For performance reasons it is recommended to use a RDBMS such as mySQL for storing the data. As of version 2.00, the DC Water Design Extension has only been tested with mySQL result tables.

About DC Water Design Extension

Displays information about the DC Water Design Extension License. Section11.5 contains details on the license.

View GUI

The DC Water Design Extension extends the ArcView View GUI with the following elements:

A new Menu called ``DC Water Design''
Buttons
Tools
Three pop-up menus

The pop-up menus are available through clicking the right mouse button over a network feature.

The additional functionality is explained below.

Write EPANET file

Exports the hydraulic model to an EPANET input file.

The model has to be complete, running ``Make EPANET Model'' and ``Check EPANET Model'' is advisable especially for the novice user before exporting the EPANET input file.

The resulting EPANET input file has the extension *.inp. The *.xml-file is just an intermediate format (temporary file). $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$

Run EPANET Calculation

Exports the hydraulic model to an EPANET input file, runs the analysis and loads the results into ArcView.

The model has to be complete, running ``Make EPANET Model'' and ``Check EPANET Model'' is advisable especially for the novice user before exporting the EPANET input file.

After the analysis has been completed, the report created by EPANET is displayed in a window and the user is prompted to select a time step for which the results will be loaded.

Load Results for step ...

Loads the results of an EPANET hydraulic analysis to ArcView.

The hydraulic analysis has to be run from ArcView in order to to enable this feature. The user is prompted to select the time step for which the results should be loaded.

Make EPANET Model

Creates the line-node structure required by EPANET.

This function fills the fields node1 and node2 in the links table with the dc_ids of the connected nodes. The fields will be overwritten by this function, therefore the user has to confirm the action before the script run.

After completion, a report gives an overview of the created model. Model creation errors are also reported. In case of such errors, the features in question are selected after the run.

If there are reports about inconsistent flow direction at pumps or valves, the ``Flip Polylines'' tool of the extension can be used to correct the errors.

EPANET Themes

Opens the EPANET themes dialog.

The themes dialog is used to select the themes used in the hydraulic model. The line and node theme are required, other themes are optional and can be switched off with the check boxes on the right side.

Most of the extension functions require that the EPANET themes are properly set up in this dialog. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ Setting up the themes should be the first step when using the extension. The settings of the EPANET themes dialog are also used to determine which themes should be edited.

EPANET Tables

Displays the EPANET tables dialog.

The tables in the dialog are used to to store non-spatial EPANET data with ArcView. Typical examples of such data are pump curves or hydraulic analysis options. Before it is possible to use a table with the DC Water Design Extension, it has to be loaded into ArcView. The ArcView documentation contains information on how to load tables.

Valve Control

Allows to set valve states according to EPANET Controls.

If a controls table is registered with the Extension (see EPANET Tables Dialog), the user is offered to select the controls he would like to apply. All chosen controls are applied: The status of the respective valves is set to ``open'' or ``closed'' depending on the controls. This is very useful in combination with Network Traces as the extension allows to stop traces at closed valves.

Make House Connections

Creates a straight pipe between tanks and junctions which share an id.

This function requires some preparatory work: Each tank of the tanks theme needs to know to which junction it should be connected. This is expressed with a field in the tanks attribute table that contains the dc_id of the junction the tank should connect to. Such fields can be established e.g. by using the spatial join function of the ArcView Geoprocessing Wizard.

Note that this functionality has been included mainly for the purpose of modeling intermittent supply with household storage tanks. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ It might be taken out or in future versions of the DC Water Design Extension. In fact, the best solution will be to create another extension specialized on intermittent supply modeling that depends on the DC Water Design Extension.

Create Supply Strings

Calculates a coded text that shows when a node is supplied with water.

This might only be used after successfully running an EPANET hydraulic analysis from ArcView. The function will query the the nodes results table for pressures above zero. Each pressure above zero will yield a ``1'' in the supply string, a pressure below or equal zero will yield a ``0'' in the supply string. For each node, the supply strings are written to a user-selectable text field. The field has to been long enough to contain as many characters as there are time steps in the EPANET results.

Note that this functionality has been included mainly for the purpose of modeling intermittent supply with household storage tanks. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ It might be taken out in future versions of the DC Water Design Extension. The ideal solution will be to create another extension specialized on intermittent supply modeling that depends on the DC Water Design Extension.

Calculate Pipe Length For Junctions

This function calculates the length of the pipes connected to a junction.

A user selectable number field in the junctions attribute table is filled with the length of the pipes connected to each junction. In order not to double the overall pipe length, each pipe length is divided by two. Thus every part of a pipe is assigned to the nearest node.

Clip Themes by Bitcode

Creates new themes with features which have the same bit set in a bit code.

The functions works with all active themes in the view. First, the user is prompted to select the bit which has to be set for the clipped themes. Then the field containing the bit code has to be chosen. (The script assumes that the bit code field names are the same throughout all the active themes.) The user can select the filename and location for each clipped theme. He can also choose whether the new themes should be added to the view.

Bit codes make it possible to use the same network features in different supply zones. This requires extraction of the features into separate themes. See section 11.1.1 for details on bit codes.

About DC Water Design Extension

Displays information about the DC Water Design Extension License. See section11.5 for the license details.

Flip Polylines

This tool allows to flip the digitizing direction of lines.

The theme containing the lines to be flipped has to be set up as the pipe theme in the EPANET themes dialog. Simple clicking on the line will switch the digitizing direction.

Tip: ArcView's symbology can be used to display the digitizing direction with arrowheads. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$

Move Nodes

A tool to move network nodes including rubber-banding.

With this tool it is possible to move network nodes (junctions, tanks, reservoirs, pumps, valves) along with the connected pipes. The network stays intact and fully connected (rubber-banding).

The respective themes have to be registered with the extension in the EPANET themes dialog.

Split Pipe (Add Junction)

A tool that allows to split a pipe into two pipes. Adds a new junction at the split point.

The two new pipes inherit the attributes from the original pipe. However, the length gets recalculated based on the shapes.

Pipe and junction themes have to be chosen in the EPANET themes dialog.

Edit Pipe Vertices

Allows to re-shape pipes.

Vertices determine the route of a pipe. The tool makes it possible to move all the vertices of a pipe. Additional, it is possible to add vertices to the pipe. Unlike the ArcView tool ``Vertex Edit'', ``Edit Pipe Vertices'' ensures network connectivity - it is impossible to disconnect a pipe from a node with this tool.

The pipe theme has to be set up in the EPANET themes dialog in order to use this tool.

Note that the pipe length is not recalculated. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ The pipe length has to be calculated manually in the pipe theme attribute table. The Questions and Answers section of this manual contains an entry that deals with calculating the pipe length.

Change Node Class

A tool to convert nodes from one class to another.

The Change Node Class tool allows to convert e.g. a junction into pump. Attributes shared between the two classes are copied. After selecting an existing node, the user is prompted to select the class to which the node should be moved. The old node is deleted in order to prevent node duplication that would corrupt the hydraulic model.

Obviously, the respective themes have to be registered with the extension in the EPANET themes dialog.

Delete Feature

A tool to delete network features.

Allows one-click deletion of network features. The user is prompted to confirm the deletion. It is important to know that there's no undo support with the DC Water Design Extension.

The themes containing features that should be deleted have to be selected in the EPANET Themes dialog.

Digitize Junction

The Digitize Junction tool is used to digitize junctions.

The junctions are added to the junction theme selected in the EPANET themes dialog.

Digitize Pipe

The Digitize Pipe tool is used to digitize pipes.

The pipes are added to the pipe theme selected in the EPANET themes dialog. In order to maintain the network integrity, the tool automatically adds junctions at the pipe end if the pipe end does not snap onto an existing node.

Digitize Tank

The Digitize Tank tool is used to digitize tanks.

The tanks are added to the tank theme selected in the EPANET themes dialog.

Digitize Valve

The Digitize Valve tool is used to digitize valves.

The valves are added to the valve theme selected in the EPANET themes dialog. The tool is disabled if the valve theme is not enabled in the EPANET themes dialog.

Digitize Reservoir

The Digitize Reservoir tool is used to digitize reservoirs.

The reservoirs are added to the reservoir theme selected in the EPANET themes dialog. The tool is disabled if the reservoir theme is not enabled in the EPANET themes dialog.

Digitize Pump

The Digitize Pump tool is used to digitize pumps.

The pumps are added to the pump theme selected in the EPANET themes dialog. The tool is disabled if the pump theme is not enabled in the EPANET themes dialog.

Show Pipe Table Entry

Pop-up menu item that allows to show the attributes of a pipe.

Right-clicking on a pipe and selecting this menu item opens the pipe attribute table, selects and promotes the pipe.

The appropriate pipe theme has to be selected in the EPANET themes dialog.

Edit Pipe Table Entry

Pop-up menu item allowing to edit the attributes of a pipe.

Right-clicking on a pipe and selecting this menu item opens the pipe attribute table, makes it editable, selects and promotes the pipe record. After that, the attributes of the pipe can be edited. The DC Water Design Extension currently provides no undo functionality.

Select Connected Pipes

Pop-up menu item that allows to trace the pipes connected to the selected pipe.

Right-clicking on a pipe and selecting this menu item opens a dialog that offers node types at which the trace should stop. Multiple types can be selected. During the trace, the status bar informs what percentage of the network has been covered by the trace so far. The progress bar will not make it to 100% unless the network is fully connected and no stopping features have been selected. The connected pipes up to all stop points are returned as the selection.

Show Node Table Entry

Pop-up menu item that shows the attributes of a node.

Right-clicking on a node and selecting this menu item opens the node attribute table, selects and promotes the pipe.

The appropriate node theme has to be selected in the EPANET themes dialog.

Edit Node Table Entry

Pop-up menu item that allows to edit the attributes of a node.

Right-clicking on a node and selecting this menu item opens the node attribute table, makes it editable, selects and promotes the node record. After that the attributes of the node can be edited. Important notice: Undo is not supported by the extension.

Select Node

Selects the current node.

Adds the current node to the selection in the node theme.

The appropriate node themes has to be selected in the EPANET themes dialog.

Table GUI

Bitcode Calculator

The Bitcode Calculator is accessible from the button bar of the table GUI. It is disabled unless the table is editable and a numerical field is selected.

Upon clicking on the Bitcode Calculator button, the user is prompted to select the bits he wants to set.
After choosing OK, the bit code will be calculated and written to all the selected records.
If no records are selected the bit code is written to all the records in the table.

The field used to store the bit codes should have no decimal places.

Bitcodes are a concept that allows to transparently share network features in multiple supply zones. Section 11.1.1 contains more information on bit codes.

API Documentation

This section documents extension scripts that could be used from the field calculator or in queries. In Addition, the script responsible for the localization (extension dictionaries) is documented. In general, the API (Application Programming Interface) documentation should only be of concern for programmers.

DCWatDes.Bitcode.or

performs a bitwise or operation on integer numbers

integer DCWatDes.Bitcode.or(integer a, integer b)

a: bit-coded integer
b: bit-coded integer
Returns:: the result of the bitwise a or b as an integer

The following AVENUE code can be used in the field calculator to perform of a bitwise or-operation on the fields a and b:

av.run("DCWatDes.Bitcode.or", {[a], [b]})

DCWatDes.Bitcode.and

performs a bitwise and operation on integer numbers

integer DCWatDes.Bitcode.and(integer a, integer b)

a: bit-coded integer
b: bit-coded integer
Returns:: the result of the bitwise a and b as an integer

The following AVENUE code can be used in the field calculator to perform of a bitwise and-operation on the fields a and b:

av.run("DCWatDes.Bitcode.and", {[a], [b]})

DCWatDes.Bitcode.isSetAsNumber

return whether the n-th bit of an integer is set or not

integer DCWatDes.Bitcode.isSetAsNumber(integer a, integer n)

a: bit-coded integer
n: number of the bit to check
Returns:: an integer of value 1 in case the n-th bit is set, 0 otherwise

The following AVENUE query can be used to select all the records which have set the 4th bit in the example field (usable with the query tools of view and table GUI):

av.run("DCWatDes.Bitcode.isSetAsNumber",{[example], 3}) = 1

Note that the bit numbering starts at 0. ``= 1'' is used to convert the numbers 0 and 1 to the boolean values to true or false, respective.

DCWatDes.i18n.createDictionaries

Creates the localization dictionaries of the extension.

In order to add another dictionary, the new dictionary has to be created first:

dicNew = Dictionary.make(100)

Next, dictionary entries can be added to the new dictionary:

dicNew.add(``English Term'', ``New translated term'')

The German dictionary contains most of the terms that have to be translated. After all the terms have been added to the new dictionary, the Dictionary has to be added to the Dictionary of Dictionaries:

_dcwDicDictionaries.add(``tr'', dicNew)

Where ``tr'' is the text that shows up in the setup dialog of the extension.

Questions and Answers

Why is there no graphical user interface to the DCWatDes.Bitcode.* functions?

The provided AVENUE functions are more flexible this way. Bit codes can be useful for quite a number of operations. Try using the functions with the field calculator and the query. Examples are given in 11.3.6.

What is the Setup Dialog for?

The Extension depends on several software packages. The Setup Dialog allows to choose other versions of these software packages than the ones supplied with the Extension itself.

Why is Version 2.00 not working with Pipe 2000 anymore?

The Pipe 2000 data model, API and documentation are inferior to EPANET. Full integration of Pipe 2000 into ArcView was impossible. With EPANET it is possible to store the complete model, including all hydraulic analysis options in the GIS.

How do I recalculate the pipe length for all the pipes?

Open the attribute table of the pipe theme.
Make sure that the pipe theme is editable.
Make sure that no records are selected.
Click on the heading for the length field.
Click on the field calculator button.
Enter the following line into the value field:
[Shape].returnLength
Click OK.

I get strange errors when I try to create the EPANET model. What can I do?

Try the following:

Try ``Check EPANET model''. This helpful to resolve duplicate IDs.
Have a close look at the erroneous features: Often accidentally duplicates features cause trouble.

I made a mistake. Why is undo not working?

Undo support had to be taken out for the sake of editing multiple themes at the same time. Make frequent backups. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$ You have been warned.

I found a bug in the Extension. What should I do?

Please send your bug reports to Steffen_Macke@dorsch.com.jo

Copyright

DC Water Design Extension 2.00. This ArcView Extension integrates EPANET with ArcView.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Appendix 14 contains a copy of the GNU Lesser General Public License. $\resizebox*{0.05\columnwidth}{!}{\includegraphics{attention-sign.eps}}$

A Strategy to Reduce Technical Water Losses for Intermittent Water Supply