Copyright © 2001-2005 DORSCH Consult
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).
Table of Contents
- 1. Introduction
- 2. Concepts
- 3. Installation
- 4. Quick Start Guide
- 5. Usage
- 5.1. General Usage
- 5.2. Project Menus
- 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.5. View Context Menus
- 5.6. Table Buttons
- 5.7. Commandline Tools
- 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
- 8. Copyright
- 9. ArcView/EPANET Data Model
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]](images/important.png) | 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. |
Bug fixes for
DCWatDes.Bitcode.or()andDCWatDes.Bitcode.xor()functions.Improved "Bytecode Calculator" functionality (Section 5.6.1, “Bytecode Calculator”).
"Write Epanet File" collapses setting entries of valves to "closed" if they contain "closed".
"Extract Model" allows now to create one view per model (Section 5.2.6, “Extract Model”) and will extract demand junctions to a separate file if a field
HasDemandis found in the junction table..New "Enforce Data Model" option that allows to relax data model checks when editing networks (E.g. sewer or street networks). See Section 5.2.1, “Setup”.
Support for Backdrop Maps (Thanks to Roland Salgado, Section 5.3.1, “Write EPANET File”).
Create Zones From SOV Controls (Section 5.3.15, “Create Zones from Controls”).
Bugfix for coordinate systems using decimal feet (Bug reported by Arnold Strasser).
This section introduces some concepts which are fundamental in order to understand how the extension works.
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:
Number and orientation of the pipes connected to the virtual line are checked for validity
The virtual node is replaced with a junction (PJ1).
An additional junction is added (PJ2).
The pipe from the virtual line to the next node starts at the additional junction. (PJ2 -> J2).
The pump or valve is created. It connects the two new Junctions (PJ1 -> PJ2).
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).
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:
See Section 7.1, “API Documentation” for details regarding these functions.DCWatDes.Bitcode.and DCWatDes.Bitcode.or DCWatDes.Bitcode.xor
![[Note]](images/note.png) | 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. |
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
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! |
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.
Click on the EPANET Themes button. Select the appropriate Themes.
If your fieldnames don't match the ones of the data model, choose "Create Missing Fields" from the DC Water Design menu.
If required, use the ArcView table calculator to populate the fields. Leaving fields empty is fine in most cases.
Choose "Make EPANET Model" from the DC Water Design menu.
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.
Fire up EPANET and open the created file (*.inp).
- 5.1. General Usage
- 5.2. Project Menus
- 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.5. View Context Menus
- 5.6. Table Buttons
- 5.7. Commandline Tools
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:
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]](images/caution.png) | Caution |
|---|---|
The |
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 |
Extract separate models from the current one based on
the ByteCode content.
The definition query for all themes of the model will be removed by this operation.
See Section 2.3, “Byte Codes” for detailed information about byte codes.
Unlike Section 5.2.4, “Split Model” and Section 5.2.5, “Merge Model” this function support one-to-many relationships (One pipe can be part if different models).
- 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
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.
Exports the hydraulic model to an 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). |
Loads binary results of an EPANET calculation into ArcView.
The user will be prompted to select a time step for which the results will be loaded.
Imports an EPANET model from an EPANET INP file.
| 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”).
Creates the line-node structure required by EPANET.
In case there are reports about inconsistent flow direction at pumps or valves, you can use the "Flip Polylines" tool to correct the errors (Section 5.4.1, “Flip Polylines”).
Opens the EPANET Themes Dialog.
| Important |
|---|---|
Most of the extension functions require that the EPANET Themes are properly set up in this dialog. |
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.
Creates a straight pipe between tanks and junctions which share an id.
| 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.
Calculates a coded text that shows when a node is supplied with water.
| 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.
A string "00111" means that the pipe was supplied from the second to the fifth hour.
LINK link_id status AT TIME hours_since_simulation_startThe number of traces - which is equal to the number of hours from simulation start - can be chosen by the user. The function requires the Epanet model to be set up correctly (Including valves and controls).
Currently the function only supports networks that contain only shut off valves.
Creates fields required by the data model if they are missing in the EPANET themes.
This allows to quickly create data sets that conform with the EPANET data model.
Tools that are added to the View GUI.
This tool allows to flip the digitizing direction of lines.
![[Tip]](images/tip.png) | Tip |
|---|---|
ArcView's symbology can be used to display the digitizing direction with arrowheads. |
A tool to move network nodes including rubber-banding.
The respective themes have to be registered with the extension in the EPANET themes dialog.
Tool that allows to split a pipe into two pipes. Adds a new junction at the split point.
Pipe and junction themes have to be chosen in the EPANET themes dialog.
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. |
The Digitize Junction tool is used to digitize junctions.
The junctions are added to the junction theme selected in the EPANET themes dialog.
The Digitize Tank tool is used to digitize tanks.
The tanks are added to the tank theme selected in the EPANET themes dialog.
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”).
Pop-up menu item that allows to show the attributes of a pipe.
The appropriate pipe theme has to be selected in the EPANET themes dialog.
Pop-up menu item that allows to trace the pipes connected to the selected pipe.
| Tip |
|---|---|
The option "Closed Valves" will stop if
a feature in the valve theme contains the text "closed" in
the field |
Interactively traces connected pipes.
See Section 5.5.3, “Select Connected Pipes” for more information on network traces.
Pop-up menu item that shows the attributes of a node.
The appropriate node theme has to be selected in the EPANET themes dialog.
Table buttons that are added by the extension.
See Section 2.3, “Byte Codes” for details regarding byte codes.
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.
- 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?
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”.
| Important |
|---|---|
Undo support had to be taken out for the sake of editing multiple themes at the same time. Make frequent backups. |
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 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.
DCWatDes.Bitcode.or performs a bytewise or operation on string numbers.
string DCWatDes.Bitcode.or(string a, string b)
Returns: the result of the bytewise a or b as a string
av.run("DCWatDes.Bitcode.or", {[a], [b]})
DCWatDes.Bitcode.xor performs a bytewise xor operation on string numbers.
string DCWatDes.Bitcode.xor(string a, string b)
Returns: the result of the bytewise a xor b as a string
av.run("DCWatDes.Bitcode.xor", {"111", "101"})
DCWatDes.Bitcode.and performs a bytewise and operation on string numbers
string DCWatDes.Bitcode.and(string a, string b)
Returns: the result of the bytewise a and b as a string
av.run("DCWatDes.Bitcode.and", {[a], [b]})
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})
= 1The 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 "0001".middle(3,1) = "1" |
Creates the Localization dictionaries of the Extension
In order to add another Dictionary, you'll first have to create one:
dicNew = Dictionary.make(100)
Then you can start adding dictionary entries:
dicNew.add("English Term", "New translated term")Look at the German dictionary for the terms that have to be translated. After you've added all the terms to the new Dictionary, you have to add the Dictionary to the Dictionary of Dictionaries:
_dcwDicDictionaries.add("de", dicNew)
Where "de" is describes the locale (In this case "de" for Germany).
Updates the valves status field, reflecting the status at a given time.
All valves are closed before applying the controls.
Expects the timestep as a number as the argument (Hours since simulation start).
Requires valves theme and controls table registered with the extension.
Works only for SOV valves. The supported controls syntax is:
LINK link_id status AT TIME hours_since_simulation_start
Copyright information for the various components of the DC Water Design Extension.
DC Water Design Extension. This ArcView Extension integrates EPANET with ArcView.
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).
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.
Initiallevel: float Initial water level above the tank bottom level (the elevation field) in m.
Minimumlevel: float Minimum water level above the tank bottom level in m.
Maximumlevel: float Maximum water level above the tank bottom level in m.
Minimumvolume: float The minimum volume of the tank in cubic meters. Can be zero.
Volumecurve: string The id of the volumecurve - for non-cylindrical tanks.
Type: string Type of the valve. The following EPANET valve types are valid:
Additional valve types supported by the DC Water Design Extension:EPANET models check valves and shuoff valves as pipes. The extension will create the necessary pipes on the fly (Virtual Lines, see Section 2.2, “Virtual Lines”).CV check valve
SOV shutoff valve
Setting: string Valve type dependent setting. The setting field takes the following values for the different valve types:
PRV the pressure in m
PSV the pressure in m
PBV the pressure in m
FCV the flow in liters per second
TCV the loss coefficient
GPV the id of the head loss curve
CV the setting value will be mapped to the status field of the pipe
SOV the setting value will be mapped to the status field of the pipe
Minorloss: float Minor loss coefficient of the valve.
status: string Status of the pipe. The following values are valid:
Material: CodedValue Integer field containing a coded value describing the material of the pipe.
result_flow: float EPANET analysis result: The flow in liters per second.
result_velocity: float EPANET analysis result: Flow velocity in meters per second.
File: string The name of the report file. Leave empty if you use the DC Water Design Extension.
- The default is NO.
Summary: string Determines whether a Summary is generated. The following values are valid:
Default is YES.- The default is YES.
- The default is NO.
Nodes: string Determines which nodes will be reported on. The following values are valid:
The default is NONE.Links: string Determines which links will be reported on. The following values are valid:
The default is NONE.
Ruletimestep: string Used with rule-based controls. Defaults to 1/10 of the hydraulic time step.
Patternstart: string Describes when the pattern cycle will be started. Defaults to 0.
Reporttimestep: string The interval in which results will be reported. The default is 1 hour.
Reportstart: string Determines the time when reporting starts. The default is 0.