Water Security Toolkit User Manual Version 1.2

(1)

SANDIA REPORT

SAND2014-16973

Unlimited Release

Printed August 2014

Water Security Toolkit User Manual

Version 1.2

Katherine Klise

1

, John Siirola

1

, David Hart

1

, William Hart

1

, Cynthia Phillips

1

, Terranna Haxton

2

, Regan

Murray

2

, Robert Janke

2

, Thomas Taxon

3

, Carl Laird

4

, Arpan Seth

4

, Gabriel Hackebeil

4

, Shawn McGee

4

,

Angelica Mann

4

1 _{Sandia National Laboratories, PO Box 5800 MS 0751, Albuquerque, NM 87185}

2 _{National Homeland Security Research Center, Office of Research and Development, U.S. Environmental}

Protection Agency, Cincinnati, OH 45256

3

Argonne National Laboratory, 9700 S. Cass Avenue, Argonne, IL 60439

4 _{Texas A&M University, Chemical Engineering Department, College Station, TX 77843}

Prepared by

Sandia National Laboratories

Albuquerque, New Mexico 87185 and Livermore, California 94550

Sandia National Laboratories is a multi-program laboratory managed and operated by Sandia Corporation, a wholly owned subsidiary of Lockheed Martin Corporation, for the U.S. Department of Energy's

National Nuclear Security Administration under contract DE -AC04-94AL85000. Approved for public release; further dissemination unlimited.

(2)

Issued by Sandia National Laboratories, operated for the United States Department of Energy by Sandia Corporation.

NOTICE: This report was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government, nor any agency thereof, nor any of their employees, nor any of their contractors, subcontractors, or their employees, make any warranty, express or implied, or assume any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represent that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government, any agency thereof, or any of their contractors or subcontractors. The views and opinions expressed herein do not necessarily state or reflect those of the United States Government, any agency thereof, or any of their contractors.

Printed in the United States of America. This report has been reproduced directly from the best available copy.

Available to DOE and DOE contractors from U.S. Department of Energy

Office of Scientific and Technical Information P.O. Box 62

Oak Ridge, TN 37831

Telephone: (865) 576-8401 Facsimile: (865) 576-5728 E-Mail: [email protected] Online ordering: http://www.osti.gov/bridge Available to the public from

U.S. Department of Commerce National Technical Information Service 5285 Port Royal Rd.

Springfield, VA 22161

Telephone: (800) 553-6847 Facsimile: (703) 605-6900

E-Mail: [email protected]

(3)

SAND2014-16973

Unlimited Release

Printed August 2014

Water Security Toolkit User Manual

Version 1.2

Katherine Klise

1

, John Siirola

1

, David Hart

1

, William Hart

1

, Cynthia Phillips

1

, Terranna Haxton

2

, Regan

Murray

2

, Robert Janke

2

, Thomas Taxon

3

, Carl Laird

4

, Arpan Seth

4

, Gabriel Hackebeil

4

, Shawn McGee

4

,

Angelica Mann

4

1 _{Sandia National Laboratories, PO Box 5800 MS 0751, Albuquerque, NM 87185}

2 _{National Homeland Security Research Center, Office of Research and Development, U.S. Environmental}

Protection Agency, Cincinnati, OH 45256

3

Argonne National Laboratory, 9700 S. Cass Avenue, Argonne, IL 60439

4 _{Texas A&M University, Chemical Engineering Department, College Station, TX 77843}

Abstract

The Water Security Toolkit (WST) is a suite of open source software tools that can be used by water

utilities to create response strategies to reduce the impact of contamination in a water distribution

network. WST includes hydraulic and water quality modeling software, optimization methodologies, and

visualization tools to identify: (1) sensor locations to detect contamination, (2) locations in the network in

which the contamination was introduced, (3) hydrants to remove contaminated water from the distribution

system, (4) locations in the network to inject decontamination agents to inactivate, remove, or destroy

contaminants, (5) locations in the network to take grab samples to help identify the source of

contamination and (6) valves to close in order to isolate contaminated areas of the network. This user

manual describes the different components of WST, along with examples and case studies.

(4)

License Notice

The Water Security Toolkit (WST) v.1.2

Copyright c 2012 Sandia Corporation. Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive license for use of this work by or on behalf of the U.S. government.

This software is distributed under the Revised BSD License (see below). In addition, WST leverages a variety of third-party software packages, which have separate licensing policies:

Acro Revised BSD License

argparse Python Software Foundation License

Boost Boost Software License

Coopr Revised BSD License

Coverage BSD License

Distribute Python Software Foundation License / Zope Public License

EPANET Public Domain

EPANET-ERD Revised BSD License

EPANET-MSX GNU Lesser General Public License (LGPL) v.3

gcovr Revised BSD License

GRASP AT&T Commercial License for noncommercial use; includes randomsample and

sideconstraintsexecutable files

LZMA SDK Public Domain

nose GNU Lesser General Public License (LGPL) v.2.1

ordereddict MIT License

pip MIT License

PLY BSD License

PyEPANET Revised BSD License

Pyro MIT License

PyUtilib Revised BSD License

PyYAML MIT License

runpy2 Python Software Foundation License

setuptools Python Software Foundation License / Zope Public License

six MIT License

TinyXML zlib License

unittest2 BSD License

Utilib Revised BSD License

virtualenv MIT License

Vol Common Public License

vpykit Revised BSD License

Additionally, some precompiled WST binary distributions might bundle other third-party executables files: Coliny Revised BSD License (part of Acro project)

Dakota GNU Lesser General Public License (LGPL) v.2.1 PICO Revised BSD License (part of Acro project)

(5)

Revised BSD License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of Sandia National Laboratories nor Sandia Corporation nor the names of its con-tributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IM-PLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUD-ING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

(6)

Acknowledgements

