DC Water Design Extension Manual

The DC Water Design Extension is an Extension to ESRI's ArcView GIS software. Starting with Versions 2.00 the DC Water Design Extension 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's possible to run the EPANET hydraulic analysis from ArcView and load the results into the GIS.

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

See Section 5.5.3, “Select Connected Pipes”.

In the EPANET hydraulic model, pumps and valves are represented as lines. From the hydraulic modeling point of view this makes sense, as the orientation of the valves and pumps is important information. In GIS data, pumps and valves are typically represented as points, as they are also symbolized with point symbols. Point data is lacking the orientation information. Because of the pipe-node duality pipes and valves will be referred to as virtual lines in this section.

The pipe-node duality complicates the creation of hydraulic models from the GIS data. It is possible to overcome the problem with one of the following solutions:

Figure 1. Virtual Line Validity

Figure 2. Virtual Line Creation

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 have to have the same digitizing direction (which will be the flow direction in the hydraulic model).

Byte codes make it possible to store fields of yes-no information in 'normal' text. Every byte in the number having the value "1" is considered set, every byte of value "0" is not set. Thus making it possible to code several independent pieces of information in one ArcView string.

As ArcView shapefiles allow to store strings of up to 255 characters length, it is possible to store up to 255 pieces of information.

The following example shows how this concept allows storing the network information in one seamless data set and utilizing the same network features in different hydraulic models:

Figure 3. Byte-coding Supply Zones

In Figure 3, “Byte-coding Supply Zones” the nodes of three hydraulic models are byte-coded for storage in the GIS. Each zone has its own byte in the byte code, indicating if the node is used in the model or not.

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

	Note
	Note that the byte numbering starts at 1. You should use a temporary field in order to perform the addition of two byte codes correctly.

	Note
	Note that you should use a different concept if you want to split up your model for editing purposes. The byte code concept models a one to many relationship, but for editing purposes, a one to one relationship should be used. This makes the automatic assembly of the model after editing easier.

The editing tools of the DC Water Design Extension use a snapping tolerance equal to 3 screen pixels.

The DC Water Design Extension can be obtained from the website http://dcwaterdesign.sourceforge.net.

The sourceforge site offers a multitude of services related to the DC Water Design Extension, including:

The following software packages are required in order to use the DC Water Design extension:

	Note
	Note that the commandline tools described in Section 5.7, “Commandline Tools” do not rely on ArcView or the Windows operating system. They are platform independent, however you may have to compile them for your platform.

To install the DC Water Design Extension, you've got to run the installer executable. After accepting the license (s. Section 8.1, “DC Water Design Extension”), you'll be prompted 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. The only thing left to do now is to select which components of the extension should be installed. In general, you should install all the components of the extension.

	Note
	If you want to use e.g. a newer version of the XSLT parser and you've installed that version already, you might decide not to install the XSLT parser that comes with the extension. Don't do this unless you know what you're doing!

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:

5.2.1. Setup

Shows the Setup Dialog.

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

• Arabic

• English

• German

• Russian

	Note
	Note that the Localization is not completed yet. It is therefore recommended that you set the language to English.

The snapping radius used for network traces and model building is also customizable in this dialog. Usually the default setting should be kept.

The backdrop resolution specifies the resolution of the backdrop map if you write your EPANET files with backdrop maps. Set to a higher resolution if required.

The command timeout specifies the time in seconds for which the extension will wait when creating epanet files or running epanet calculations. If the EPANET run doesn't finish in time, there'll be an error message.

Deselecting the Enforce Data Model checkbox allows to relax checks on fields required for EPANET.

	Tip
	Deselect the Enforce Data Model checkbox when editing street or sewer networks.

5.2.4. Split Model

Allows to split a model into different ones.

The values of the Zone field will be used to determine to which model a network element belongs

The sub-models will be stored in subfolders named like the zones.

Section 5.2.5, “Merge Model” can be used to re-assemble the model automatically.

	Caution
	The Zone field has to be filled for all records.

5.2.5. Merge Model

Merge a model that was split by Section 5.2.4, “Split Model”.

Because "Merge Model" is using the zone names from the main pipes theme, it is not possible to add new zones by simply adding a new folder. New zones have to be introduced in the main file first.

	Caution
	The Zone field should be filled for all records. Empty fields will be filled with the zone name from the folder.

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

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

The additional functionality is explained below.

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

Optionally, a Backdrop Map is exported together with the EPANET model. This requires additional themes in the View e.g. pressure zones or a street layer. The resolution of the backdrop map can be specified in the setup dialog (see Section 5.2, “Project Menus”). A backdrop will only be written, if the view contains visible themes in addition to the EPANET themes.

	Note
	The resulting EPANET input file has the extension *.inp. The *.xml-file is just an intermediate format (temporary file).

