DC Water Design Extension Manual


Table of Contents

1. Introduction
1.1. What is the DC Water Design Extension?
1.2. What's New?
1.2.1. Version 2.12.3
1.2.2. Version 2.12.2
1.2.3. Version 2.12.1
1.2.4. Version 2.12
1.2.5. Version 2.11
1.2.6. Version 2.10
1.2.7. Version 2.09
1.2.8. Version 2.08
1.2.9. Version 2.07
1.2.10. Version 2.06
1.2.11. Version 2.05
1.2.12. Version 2.04
1.2.13. Version 2.03
1.2.14. Version 2.02
1.2.15. Version 2.01
2. Concepts
2.1. Network Traces
2.2. Virtual Lines
2.3. Byte Codes
2.4. Snapping
3. Installation
3.1. How to Obtain the DC Water Design Extension
3.2. Requirements
3.3. Setup
4. Quick Start Guide
5. Usage
5.1. General Usage
5.2. Project Menus
5.2.1. Setup
5.2.2. EPANET Tables
5.2.3. Result Tables
5.2.4. Split Model
5.2.5. Merge Model
5.2.6. Extract Model
5.2.7. About
5.3. View Menus
5.3.1. Write EPANET File
5.3.2. Run EPANET Calculation
5.3.3. Import Binary Result File
5.3.4. Import EPANET Inp File
5.3.5. Check EPANET Model
5.3.6. Load Results for Step ...
5.3.7. Make EPANET Model
5.3.8. EPANET Themes
5.3.9. EPANET Tables
5.3.10. Valve Control
5.3.11. Make House Connections
5.3.12. Create Supply Strings
5.3.13. Calculate Pipe Length For Junctions
5.3.14. Clip Themes by Bitcode
5.3.15. Create Zones from Controls
5.3.16. Create Missing Fields
5.3.17. Create Missing Junctions
5.3.18. Skeletonize Model
5.3.19. About DC Water Design Extension
5.4. View Tools
5.4.1. Flip Polylines
5.4.2. Move Nodes
5.4.3. Split Pipe (Add Junction)
5.4.4. Edit Pipe Vertices
5.4.5. Change Node Class
5.4.6. Delete Feature
5.4.7. Digitize Junction
5.4.8. Digitize Pipe
5.4.9. Digitize Tank
5.4.10. Digitize Valve
5.4.11. Digitize Reservoir
5.4.12. Digitize Pump
5.5. View Context Menus
5.5.1. Show Pipe Table Entry
5.5.2. Edit Pipe Table Entry
5.5.3. Select Connected Pipes
5.5.4. Select Connected Pipes Interactively
5.5.5. Show Node Table Entry
5.5.6. Edit Node Table Entry
5.5.7. Select Node
5.6. Table Buttons
5.6.1. Bytecode Calculator
5.7. Commandline Tools
5.7.1. inp2shp
5.7.2. epanet2mysql
6. Frequently Asked Questions
6.1. Why is there no graphical user interface to the DCWatDes.Bitcode.* functions?
6.2. What is the Setup Dialog for?
6.3. How do I recalculate the pipe length for all the pipes?
6.4. I get strange errors when I try to create the EPANET model. What can I do?
6.5. I made a mistake. Why is undo not working?
6.6. How do I add rule-based controls?
6.7. How do I add the initial status of a pump?
6.8. I found a bug in the Extension. What should I do?
6.9. How Can I Select All Rows where DC_ID is Longer than 13 Characters?
6.10. How Can I Select All Rows where DC_ID Contains Spaces?
7. Development
7.1. API Documentation
7.1.1. DCWatDes.Bitcode.or
7.1.2. DCWatDes.Bitcode.xor
7.1.3. DCWatDes.Bitcode.and
7.1.4. DCWatDes.Bitcode.isSetAsNumber
7.1.5. DCWatDes.i18n.createDictionaries
7.1.6. DCWatDes.Model.Epanet.Valves.controlByTime
7.2. Procedures
7.2.1. Release Process
8. Copyright
8.1. DC Water Design Extension
8.2. Apache Software
8.3. DC Water Design Extension Manual
9. ArcView/EPANET Data Model
9.1. Identity
9.2. Node
9.3. Junction
9.4. Tank
9.5. Pump
9.6. Valve
9.7. Pipe
9.8. Reservoir
9.9. Feature
9.10. Pattern
9.11. Options
9.12. Report
9.13. Times
9.14. VirtualLine
9.15. Curve

