Model:TopoFlow

TopoFlow

Latest News

A beta version of TopoFlow 1.5 is now available (September 3, 2008) and this website has been updated to reflect the new features. You can download the new version, new HTML help system and new documentation by clicking on the links below. Please note that an improved method for linking unsaturated and saturated subsurface flow is not yet complete in this beta release.

New Movie: Click on the following image to watch a movie that shows the space-time distribution of discharge in a small basin in Kentucky in response to a short, spatially-uniform rainfall event.

<localVideo width="264" height="216" image="Small_KY_Discharge.png" caption="Spatial discharge movie" type="video/msvideo"> Small_Q_w_Sound.avi </localVideo>

What is TopoFlow?

TopoFlow is a powerful, spatially-distributed hydrologic model with a user-friendly point-and-click interface. Its main purpose is to model many different physical processes in a watershed with the goal of accurately predicting how various hydrologic variables will evolve in time in response to climatic forcings. Time evolutions for single pixels (such as hydrographs), collections of user-selected pixels, or entire grids (as animations) are all supported as output options. The currently supported physical processes are:

• Snowmelt (simple Degree-Day or full Energy Balance method)
• Precipitation (Uniform or varying in space and time)
• Evapotranspiration (Priestley-Taylor or full Energy Balance)
• Infiltration (Green-Ampt, Smith-Parlange or 1D Richards' equation with 3 layers)
• Channel/overland flow (Kinematic, Diffusive or Dynamic Wave and Manning's formula or Law of Wall for flow resistance)
• Shallow subsurface flow (Darcian, multiple uniform layers)
• Flow diversions (sources, sinks and canals)

Processes such as sediment and contaminant transport and landform evolution are planned for future releases. For each physical process, the user selects a "method" to be used to model that process from a droplist of options, and then specifies the input data that is required for that method and the output variables that are of interest. TopoFlow is designed so that users can use existing methods, share methods with others, or add their own methods and incorporate them into the graphical user interface. A method called "None" is always available to turn off any given physical process, and cleanly-written templates are provided to simplify the task of adding new methods.

TopoFlow also includes a growing number of pre- and post-processing tools. Some of the pre-processing tools included in the latest version are: (1) a tool for parameterizing channel geometry and roughness with either contributing area or Horton-Strahler order, (2) a "profile-smoothing" tool to remove "jumps" in DEM profiles, (3) a tool for computing a "normal depth" grid, (4) a data interpolation tool for creating time-indexed grid stacks from time series data for 3 or more stations [via inverse distance method], (5) shortwave and longwave radiation calculators and (6) a multifractal, rainfall simulation tool.

TopoFlow is written in a high-level, array-based programming language called IDL (Interactive Data Language). IDL is a product of ITT Visual Information Solutions (formerly Research Systems, Inc.). Advanced features like:

• Dynamic data typing (very useful for TopoFlow)
• Fast, efficient I/O operations to files
• Fast array processing
• Transparent memory management
• Built-in ability to create point-and-click user interfaces
• Support for pointers and data structures and
• Easy-to-learn command syntax

make IDL especially well-suited to the needs of the TopoFlow project. Programs written in IDL are also highly portable across computer platforms, so that TopoFlow runs almost identically on Windows, Mac, and Unix platforms. (TopoFlow was also designed to handle byte order issues transparently, so that data sets can be shared between platforms.)

How Do I Install and Run TopoFlow?

To run TopoFlow, you first need to download the file: TF15b_IDL63.zip (for IDL 6.3) or the file TF15b_IDL60.zip (for IDL 6.0) and unzip it. This bundle contains a file called topoflow.sav and two folders called Images and Help that contain resource files. You will need to manually create the main TopoFlow folder and copy these files to that folder. The main TopoFlow folder should be named: "C:\Program Files\TopoFlow\" for Windows, "/Applications/TopoFlow/" for Mac OS X, and "/usr/local/TopoFlow/" for other Unix platforms.

You will then need to obtain one of the following applications:

• the IDL 6.0 or 6.3 Virtual Machine (free)
• a licensed copy of IDL 6.0 or 6.3 (a product of ITT Visual Info. Solutions) or
• a licensed copy of RiverTools 3.0 (a product of Rivix, LLC).

Each of these applications has the ability to "restore" or run TopoFlow, which is stored in the file topoflow.sav. You can create a shortcut or alias for this file and place it somewhere in the IDL search path or in the RiverTools "menu" folder. You can download an IDL installer from ITT Visual Information Solutions that lets you choose whether to install just the free IDL Virtual Machine (IDL VM) or the full IDL application. Installers are available for most of the popular operating systems including Windows, Linux and Mac OS X. The IDL Virtual Machine is free and allows you to run any IDL "SAV" file that has been compiled with IDL 6.0 or higher. A full, licensed copy of IDL allows access to the IDL command line while TopoFlow is running and provides a very flexible modeling environment. [Note: In order to run IDL or IDL VM under Mac OS X, you will first need to install the optional X11 application from Apple if it has not already been installed.]

In order to create some of the input files that are required by TopoFlow, you will also need an application that can extract geomorphometric grids such as D8 flow grids, slope grids and contributing area grids from digital elevation model (DEM) data. This functionality is available in hydrologic GIS programs such as RiverTools. RiverTools is a user-friendly, point-and-click environment for the GIS analysis of digital terrain, watersheds and river networks that is also written in IDL. It also has a large number of useful tools for DEM preparation, visualization, analysis and grid editing. A summary of key functionality is available on the RiverTools website. (See the Fact Sheet, Key Benefits and Image Gallery.) TopoFlow can optionally be installed as a plug-in to RiverTools (in its User menu) and can then take advantage of some of the additional capabilities that are built into RiverTools.

Where Can I Learn More About TopoFlow?

TopoFlow 1.5 has a new HTML-based help system which includes a tutorial in the Help menu and Help buttons in many of the dialogs. You can download documents with more information that relates to TopoFlow by clicking on the following links:

• What's New in TopoFlow 1.5 beta
• The TopoFlow license agreement
• Zhang et al. (2000) (PDF), a paper that describes the ARHYTHM model.
• A background paper on hydrologic modeling by S. Peckham (PDF), to appear in an Elsevier book called Geomorphometry in 2007.
• A background paper on RiverTools by S. Peckham (PDF), to appear in an Elsevier book called Geomorphometry in 2007.

Additional documentation, PowerPoint presentations and sample data can be downloaded by following the links at the top of the navigation bar on the left-hand side of this page.

Who are the Developers of TopoFlow?

The TopoFlow project grew out of discussions in 2002 between Scott Peckham (University of Colorado, Boulder) and Matt Nolan (University of Alaska, Fairbanks). The initial idea was to merge two spatial hydrologic models into one and add a user-friendly, point-and-click interface. One of these models was a D8-based, rainfall-runoff model written by Peckham which supported both kinematic and dynamic wave routing as well as both Manning's formula and the law of the wall for flow resistance. The second model, called ARHYTHM, was written by Larry Hinzman and colleagues at UAF (see Zhang et al., 2000) for the purpose of modeling Arctic watersheds. It therefore contained advanced methods for modeling thermal processes such as snowmelt, evaporation and shallow-subsurface flow and was validated with field data for several Arctic watersheds.

The first version of TopoFlow was launched at a user workshop in Fairbanks in 2003. Since then, the number of users and the number of people contributing code has continued to grow. TopoFlow has been specially-designed so that new methods for modeling physical processes can be added easily without affecting the existing set of built-in methods. The number of tools and methods available to users therefore grows as the user community of hydrologists using it for their research grows. Contributors to the TopoFlow project so far include:

• Dr. Scott Peckham: Overall design, oversight, most source code, testing, documentation and the website.
• Dr. Larry Hinzman: ARHYTHM model author, funding support and ongoing collaboration.
• Dr. Matt Nolan: Collaboration on user interface and design.
• Dr. Bob Bolton: Variable hydraulic conductivity method for subsurface flow and the Inverse Distance Method routine used by the "RTS File from Station Data" dialog in the Create menu.
• Dr. Thomas Over: Multifractal cascade routines for simulated space-time rainfall.
• Anna Liljedahl: Testing and detailed bug reports.

TopoFlow is distributed as very clean, open-source IDL code, complete with a user-friendly graphical user interface, context-specific help, etc. The goal is for users to use this code as a template for contributing and sharing new hydrological "methods" that they may develop. People interested in contributing to the project should contact S. Peckham. The latest versions of source code can be accessed via Subversion.

Who Uses TopoFlow?

TopoFlow has so far been used for the following projects:

• Bolton, W.R. (2006) Dynamic modeling of the hydrologic processes in areas of discontinuous permafrost, PhD dissertation, 163 pp., Dept. of Civil Engineering, University of Alaska, Fairbanks.

• Bolton, W.R. and J. Boike (2007) Incorporation of a two-direction freeze-thaw algorithm into a spatially-distributed hydrologic model, Geophysical Research Abstracts, Vol. 9, 00695 SRef-ID: 1607-7962/gra/EGU2007-A-00695. (EGU Meeting 2007)

• Bolton, W.R. and J. Bolton (2008) Simulation of mass and energy fluxes at a polygonal tundra site, Lena River Delta, Siberia, Geophysical Research Abstracts, Vol. 10, EGU2008-A-10974, SRef-ID: 1607-7962/gra/EGU2008-A-10974, EGU General Assembly 2008.

• Bolton, W.R., L.D. Hinzman, S. Peckham, D.L. Kane and K. Yoshikawa (2003) Using a spatially distributed model to characterize the influence of permafrost on hydrological processes, SEARCH Open Science Meeting (SEARCH = Study of Environmental Arctic Change), October 27, 2003, Seattle, WA. Student Poster.

• Coe, J.A., D.A. Kinner and J.W. Godt (2008) Initiation conditions for debris flows generated by runoff at Chalk Cliffs, central Colorado, Geomorphology, v. 96, 270-297.

• Harris, J.R. and J. Hurtado (2004) Containment and recharge of surface runoff from the Franklin Mountains of West Texas to help restore water levels in the Hueco Bolson for future use, abstract at 18th Annual Geological Sciences Colloquium, University of Texas, El Paso.

• Janowicz, J.R., L. Hinzman and W.R. Bolton (2005) Comparative analysis of runoff using the TopoFlow model from small subarctic Alaska and Yukon watersheds, Proceedings of the 15th International Northern Research Basins Symposium and Workshop, Luleaa to Kvikkjokk, Sweden, 29 August to 2 September, p. 255.

• Liljedahl, A. (2008) Master's thesis, University of Alaska, Fairbanks.

• Liljedahl, A. and L. Hinzman (2008) TopoFlow soil moisture simulations and validation, American Water Resources Association Alaska Section 2008 Annual Meeting, January 28-31, Juneau, AK

• Marsh, C., S. Pohl and G.E. Liston (2007) Impact of increased shrub density on snow accumulation and melt in the Arctic tundra, IUGG XXIV General Assembly, July 2-13, Perugia, Italy. (student poster)

• Muldoon, M. (2007) Used TopoFlow as part of a graduate-level course in Fall 2007, Physical Hydrogeology, 51-365/565.

• Peckham, S.D. (2004) The TopoFlow hydrologic model: A new community project, 2004 Joint Assembly of the AGU, Montreal, Canada, invited talk: H52B-05.

• Peckham, S.D., L. Hinzman and M. Nolan (2004) The TopoFlow hydrologic model: A new community project, AGU Hydrology Days 2004, March 10-12, 2004, Colorado State University, Fort Collins, CO.

• Peckham, S.D. (2008) Geomorphometry and spatial hydrologic modeling (Chapter 22), In: Hengl, T. and Reuter, H.I. (Eds), Geomorphometry: Concepts, Software and Applications. Developments in Soil Science, vol. 33, Elsevier, 377-393 pp.

• Pohl, S., P. Marsh and B.R. Bonsal (2006) Modeling snowmelt runoff from an Arctic headwater basin at a variety of spatial and temporal scales under present and future climates, Americal Geophysical Union, Fall Meeting 2006, abstract #C41E-05.

• Pohl, S., P. Marsh and B. Davison (2006) Modeling snowmelt runoff in small Arctic basins with several models of different complexity, Annual Scientific Meeting of the Canadian Geophysical Meeting, May 14-17, 2006. Banff Centre, Banff, Alberta. Abstracts Volume, p. 104.

• Pohl, S., P. Marsh, M. Russell and C. Onclin (2007) Hydrology of a small upland tundra lake, CMOS-CGU-AMS Congress 2008, "Air, Ocean, Earth and Ice on the Rock", St. John's, Newfoundland and Labrador, Canada, May 28 to June 1, 2007, H01-1C4.6.

• Schramm, I. (2005) Hydrologic Modeling of an Arctic Watershed, Alaska, PhD Dissertation, University of Potsdam, Germany.

• Schramm, I., J. Boike, W.R. Bolton and L.D. Hinzman (2007) Application of TopoFlow, a spatially distributed hydrological model, to the Imnavait Creek watershed, Alaska, J. Geophys. Res., 112, G04S46, AGU, (DOI 10.1029/2006JG000326)

• Trochim, E.D. and D.L. Kane (2007) Integrating thermokarst features in the Upper Kuparuk and Imnavait Basin using remote sensing and ground-truth data in TopoFlow, Poster H21A-0199, Fall AGU Meeting, San Francisco, CA.

Funding

Partial funding for this work has been provided by a grant from the National Science Foundation (OPP-0229705), which is gratefully acknowledged. Any opinions, findings, conclusions or recommendations expressed on this website are those of the authors and do not necessarily reflect the views of the National Science Foundation.

TopoFlow Questionnaire

Contact Information

Model:	TopoFlow
Contact person:	Scott Peckham
Institute:	CSDMS, INSTAAR, University of Colorado
City:	Boulder, CO
Country:	USA
Email:	Scott.Peckham@colorado.edu
2nd person involved:	--
3rd person involved:	--

Model description

Model type:	Modular model for the terrestrial domain.
Description:	TopoFlow is a powerful, spatially-distributed hydrologic model with a user-friendly point-and-click interface. Its main purpose is to model many different physical processes in a watershed with the goal of accurately predicting how various hydrologic variables will evolve in time in response to climatic forcings.

Technical information

Supported platforms:	UNIX, Linux, Mac OSX, Windows
Programming language:	IDL
Model development started at:	2001 and development still takes place.
To what degree will the model become available:	Source code will be available
Current license type:	Apache public license
Memory requirements:	Standard
Typical run time:	Minutes to hours

Input / Output description

Input parameters:	Too many to list here. Please see the 90+ page HTML help system.
Input format:	ASCII, Binary
Output parameters:	Too many to list here. Please see the 90+ page HTML help system.
Output format:	ASCII, Binary
Post-processing software (if needed):	RiverTools or a similar program is helpful for pre- and post-processing.
Visualization software (if needed):	No

Process description

Processes represented by model:	Snowmelt (degree-day or energy balance), precipitation (measured or simulated), evapotranspiration (Priestley-Taylor or energy balance), infiltration (Green-Ampt, Smith-Parlange or Richards' 1D, multi-layer), channelized flow (kinematic, diffusive or dynamic wave, all 1D), overland flow, shallow subsurface flow (Darcy, up to 6 layers), flow diversions (sinks, sources or canals)
Key physical parameters & equations:	Too many to list here. Please see the 90+ page HTML help system.
Length scale & resolution constraints:	Recommended grid cell size is around 100 meters, but can be parameterized to run with a wide range of grid cell sizes. DEM grid dimensions are typically less than 1000 columns by 1000 rows.
Time scale & resolution constraints:	Each process can have its own timestep. Typical timesteps are: channel flow (seconds), infiltration (seconds to minutes), snowmelt (hours to days), subsurface flow (hours to days), etc. Model can be run for a full year or longer, if necessary.
Numerical limitations and issues :	Overland flow is currently modeled in a nonstandard way. Diffusive wave and dynamic wave routing routines need more testing.

Testing

Available calibration data sets:	TopoFlow is typically not calibrated to fit data, but is run with best guesses of the physical parameters.
Available test data sets:	Treynor watershed, in the Nishnabotna river basin, in Iowa, USA. Two large events. Arctic watershed data from Larry Hinzman (UAF).
Ideal data for testing:	Several test datasets can be downloaded from the TopoFlow website.

User groups

Currently or plans for collaborating with:

Collaborators include: Larry Hinzman (UAF), Bob Bolton, Anna Liljedahl (UAF), Stefan Pohl, Tom Over and others

Documentation

Key papers of the model:	Peckham, S.D. (2008) Geomorphometry and spatial hydrologic modeling (Chapter 22), In: Hengl, T. and Reuter, H.I. (Eds), Geomorphometry: Concepts, Software and Applications. Developments in Soil Science, vol. 33, Elsevier, 377-393 pp.
Is there a manual available:	yes
Model website if any:	http://instaar.colorado.edu/topoflow

Additional comments

Comments:

Efforts are underway to convert TopoFlow to Python using i2py. The Numerical Python module (numpy) will be used for fast, array-based processing and the wxPython module will be used for the graphical user interface. TopoFlow has a 90+ page HTML help system and intuitive GUI that is ideal for teaching.

Source

Command-Line Access

If you plan to make changes, use this command to check out the code as yourself using HTTPS:

<geshi lang=bash>

1. Project members authenticate over HTTPS to allow committing changes.

svn checkout https://csdms.colorado.edu/svn/topoflow </geshi>

When prompted, enter your CSDMS Subversion password.

Non-members may only check out a read-only working copy of the project source.

To obtain a CSDMS Subversion account or to become a member of this project, please email csdms@colorado.edu.

GUI and IDE Access

This project's Subversion repository may be accessed using many different client programs and plug-ins. See your client's documentation for more information.

http://csdms.colorado.edu/viewvc/?root=topoflow

Subversion Help

For help on how to use Subversion, an excellent manual is available online at http://svnbook.red-bean.com/