This work was supported by the U.S. Environmental Protection Agency through its Office of Research and Development (Interagency Agreement # DW8992192801). The material in this document has been subject to technical and policy review by the U.S. EPA, and approved for publication. The views expressed by individual authors, however, are their own, and do not necessarily reflect those of the U.S. Environmental Protection Agency. Mention of trade names, products, or services does not convey official U.S. EPA approval, endorsement, or recommendation.

The Water Security Toolkit is an extension of the Threat Ensemble Vulnerability Assessment-Sensor Place-ment Optimization Tool (TEVA-SPOT), which was also developed with funding from the U.S. Environ-mental Protection Agency through its Office of Research and Development (Interagency Agreement # DW8992192801). The authors acknowledge the following individuals for their contributions to the devel-opment of TEVA-SPOT: Jonathan Berry (Sandia National Laboratories), Erik Boman (Sandia National Laboratories), Lee Ann Riesen (Sandia National Laboratories), James Uber (University of Cincinnati), and Jean-Paul Watson (Sandia National Laboratories).

(7)

Acronyms

ATUS American Time-Use Survey BLAS Basic linear algebra sub-routines

CFU Colony-forming unit

CVAR Conditional value at risk CWS Contamination warning system

EA Evolutionary algorithm

EDS Event detection system

EPA U.S. Environmental Protection Agency

EC Extent of Contamination

ERD EPANET results database file

GLPK GNU Linear Programming Kit

GRASP Greedy randomized adaptive sampling process

HEX Hexadecimal

HTML HyperText markup language

INP EPANET input file

LP Linear program

MC Mass consumed

MILP Mixed integer linear program

MIP Mixed integer program

MSX Multi-species extension for EPANET NFD Number of failed detections

NS Number of sensors

NZD Non-zero demand

PD Population dosed

PE Population exposed

PK Population killed

TAI Threat assessment input file TCE Tailed-conditioned expectation

TD Time to detection

TEC Timed extent of contamination

TEVA Threat ensemble vulnerability assessment

TSB Tryptic soy broth

TSG Threat scenario generation file TSI Threat simulation input file

VAR Value at risk

VC Volume consumed

WST Water Security Toolkit

(8)

Symbols

Notation Definition Example

{,} set brackets {1,2,3} means a set containing the values 1,2, and 3.

∈ is an element of s∈S means thatsis an element of the setS.

∀ for all s= 1∀s∈S means that the statements= 1 is true for allsin

set S.

P _summation Pn

i=1si meanss1+s2+· · ·+sn.

\ set minus S\T means the set that contains all those elements ofS that are not in set T.

| given |is used to define conditional probability. P(s|t) means the prob-ability ofsoccurring given thatt occurs.

|...| cardinality Cardinality of a set is the number of elements of the set. If setS ={2,4,6}, then |S|= 3.

(9)

13.2.1 Usage . . . 154 13.2.2 Options . . . 154 13.2.3 Arguments . . . 154 13.3 measuregen . . . 155 13.3.1 Usage . . . 155 13.3.2 Options . . . 155 13.3.3 Arguments . . . 156 13.4 scenarioAggr . . . 157 13.4.1 Usage . . . 157 13.4.2 Options . . . 157 13.4.3 Arguments . . . 157 13.5 spotSkeleton . . . 158 13.5.1 Usage . . . 158 13.5.2 Arguments . . . 158

References

159

(15)

List of Figures

2.1 Thetevasimtemplate screen output. . . 9

3.1 Contaminant transport simulation flowchart. . . 10

3.2 Thetevasimconfiguration template file. . . 12

3.3 Layout of the EPANET Example Network 3. . . 15

3.4 Example TSG contamination scenario file. . . 15

3.5 Thetevasimconfiguration file for example 1. . . 16

3.6 Thetevasimconfiguration file for example 2. . . 16

4.1 Impact assessment flowchart. . . 17

4.2 Thesim2Impactconfiguration template file. . . 24

4.3 Thesim2Impactconfiguration file for example 1. . . 26

5.1 Sensor placement flowchart. . . 28

5.2 Thespconfiguration template file. . . 41

5.3 Thespconfiguration file for example 1. . . 42

5.4 ThespYAML output file for example 1. . . 43

5.5 The evalsensor output forspexample 1. . . 43

5.10 The spconfiguration file for example 4. . . 48

5.11 The evalsensor output for spexample 4. . . 48

(16)

6.1 Flushing response simulation flowchart. . . 56

6.2 Theflushingconfiguration template file. . . 64

6.3 Theflushingconfiguration file for example 1. . . 66

6.4 TheflushingYAML output file for example 1. . . 67

7.1 Multi-species reaction booster placement flowchart. . . 72

7.2 MIP booster placement flowchart. . . 72

7.3 Thebooster_msxconfiguration template file. . . 75

7.4 Thebooster_mipconfiguration template file. . . 88

7.5 Thebooster_mipconfiguration file for example 1. . . 89

7.6 Thebooster_mipYAML output file for example 1. . . 90

7.7 Thebooster_msxconfiguration file for example 2. . . 91

8.1 Contamination source identification flowchart. . . 92

8.2 Two different injection profiles used by the formulation variations. . . 94

8.3 Theinversionconfiguration template file. . . 97

8.4 Theinversionconfiguration file for example 1. . . 100

8.5 TheinversionYAML output file for example 1. . . 101

8.6 Theinversionconfiguration file for example 2. . . 102

8.7 TheinversionYAML output file for example 2. . . 102

9.1 Grab sampling flowchart. . . 103

9.2 Thegrabsampleconfiguration template file. . . 105

9.3 Thegrabsampleconfiguration file for example 1. . . 109

9.4 ThegrabsampleYAML output for example 1. . . 110

10.1 Visualization flowchart. . . 112

10.2 The visualizationconfiguration template file. . . 114

(17)

10.4 Graphic from visualizationexample 1. . . 120

10.5 The visualizationconfiguration file for example 2. . . 121

10.6 The location file used invisualizationexample 2. . . 121

10.7 Graphic from visualizationexample 2. . . 122

11.1 Illustration of the origin tracking algorithm. . . 124

11.2 The spconfiguration file using the GLPK solver to compute a lower bound. . . 125

11.3 The spYAML file with the lower bound from the GLPK solver. . . 126

11.4 The spconfiguration file using the Lagrangian solver. . . 126

11.5 The spYAML file with the lower bound from the Lagrangian solver. . . 127

11.6 The spconfiguration file using the Lagrangian solver and the compute bound option. . . 128

11.7 The evalsensorexample output. . . 130

11.8 The evalsensoroutput using sensor failure probabilities. . . 131

11.9 Illustration of the source inversion and grab sample cycling strategy. . . 132

11.10Fixed sensors (blue) and contamination location (red) for case study. . . 133

11.11The possible injection nodes (red) and optimal grab sample locations (blue) identified in Cycle 1. . . 134

11.12The possible injection nodes (red) and optimal grab sample locations (blue) identified in Cycle 2. . . 135

11.13The possible injection nodes (red) identified in Cycle 3. . . 136

11.14Net6 water distribution network with water quality sensors. . . 137

11.15Net6 with positive contamination detection at JUNCTION-1617. . . 138

11.16Net6 with possible contamination sources identified byinversionsubcommand. . . 139

11.17Net6 with nodes impacted by the 25 possible contamination sources. . . 140

11.18Net6 with the flushing nodes identified by theflushingsubcommand. . . 141

(18)

Chapter 1 Introduction

An abundant supply of safe, high-quality drinking water is critical to modern industrialized societies. At home, water is used for drinking, cooking, washing clothes and bathing. At work, water is used to operate restaurants, hospitals and manufacturing plants. In our communities, water is used for fighting fires. Conse-quently, contamination of drinking water infrastructure could severely impact the public health and economic vitality of a community. The distributed physical layout of drinking water systems makes them inherently vulnerable to a variety of incidents, such as terrorist attacks, accidents and even natural disasters. The physical destruction of water infrastructure can disrupt water service to communities, and particularly key facilities such as hospitals, power stations and military installations. Similarly, contamination with deadly agents could result in large numbers of illnesses and fatalities.

Since the events of September 11, 2001, water utilities have had increasing concerns about the possibility of harm to our water quality due to an accidental or intentional contamination incident within a distribution network. The U.S. EPA’s Response Protocol Toolbox (EPA, 2004) provides recommendations on actions that water utilities can take to minimize potential impacts to consumers following a contamination threat or incident. Detection and consequence management are major steps in this protocol. EPA has also developed modeling and simulation tools to assist in the detection of contamination incidents in water distribution networks. The Threat Ensemble Vulnerability Assessment-Sensor Placement Optimization Tool, or TEVA-SPOT (EPA, 2011), identifies the optimal placement of online water quality monitoring sensors to detect contamination incidents. Another EPA developed tool to assist in detection is the CANARY event detection system (Hart and McKenna, 2012), which analyzes water quality data from the sensors and identifies periods of anomalous water quality. These tools work together to help form a contamination warning system (CWS). The overall goal of a CWS is to detect contamination incidents in time to reduce potential public health and economic consequences. The current terminology for a CWS is a water quality surveillance and response system. For more information on CWS, see U.S. EPA Water Security Initiative (EPA, 2013b).

Should a CWS detect the presence of contamination in a water distribution network, consequence manage-ment must be employed. Decision-making tools that assist water utilities in evaluating and planning various response strategies are needed to support rapid response to contamination incidents. The Water Security Toolkit (WST) is a suite of tools that help provide the information necessary to make good decisions resulting in the minimization of further human exposure to contaminants, and the maximization of the effectiveness of intervention strategies. WST is intended to assist in:

• Planning response actions to natural disasters and terrorist attacks,

• Developing consequence management plans,

• Informing large-scale exercises/training,

• Planning response actions to address traditional utility challenges, such as pipe breaks and water quality problems and

(19)

• Evaluating implications of different response strategies.

For water utilities with hydraulic modeling expertise, WST combined with EPANET-RTX (EPA, 2013a; Hatchett et al., 2011; Janke et al., 2011) could use data from CANARY, other sensor stations and field investigations to optimize and implement response actions in real-time.

WST assists in the evaluation of multiple response actions in order to select the most beneficial consequence management strategy. It includes hydraulic and water quality modeling software and optimization method-ologies to identify: (1) sensor locations to detect contamination, (2) locations in the network in which the contamination was introduced, (3) hydrants to remove contaminated water from the distribution system, (4) locations in the network to inject decontamination agents to inactivate, remove or destroy contaminants, (5) locations in the network to take grab sample to confirm contamination or cleanup and (6) valves to close in order to isolate contaminated areas of the network.

This user manual describes the different components of WST. It is also available as an EPA Report EPA (2013c). The manual contains one chapter on each of the water security tools:

• Contaminant transport • Impact assessment • Sensor placement • Hydrant flushing • Booster placement • Source identification • Grab sampling • Visualization

Another chapter discusses advanced topics and provides case studies. WST uses YAML format configuration files to supply input parameters to each water security tool. Additional information on the YAML format can be found in File Formats Section 12.1.

The contaminant transport simulation, impact assessment and sensor placement optimization tools were all developed as part of the TEVA-SPOT Toolkit (EPA, 2011). All functionality in TEVA-SPOT has been replicated in WST using new, user friendly YAML format configuration files. WST builds upon the simulation and optimization framework of TEVA-SPOT and adds several new features. These features were all developed to model possible response action plans once contamination has been detected in the system. These action plans include redirecting flow by either opening hydrants or closing valves, injecting decontaminant to inactivate biological agents and using sensor measurements to identify possible source locations.

The main data requirement to use WST is a calibrated water utility network model. Additional input data is dependent on the WST application. This includes information on the simulated contamination incident(s) (e.g., type, location(s), amount), the impact metric (e.g., extent of contamination, population exposed), and the response actions (e.g., flushing hydrants, injecting disinfectant). To optimize a response action, additional information on the potential locations for water quality sensors, hydrants to flush, valves to close, disinfectant booster stations and manual grab samples is needed. The operating characteristics of these different response actions are also required, such as the detection limits of the water quality sensors, the rate and duration that hydrants can be flushed, the control settings for injecting disinfectant at booster stations and the number of manual grab samples that can be taken at the same time. More details on the data requirements are provided in the chapter describing the specific water security tool. In addition, each

(20)

chapter has example applications. All examples are included with WST and can be found in the examples folder. These examples use simple networks and data files that are also distributed with WST. The examples shown in this user manual are all executed on a Linux computer, so the CPU time for each example might not be the same on computers with different operating systems.

(21)

Chapter 2 Getting Started

This chapter provides information on downloading and installing WST. WST is an open source toolkit for modeling and analyzing water distribution systems to minimize the potential impact of contamination incidents.

2.1 Obtaining the Water Security Toolkit

WST is distributed by Sandia National Laboratories in both source and pre-built binary forms through the World Wide Web athttps://software.sandia.gov/trac/wst. From the main WST web page, click the Download WST link. The download page has options to download the WST source code as well as pre-built binary packages for 32- and 64-bit Windows, and 64-bit Linux. For most users, installing pre-built binary versions of WST is recommended. Along with formal releases, a VOTD (version of the day) build can also be downloaded. This package is an automated build of the current development branch of the code meant to facilitate rapid dissemination of research developments to interested partners. VOTD builds should be considered bleeding edge and might frequently be unstable; as such, general users are discouraged from relying on them for any production analyses.

Alternatively, the WST source code can be checked out directly from the master Subversion version control system throughhttps://software.sandia.gov/svn/wst/. In particular, the mainline trunk development branch can be checked out with

svn checkout https://software.sandia.gov/svn/wst/wst/trunk wst

Individual releases are archived in thehttps://software.sandia.gov/svn/wst/wst/tags directory. The repository contains references to external repositories (notably, the EPANET repository on SourceForge). Please note that your local network configuration might require site-specific Subversion proxy settings, as well as network access tohttps://software.sandia.govandhttps://epanet.svn.sourceforge.net.

2.2 Dependencies of the Water Security Toolkit

WST is a collection of Python and compiled C++ software. It has dependencies on several third-party software packages. First and foremost, a Python interpreter must be installed. WST is currently compatible with Python 2.6 or 2.7. Python 3.x is not yet supported. Python is available fromhttp://python.org/. The WST source code and binary distributions bundle several additional Python packages, including:

Coopr

A collection of open-source optimization-related Python packages that support a diverse set of optimization capabilities for formulating and analyzing optimization models. Coopr in turn bundles several third-party dependency libraries:

(22)

A Python command line argument parsing utility. coverage

A Python utility for capturing and reporting code coverage. distribute

A Python utility for building and installing Python packages. gcovr

A utility for parsing and reporting GCOV code coverage reports. nose

A Python test-harness driver. ordereddict

A utility that back-ports ordered dictionaries to Python 2.6. pip

A Python utility for installing Python packages. ply

A general parser-lexer. pyro

A utility for managing distributed Python execution. runpy2

A utility that back-ports runpy functionality to Python 2.4. setuptools

A Python utility for building and installing Python packages. six

A utility that provides a portable interface to Python 2.x and 3.x. unittest2

A utility that back-ports unittest functionality from Python 2.7 to 2.3-2.6. virtualenv

A utility for creating virtual Python environments. PyUtilib

A collection of Python utilities, including the testing harness used in WST. PyEPANET

Python wrappers for the EPANET 2.0 Programmers Toolkit. PyYAML

A YAML parser and emitter for Python.

WST subcommands can leverage numerous third-party programs that are not available in the WST source code:

AMPL

A commercial algebraic modeling environment, available fromhttp://www.ampl.com/. CBC

An open-source mixed-integer linear programming solver, available from https://projects. coin-or.org/Cbc. The COIN Binary Project provides pre-compiled binaries through the CoinAll distribution, available fromhttps://projects.coin-or.org/CoinBinary.

CPLEX

A commercial mixed-integer linear programming solver, available from http://www.ibm.com/ software/integration/optimization/cplex-optimizer/.

Coliny

An open-source package that provides algorithms for model transformation and black-box opti-mization, available as the Acro-coliny project fromhttps://software.sandia.gov/trac/acro/. Dakota

(23)

surrogate modeling and uncertainty quantification, available from http://dakota.sandia.gov/. For Windows users, the 5.1 MinGW build is recommended.

GLPK

An open-source mixed-integer linear programming solver, available from http://www.gnu.org/ software/glpk/. Pre-compiled binary distributions are available as part of most UNIX-like oper-ating systems. The GLPK for Windows Project provides pre-compiled Windows binaries, available fromhttp://winglpk.sourceforge.net/.

Gurobi

A commercial mixed-integer linear programming solver, available fromhttp://www.gurobi.com/. PICO

An open-source mixed-integer linear programming solver, available as the Acro-pico project from

https://software.sandia.gov/trac/acro/.

Please refer to the individual projects’ documentation for licensing, pricing and installation information.

2.3 Installing the Water Security Toolkit Binary Distributions

Precompiled binary distributions (for Windows and Linux platforms) are distributed as a single ZIP archive. Installing WST requires unzipping the archive to any location on the hard drive. The archive will create several folders within the main WST folder:

bin The compiled WST programs and driver utilities dist Third-party dependencies

doc WST documentation (including this guide)

etc Model files

examples Files associated with the WST subcommand examples

The main WST executable is located in the wst/bin directory. WST can be executed by typing the full path to the executable (e.g., C:\WST-1.2\bin\wst.exe on Windows or wst-1.2/bin/wst on Linux) or by adding the wst-1.2/bin directory to the system PATH variable and callingwstfrom the command line prompt. The first time thewstcommand is used a message about configuring Python packages for first use is displayed. This process is normal and could take several minutes depending on the system.

2.4 Compiling the Water Security Toolkit Source Code

Compiling WST from the source code is an advanced topic and targeted only at potential developers. It assumes familiarity with compilers and build terminology. General users are strongly recommended to use the pre-built binary packages whenever possible.

Compiling WST from the source code uses the Python VirtualEnv package to set up a virtual Python environment within the WST source code distribution. The Python components of WST are installed into this virtual environment to better insulate WST from the rest of the particular environment (and vice-versa). The compiled (C++) binary executable files are installed into a bin directory within the source code distribution. Currently, WST does not support out-of-source builds.

While WST can be compiled from the source code for Windows and Linux operating systems, Windows users are recommended to leverage the pre-built binary distributions. WST can be compiled for Linux using a 3-step process:

1. Obtain the WST source code

2. Configure the Python virtual environment 3. Build the C++ executable files

(24)

2.4.1 Obtaining the Water Security Toolkit Source Code

The WST source code can either be extracted from a downloaded source zip/tar archive or checked out directly from the repository using Subversion. The following directions assume that the source code is in the wst-1.2 directory.

2.4.2 Configuring the Python Virtual Environment

The Python virtual environment is automatically configured by the setup command distributed in the top-level directory of the source code distribution:

cd ~/wst-1.2 ./setup

This configures WST using the system’s default Python interpreter and the bundled versions of the Python dependencies. A different version of Python can be used with WST by specifying it explicitly when running thesetupcommand:

cd ~/wst-1.2 python2.7 ./setup

WST can also be configured with the bleeding edge (trunk) versions of the key Python dependencies by specifying the–trunkoption:

cd ~/wst-1.2 ./setup --trunk

Setup configures the Python virtual environment within the wst/python directory (e.g.,/wst-1.2/python). The virtual interpreter and the main wst command both reside in wst/python/bin directory (e.g.,/wst-1.2/python/bin/wst). If only a single virtual environment is going to be on the machine, adding the wst/python/bin directory to the system PATH variable is recommended. Alternatively, the lbin and

lpython commands (installed into wst/python/bin) can be used to correctly locate local binaries and the local virtual python interpreter. To run the wstcommand from anywhere under the main WST directory, use the lbin wst command. Similarly, to run the local python (virtual environment) interpreter, use the

lpythoncommand. It is safe to copy bothlbin andlpythonto other directories (e.g.,/bin). 2.4.3 Building the C++ Executable Files

WST relies on the GNU Autotools to manage the build process for compiled executables. In particular, Autoconf version 2.60 or newer must be installed on the system along with a relatively new C++ compiler and linker (e.g., gcc >= 3.4). The build process follows the normal autoreconf – configure – make

sequence: cd ~/wst-1.2 ./setup autoreconf -v -i -f ./configure make

It is not recommended to use themake installcommand. The resulting compiled binaries reside in wst/bin, and are easily accessed from anywhere under the main WST directory using thelbin command.

This process could be simplified by using the mainsetupcommand: cd ~/wst-1.2

(25)

2.5 Basic Usage of the Water Security Toolkit

The main command line structure to execute a WST subcommand is the following: wst SUBCOMMAND <configfile>

where SUBCOMMAND is the one of subcommands available under the wst command and configfile is the configuration file associated with the specified subcommand. The subcommands include the following:

• tevasim • sim2Impact • sp • flushing • booster_msx • booster_mip • inversion • grabsample • visualization

Each subcommand is described in more detail in Chapters 3 through 10.

In addition, the–-helpoption prints information about the different subcommand options available. wst --help

Each subcommand has the option to generate a template configuration file by using the following command line:

wst SUBCOMMAND --template <configfile>

whereconfigfile is the name of the template configuration file created for the specifiedSUBCOMMAND.

2.6 Verifying Installation of the Water Security Toolkit

An example using one of the WST subcommands can be used to verify the proper installation of WST. This example uses the WST subcommandtevasim, which is documented in Chapter 3.

1. A template configuration file for thetevasimsubcommand can be generated using the following com-mand line, in which verify-wst.yml is the template configuration file to be created:

wst tevasim --template verify-wst.yml

This example assumes that the wst/bin directory was added to the PATH variable. If the path was not modified, the wstcommand would be replaced with the full path to the main WST script (e.g., C:\WST-1.2\bin\wst) in this and all subsequent commands.

2. The EPANET input file for the example network (Net3.inp) needs to be copied from the wst/ex-amples/Net3 directory to the current working directory, since it is the network file referenced in the generated template file. On Windows (assuming WST is installed to C:\WST-1.2), the command line to copy this file is the following:

(26)

On Linux (assuming WST is installed to ~/wst-1.2), the command line to copy this file is the following: cp ~/wst-1.2/examples/Net3/Net3.inp

3. Thetevasimsubcommand using this example is executed with the following command line: wst tevasim verify-wst.yml

This runs the tevasimsubcommand and produces the output shown in Figure 2.1 WST tevasim subcommand

---Validating configuration file

Running contaminant transport simulations WST normal termination

---Directory: C:/WST-1.2/examples/ Results file: Net3tevasim_output.yml Log file: Net3tevasim_output.log

Figure 2.1: Thetevasimtemplate screen output.

2.7 Uninstalling the Water Security Toolkit

As WST does not rely on a formal installer, uninstalling WST only requires deleting the main WST directory (regardless if the pre-built binaries were installed or WST was built from the source code). If the wst/bin and/or wst/python/bin directories were added to the system PATH variable, these entries should be removed also.

(27)

Chapter 3 Contaminant Transport

This chapter describes how to simulate contamination incidents in a water distribution network, which is one of the first steps before designing a water quality sensor network or evaluating response actions to a contamination incident. The tevasim subcommand simulates the hydraulics and contaminant transport within a water distribution network model, which consists of pipe, node, pump, valve, storage tank and reservoir components. Thetevasimsubcommand uses the hydraulic engine from EPANET to solve the flow continuity and headloss equations (Rossman, 2000). Water quality simulations are calculated using either EPANET (Rossman, 2000), EPANET-MSX (Shang et al., 2011) or Merlion (Mann et al., 2012a). To increase efficiency when simulating a large ensemble of contamination incidents, the tevasim subcommand uses a single hydraulic simulation to simulate an ensemble of water quality simulations. A flowchart representation of thetevasim subcommand is shown in Figure 3.1. The utility network model is defined by an EPANET compatible network models (INP format) in WST. The simulation input is supplied through the tevasim

WST configuration file. Contaminant Transport Utility Network Model Simulation Input Threat Ensemble Database

Figure 3.1: Contaminant transport simulation flowchart.

3.1 Hydraulic and Water Quality Analysis

Three water quality simulators, EPANET, EPANET-MSX and Merlion, are used within WST. These simu-lators are explained in more detail in the following subsections.

3.1.1 EPANET and EPANET-MSX

EPANET performs extended-period simulation of the hydraulic and water quality behavior within pressurized pipe networks. These models can evaluate the expected flow in water distribution systems, and model the transport of contaminants and related chemical interactions. The multi-species extension, EPANET-MSX, is also included in WST to simulate contamination incidents using multi-species reactions. Any

(28)

reaction dynamics between chemical and/or biological species (e.g., chemical-chemical, chemical-biological or biological-biological) can be modeled and simulated using EPANET-MSX. EPANET-MSX can be used in sensor network design and booster station placement. More specifics on these applications can be found in Chapters 5 and 7. Additional information on EPANET can be found at http://www.epa.gov/nrmrl/ wswrd/dw/epanet.html and in the EPANET user manual (Rossman, 2000). Additional information on EPANET-MSX can be found in the EPANET-MSX user manual (Shang et al., 2011).

3.1.2 Merlion

The tevasim subcommand also includes a water quality modeling framework called Merlion. Unlike EPANET, Merlion does not model bulk or wall reactions. Given hydraulic information from simulation packages like EPANET or experimental data, Merlion models the transport of a substance as it spreads through the water distribution system based on the network dynamic flow patterns. Merlion first formulates a linear water quality model with explicit all-to-all mapping (inputs include injections at all possible nodes and time steps, and outputs include concentrations at all possible nodes and time steps). This model is then used for forward tracing simulations by first specifying the injection profile and then solving the system for the network concentration profile. The linear model also can be embedded within other numerical applica-tions or for analysis in many security applicaapplica-tions. Using Merlion in thetevasimsubcommand can be faster for multi-scenario simulation; however, it is also more memory intensive. Merlion is also used to identify booster station locations, contaminant source injection locations and manual grab sample locations. More specifics about these applications are in Chapters 7, 8 and 9. More information on Merlion can be found in Section 11.1 and (Mann et al., 2012a).

3.2 Contaminant Transport Scenarios

Contaminant transport scenarios can be defined directly in a WST configuration file or by using a TSI or TSG file. These options are set in the scenario block of the configuration file for all of the WST subcommands that require scenarios.

The recommended approach is to define the contamination transport scenarios directly in the scenario block of the WST configuration file. The options that must be set are the location, type, strength, species (required only for EPANET-MSX) and start and end times for the contamination scenarios. The injection location can be specified by a list of EPANET node IDs, or by the key words NZD (non-zero demand nodes) or ALL (all nodes) to create an ensemble of contaminant scenarios. The injection type can be CONCEN, MASS, FLOWPACED or SETPOINT as defined in the EPANET user manual(Rossman, 2000). CONCEN represents the concentration of an external source entering a node and applies only when the node has a net negative demand. MASS, FLOWPACED and SETPOINT represent booster sources, where a contaminant is injected directly into the network regardless of nodal demand. A MASS source type adds a fixed mass flow to that resulting from inflow to the node, while a FLOWPACED booster adds a fixed concentration to the resultant inflow concentration at the node. A SETPOINT booster fixes the concentration leaving the node as long as the inflow concentration was below the setpoint. The strength of a MASS source is in units of mass flow per minute, while CONCEN, FLOWPACED and SETPOINT sources are in units of concentration (mass per volume). The configuration file defines injection time in minutes and strength in mg/L or mg/min depending on the injection type.

Alternatively, the contamination transport scenarios can be defined using a TSI or TSG file. Each line of a TSI file specifies a single contaminant scenario by listing the injection location, type, species (required only for EPANET-MSX), strength and time frame. Each scenario can include multiple injection locations and multiple injection species with unique injection strengths and time frames. This format allows for the greatest flexibility in combined scenario options. For more detail on the TSI file, see File Formats Section 12.13.

The TSG file is a short hand format of the more detailed TSI file. Multiple injection locations can be specified on a single line. All permutations of the combined locations are used to create multiple scenarios.

(29)

Each line of the TSG file is limited to a single injection species and time frame. For more detail on the TSG file, see File Formats Section 12.12. The TSI and TSG files specify the injection time frame in seconds and the strength units depend on the INP network model file units.

If a TSI file is specified in the WST configuration file, the TSG file and location, type, strength, species, start time and end time options are overridden. If a TSG file is specified in the WST configuration file, the location, type, strength, species, start time and end time options specified in the configuration file are overridden.

3.3 tevasim

Subcommand

Thetevasimsubcommand is executed using the following command line: wst tevasim <configfile>

whereconfigfile is a WST configuration file in the YAML format.

The –-help option prints information about this subcommand, such as usage, arguments and a brief de-scription:

wst tevasim --help

3.3.1 Configuration File

Thetevasimsubcommand generates a template configuration file using the following command line: wst tevasim --template <configfile>

Thetevasim WST template configuration file is shown in Figure 3.2. Brief descriptions of the options are included in the template after the # sign.

# tevasim configuration template network:

epanet file: Net3.inp # EPANET network file name scenario:

location: [NZD] # Injection location: ALL, NZD or EPANET ID

type: MASS # Injection type: MASS, CONCEN, FLOWPACED, or SETPOINT strength: 100.0 # Injection strength [mg/min or mg/L depending on type] species: null # Injection species, required for EPANET-MSX

start time: 0 # Injection start time [min] end time: 1440 # Injection end time [min]

tsg file: null # TSG file name, overrides injection parameters above tsi file: null # TSI file name, overrides TSG file

msx file: null # Multi-species extension file name msx species: null # MSX species to save

merlion: false # Use Merlion as WQ simulator, true or false configure:

output prefix: Net3 # Output file prefix

debug: 0 # Debugging level, default = 0

Figure 3.2: Thetevasimconfiguration template file. 3.3.2 Configuration Options

Full descriptions of the WST configuration options used by thetevasimsubcommand are listed below. network

epanet file

(30)

Required input. scenario

location

A list that describes the injection locations for the contamination scenarios. The options are: (1) ALL, which denotes all nodes (excluding tanks and reservoirs) as contamination injection locations; (2) NZD, which denotes all nodes with non-zero demands as contamination injection locations; or (3) an EPANET node ID, which identifies the node where contamination is intro-duced. This allows easy specification of single or multiple contamination scenarios.

Required input unless a TSG or TSI file is specified. type

The injection type for the contamination scenarios. The options are MASS, CONCEN, FLOW-PACED or SETPOINT. See the EPANET manual for additional information about source types (Rossman, 2000).

Required input unless a TSG or TSI file is specified. strength

The amount of contaminant injected into the network for the contamination scenarios. If the type option is MASS, then the units for the strength are in mg/min. If the type option is CONCEN, FLOWPACED or SETPOINT, then units are in mg/L.

Required input unless a TSG or TSI file is specified. species

The name of the contaminant species injected into the network. This is the name of a single species. It is required when using EPANET-MSX, since multiple species might be simulated, but only one is injected into the network. For cases where multiple contaminants are injected, a TSI file is needed.

Required input for EPANET-MSX unless a TSG or TSI file is specified. start time

The injection start time that defines when the contaminant injection begins. The time is given in minutes and is measured from the start of the simulation. For example, a value of 60 represents an injection that starts at hour 1 of the simulation.

Required input unless a TSG or TSI file is specified. end time

The injection end time that defines when the contaminant injection stops. The time is given in minutes and is measured from the start of the simulation. For example, a value of 120 represents an injection that ends at hour 2 of the simulation.

Required input unless a TSG or TSI file is specified. tsg file

The name of the TSG scenario file that defines the ensemble of contamination scenarios to be simulated. Specifying a TSG file will override the location, type, strength, species, start and end times options specified in the WST configuration file. The TSG file format is documented in File Formats Section 12.12.

Optional input. tsi file

The name of the TSI scenario file that defines the ensemble of contamination scenarios to be simulated. Specifying a TSI file will override the TSG file, as well as the location, type, strength, species, start and end time options specified in the WST configuration file. The TSI file format is documented in File Formats Section 12.13.

(31)

msx file

The name of the EPANET-MSX multi-species file that defines the multi-species reactions to be simulated using EPANET-MSX.

Required input for EPANET-MSX. msx species

The name of the MSX species whose concentration profile will be saved by the EPANET-MSX simulation and used for later calculations.

Required input for EPANET-MSX. merlion

A flag (true or false) to indicate if the Merlion water quality simulator should be used. If an MSX file is provided, EPANET-MSX will be used.

Required input, default = false. configure

output prefix

The prefix used for all output files. Required input.

debug

The debugging level (0 or 1) that indicates the amount of debugging information printed to the screen, log file, and output yml file.

Optional input, default = 0 (lowest level).

3.3.3 Subcommand Output

The tevasim subcommand creates two output files, one is in the YAML file format and the other is a log file. The YAML file is called <output prefix>tevasim_output.yml and the log file is <output pre-fix>tevasim_output.log. The YAML file contains the name of the EPANET report file, the name of the binary ERD database file, the run date and the CPU time. The EPANET report file and binary ERD database files are described below. The log file contains basic debugging information.

• EPANET report: This file provides information on the EPANET simulations. The EPANET report file format is described in Appendix C.3 of the EPANET Users Manual (Rossman, 2000).

• ERD database: The database contains the simulation results, and is stored in four files: header file, index file, hydraulics file and a water quality file. The ERD database format is described in Geib et al. (2011). This files is not intended to be read by users but rather is read by other WST subcommands.

3.4 Contaminant Transport Examples

An EPANET network model (INP format) and a configuration file are required to run thetevasim subcom-mand.

Thetevasimtemplate configuration file uses the EPANET Example Network 3 (Net3.inp). The network is shown in Figure 3.3. Net3 contains 92 junctions, 2 reservoirs and 3 tanks. This network has 59 non-zero demand (NZD) nodes. The network file is setup to run a 48-hour hydraulic and water quality simulation. A 1-hour hydraulic time step and 5-minute water quality time step are used.

The scenario ensemble in thetevasimtemplate configuration file defines a contaminant injection from each NZD node, with a MASS injection of 100 mg/L, starting at time 0 and injecting for 24 hours (1440 minutes). To define scenarios that start and stop at multiple times, a TSG file can be used to define the scenario set. Figure 3.4 shows the example TSG file, Net3.tsg, in which the contamination scenarios are injected at all

(32)

Figure 3.3: Layout of the EPANET Example Network 3.

NZD nodes starting at 12 am, 6 am, 12 pm and 6 pm for a total of 236 scenarios. Each injection lasts 24 hours and injects a contaminant at 100 mg/L.

; 24-hour events, 12am,6am,12pm, and 6pm

NZD MASS 100 0 86400

NZD MASS 100 21600 108000

NZD MASS 100 43200 129600

NZD MASS 100 64800 151200

Figure 3.4: Example TSG contamination scenario file.

3.4.1 Example 1

The first example uses the Net3.inp network file, the contamination scenario set defined by Net3.tsg and the Merlion water quality model. The configuration file, tevasim_ex1.yml, for this example is shown in Figure 3.5.

The example can be executed using the following command line: wst tevasim tevasim_ex1.yml

(33)

network:

epanet file: Net3/Net3.inp scenario:

location: null type: null strength: null species: null start time: null end time: null

tsg file: Net3/Net3.tsg tsi file: null

msx file: null msx species: null merlion: true configure:

output prefix: tevasim_ex1/Net3 debug: 0

Figure 3.5: Thetevasimconfiguration file for example 1.

3.4.2 Example 2

The second example uses EPANET-MSX to simulate the transport of multiple contaminants. For a multi-species simulation, a MSX file and the MSX multi-species must be added to thetevasimconfiguration file. The MSX species is the species whose concentration profile will be saved by EPANET-MSX to be used for future calculations. The MSX species can be different than the species which is injected into the network. The configuration file, tevasim_ex2.yml, for this example is shown in Figure 3.6. The example uses the Net3.inp network file and the MSX file, Net3_EColi_TSB.msx, which simulates the reaction dynamics between Escherichiacoli, chlorine and a tryptic soy broth (TSB), a nutrient broth that helps to grow bacteria. For more information about this specific reaction dynamics, see the E. coli-TSB model described in Murray et al. (2011). In this example, both the species and MSX species are the same.

network:

epanet file: Net3/Net3.inp scenario: location: [’15’] type: MASS strength: 5.77e8 species: EColi start time: 0 end time: 360 tsg file: null tsi file: null

msx file: Net3/Net3_EColi_TSB.msx msx species: EColi

merlion: false configure:

output prefix: tevasim_ex2/Net3_EColi_TSB debug: 0

Figure 3.6: Thetevasimconfiguration file for example 2. The example can be executed using the following command line:

wst tevasim tevasim_ex2.yml

To simulate the simultaneous injection of two species, a TSI file is needed. For example, the TSI file, Net3_EColi_TSB.tsi, defines the simultaneous injection of E. coli and TSB at multiple locations within Net 3.

(34)

Chapter 4 Impact Assessment

The potential consequences of individual contamination scenarios can be quantified using the results from the contaminant transport simulations and a variety of impact assessment metrics. Thesim2Impact sub-command performs impact assessment using the output threat ensemble database (ERD) from thetevasim

subcommand. This analysis provides all necessary network statistics for sensor network design (described in Chapter 5) as well as response actions, such as flushing hydrants and boosting disinfectant (described in Chapters 6 and 7, respectively).

A flowchart representation of the sim2Impact subcommand is shown in Figure 4.1. The threat ensemble database (ERD) is the output from the tevasim subcommand and is required input for the sim2Impact

subcommand. The consequences input parameters are supplied through thesim2ImpactWST configuration file. Additional input data that describes the exposure and dose response models of a particular contaminant is required if a human health impact metric is used. These models are defined by parameters listed in a threat assessment input (TAI) file. More details on the TAI file are provided in the File Formats Section 12.11. Impact Assessment Threat Ensemble Database Consequences Input Impact File

Figure 4.1: Impact assessment flowchart.

Several impact metrics are included in thesim2Impactsubcommand to reflect different criteria that decision makers could use in sensor network design or response actions. These metrics include: population dosed (PD), population exposed (PE), population killed (PK), extent of contamination (EC), timed extent of contamination (TEC), mass consumed (MC), volume consumed (VC), time to detection (TD) and number of failed detections (NFD). The equations used to compute the impact metrics are listed in Section 4.1. Impact metrics are calculated at discrete time steps for a given contamination scenario. The discrete time steps are defined by the reporting time step and the duration of the water quality simulation.

Human health impacts (PD, PE and PK) can be estimated by combining the water quality simulations with exposure models. Contaminant-specific data are needed to accurately estimate the health endpoints. For

(35)

many contaminants, reliable data are lacking, and the ensuing uncertainty in the results must be understood. More information on the human health impacts is provided in Section 4.2.

4.1 Impact Metrics

Impact assessment results are calculated and stored in an impact file. This file is not typically read by a WST user, rather it is read by a sensor or response optimization routine. For each contamination scenario, the impact file contains a list of all the locations (nodes) in the network where a sensor might detect contamination from a specific scenario. Nodes that do not detect contamination are not included in the impact file for that specific scenario. For each node that detects contamination, the impact file contains the detection time and consequence at that time, as measured by one of the impact metrics.

The impact file is used as input for sensor placement optimization and during the optimization process of response actions, such as flushing hydrants and boosting disinfectant. When calculating impacts, a detection threshold can be specified such that contaminants are only detected above a specified concentration limit (the default limit is zero). Second, a response time can be specified in thesim2Impact configuration file, which accounts for the time needed to verify the presence of contamination (e.g., by field investigation), inform the public, and/or initiate flushing, booster disinfection, or other response action (the default response time is zero). The contamination impact is computed at the time when the response has been initiated (the detection time plus response time), which is called the effective response time. Finally, a detection confidence can be defined, which specifies the number of sensors that must detect contamination from any given scenario before it is considered to be detected, at which time the impacts are calculated (the default is 1 sensor).

The impact file contains four columns of information:

• Column 1 contains the contamination scenario number,a

• Column 2 contains the node location where contamination was detected,i

• Column 3 contains the effective response time in minutes,T_i0

• Column 4 contains the impact at the effective response time as measured by a specified metric, da,i

The impact file is documented in the File Formats Section 12.4. The impact metric,da,i, is used directly in

the sensor placement formulation (Equation 5.1), the flushing formulation and the booster formulation. The effective response time at nodei, T_i0, is calculated using the following equation:

T_i0= min (t:|Cn,t >detection limit| ≥detection confidence)∆T+ response time (4.1)

where Cn,t is the contaminant concentration at node n at time stept for every node and time step in the

water quality simulation. The concentration is typically expressed in units of milligrams per liter (mg/L). Concentration could also be a count of cells for a biological contaminant, where the units are cells/L or CFU/L (coliny forming units/L). The length of the reporting time step is denoted as ∆T and has units of time. For detection, the concentration must be above the detection limit, and the number of detections must be above the detection confidence. (Note |Cn,t>detection limit| is the number of node, time step pairs

where contaminant was detected above the detection limit, this includes detection at nodei).

In the impact file, the impact at the end of the simulation time is included for each contamination scenario. Essentially, this is the impact if contamination was not detected at any node location, and is often referred to as the dummy sensor location. For this entry,iis set to -1,T_i0 is the time at the end of the water quality simulation, andda,i is the impact at the end of the simulation.

The impact, da,i, can be computed using one of the following metrics: PD, PE, PK, EC, TEC, MC, VC,

TD and NFD. These metrics are defined in the following equations. In the equations, the effective response time step for nodei,t0_i, equalsT_i0/∆T, and subscriptsn,tand pare used to reference a specific node, time step and person, respectively.

Water Security Toolkit User Manual Version 1.2

SANDIA REPORT

SAND2014-16973

Unlimited Release

Printed August 2014

Water Security Toolkit User Manual

Version 1.2

Katherine Klise

, John Siirola

, David Hart

, William Hart

, Cynthia Phillips

, Terranna Haxton

, Regan

Murray

, Robert Janke

, Thomas Taxon

, Carl Laird

, Arpan Seth

, Gabriel Hackebeil

, Shawn McGee

,

Angelica Mann

SAND2014-16973

Unlimited Release

Printed August 2014

Water Security Toolkit User Manual

Version 1.2

Katherine Klise

, John Siirola

, David Hart

, William Hart

, Cynthia Phillips

, Terranna Haxton

, Regan

Murray

, Robert Janke

, Thomas Taxon

, Carl Laird

, Arpan Seth

, Gabriel Hackebeil

, Shawn McGee

,

Angelica Mann

Abstract

The Water Security Toolkit (WST) is a suite of open source software tools that can be used by water

utilities to create response strategies to reduce the impact of contamination in a water distribution

network. WST includes hydraulic and water quality modeling software, optimization methodologies, and

visualization tools to identify: (1) sensor locations to detect contamination, (2) locations in the network in

which the contamination was introduced, (3) hydrants to remove contaminated water from the distribution

system, (4) locations in the network to inject decontamination agents to inactivate, remove, or destroy

contaminants, (5) locations in the network to take grab samples to help identify the source of

contamination and (6) valves to close in order to isolate contaminated areas of the network. This user

manual describes the different components of WST, along with examples and case studies.

License Notice

Revised BSD License

Acknowledgements

Acronyms

Symbols

Contents

References

159

List of Figures

Chapter 1

Introduction

Chapter 2

Getting Started

2.1

Obtaining the Water Security Toolkit

2.2

Dependencies of the Water Security Toolkit

2.3

Installing the Water Security Toolkit Binary Distributions

2.4

Compiling the Water Security Toolkit Source Code

2.5

Basic Usage of the Water Security Toolkit

2.6

Verifying Installation of the Water Security Toolkit

2.7