This Manual describes the DC Water Design Extension Version 2.12.2+cvs.

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

[Important]Important

Be sure to check the DC Processing Extension and the DC Sewer Design Extension which are also freely available. These extensions provide additional functionality that is very helpful. E.g. the DC Sewer Design Extension can be used to draw water network profiles.

This section introduces some concepts which are fundamental in order to understand how the extension works.

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:

The second possibility has some advantages, as it does not require additional data storage - it was applied in the described application. However, it imposes some restraints on the data. The concept to model virtual lines as points in the GIS can be summarized as follows:

  • Each virtual line needs to have exactly two pipes connected

  • Both connected pipes must be oriented in the same way: One pipe has to start at the virtual line and the other pipe has to end at the virtual line

Figure 1, “Virtual Line Validity” shows examples of different pipe orientations at a virtual line. The case a shows a pump with two pipes connected that are oriented in the same way. This allows the creation of the hydraulic model and is therefore considered valid. Case b shows pumps with pipes connected that are not oriented in the same way. This is invalid as is does not allow the creation of the hydraulic model. Case c is invalid because the pump has more than 3 pipes connected to it. Note that the orientation information of the pump symbol is not necessarily contained in the GIS data.

Figure 2, “Virtual Line Creation” depicts the conversion process of virtual lines:
  1. Number and orientation of the pipes connected to the virtual line are checked for validity

  2. The virtual node is replaced with a junction (PJ1).

  3. An additional junction is added (PJ2).

  4. The pipe from the virtual line to the next node starts at the additional junction. (PJ2 -> J2).

  5. The pump or valve is created. It connects the two new Junctions (PJ1 -> PJ2).

The DC Water Design Extension follows this conversion process when it is creating EPANET models. Additional considerations used in the process are:
  • The length of the virtual line is one metre. Figure 2, “Virtual Line Creation”

  • If the pipe starting at the virtual line is shorter than one metre, the virtual line length is set to half of the pipe length.

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:

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:

  • The models are numbered

  • Each byte represents one supply zone

  • If the byte 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 the following functions:

    DCWatDes.Bitcode.and
    DCWatDes.Bitcode.or
    DCWatDes.Bitcode.xor
    See Section 7.1, “API Documentation” for details regarding these functions.

[Note]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

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.

Description of the DC Water Design Extension Installation.

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:

  • Downloads

  • Documentation

  • Sources

  • Bug Tracker

  • Mailing List

  • Sample Data

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]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!

  1. Load the Extension.

  2. Open a View.

  3. Add Themes to the View. The Themes should describe your 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 (see Section 9, “ArcView/EPANET Data Model”). You can use ArcView field aliases to map the fields correctly.

  4. Click on the EPANET Themes button. Select the appropriate Themes.

  5. If your fieldnames don't match the ones of the data model, choose "Create Missing Fields" from the DC Water Design menu.

  6. If required, use the ArcView table calculator to populate the fields. Leaving fields empty is fine in most cases.

  7. Choose "Make EPANET Model" from the DC Water Design menu.

  8. If the last step didn't yield any errors, you can create an EPANET input file now. Choose "Write EPANET File" from the DC Water Design menu. Choose filename and location. In case of errors, running "Check EPANET Model" might help you to track down the most common error.

  9. Fire up EPANET and open the created file (*.inp).

How to use the DC Water Design Extension.

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:

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]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:

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

Allows to set valve states according to EPANET Controls.

If a controls table is registered with the Extension (see Section 5.3.9, “EPANET Tables”), the user is offered to select the controls he would like to apply. All chosen controls are applied. This is very useful in combination with Network Traces as the extension allows to stop traces at closed valves.

Tools that are added to the View GUI.

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”).

[Important]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.

This section contains information that is relevant to developers. Most probably you only want to read this if you are a programmer.

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.

Copyright information for the various components of the DC Water Design Extension.

This section describes the ArcView/EPANET Data Model. Note that the units will change if EPANET is not set to use liters per second (LPS) as units. Refer to the EPANET documentation (especially the toolkit help) for further information.

Inherits from VirtualLine