5.3.4. Import EPANET Inp File

Imports an EPANET model from an EPANET INP file.

The EPANET INP format is an ASCII format (it can be easily edited by any text editor) that is documented in the EPANET toolkit. The windows version of EPANET can export models to this format (File -> Export -> Network ...).

	Caution
	Currently the function will not import the full EPANET model. Be sure to check whether the imported results fit your needs.

The function uses the inp2shp command. (Section 5.7.1, “inp2shp”).

5.3.8. EPANET Themes

Opens the EPANET Themes Dialog.

Use the Dialog to select the themes you want to use in your 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.

	Important
	Most of the extension functions require that the EPANET Themes are properly set up in this dialog.

Setting up the themes should be the first step when using the extension. The settings are also used to determine which themes should be edited.

5.3.11. 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 he 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 Geoprocessing Wizard.

	Note
	Note that this functionality has been included mainly for the purpose of modeling intermittent supply with household storage tanks.

It might be taken out or completely rewritten in future versions of the DC Water Design Extension.

5.3.12. 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
	Note that this functionality has been included mainly for the purpose of modeling intermittent supply with household storage tanks.

It might be taken out or completely rewritten in future versions of the DC Water Design Extension.

	  LINK link_id status AT TIME hours_since_simulation_start
	  

Tools that are added to the View GUI.

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

5.4.4. 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's 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.

	Important
	Note that the pipe length is not recalculated.

Recalculate the pipe length manually in the pipe theme attribute table. See the Questions and Answers section of this manual if you have problems calculating the pipe length.

The context menu items described in this section are available if the right mouse button is pressed over a theme that has been registered with the DC Water Design Extension (See Section 5.3.8, “EPANET Themes”).

5.5.3. 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. Note that the progress bar won't make it to 100% unless the network is fully connected and no stopper has been selected. The connected pipes up to all stop points are returned as the selection.

	Tip
	The option "Closed Valves" will stop if a feature in the valve theme contains the text "closed" in the field status.

Table buttons that are added by the extension.

Several commandline tools that are available together with the DC Water Design Extension.

If you do not know what a commandline tool is, you may want to skip this section as the DC Water Design Extension provides

Note that these tools don't rely on ArcView and may be used independent of the DC Water Design Extension.

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 Section 7.1, “API Documentation”.

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

Try the following:

	Important
	Undo support had to be taken out for the sake of editing multiple themes at the same time. Make frequent backups.

You've been warned.

If you have a text file for simple controls, add lines like the following to it:

[RULES]
      
      RULE 1 IF TANK LEVEL 1 ABOVE 19.1
      
      THEN PUMP 355 STATUS IS CLOSED

Just add it to the properties field of the pump like in the following example:

	HEAD Curve1 SPEED 1.2

Please send your bug reports to <dcwaterdesign-info@lists.sourceforge.net> or use the bug tracker on the website.

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

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

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

	string DCWatDes.Bitcode.xor(string a, string b)

	av.run("DCWatDes.Bitcode.xor", {"111", "101"})
	

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

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

7.1.4. DCWatDes.Bitcode.isSetAsNumber

DCWatDes.Bitcode.isSetAsNumber returns whether the n-th byte of a string is set or not

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

a byte-coded string

n number of the byte to check

Returns: an integer of value 1 in case the n-th byte 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",{"0001", 3}) 
	  = 1

The expression will return true

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.

	Tip
	Note that you can also use the middle() function to find out whether a byte is set: "0001".middle(3,1) = "1"

	dicNew = Dictionary.make(100)

	dicNew.add("English Term", "New translated term")

	_dcwDicDictionaries.add("de", dicNew)

LINK link_id status AT TIME hours_since_simulation_start

Procedures in the development process.

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

Copyright (C) 1998-2005 DORSCH Consult

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

testXSLT (Xalan C++) Copyright (C) 2000 Apache Software Foundation. All rights reserved.

Visit http://xml.apache.org for the details and/or sources.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from the Free Software Foundation (http://www.gnu.org).

Inherited by Feature

Inherited by Pattern

Inherited by Curve

Inherits from Feature

Inherited by Junction

Inherited by Tank

Inherited by Reservoir

Inherited by VirtualLine

Inherits from Node

Inherits from Node

Inherits from VirtualLine

Inherits from VirtualLine

Inherits from Feature

Inherits from Node

Inherited by Node

Inherited by Pipe

Inherits from Identity

Inherits from Identity

Times can be specified in SECONDS(SEC), MINUTES (MIN), HOURS or DAYS. Just enter the unit name after the value. The default time unit is hours.

Inherited by Pump

Inherited by Valve

Inherits from Node

Inherits from Identity