Model:TopoFlow

From CSDMS


TopoFlow


Metadata

Also known as
Model type Modular
Model part of larger framework
Note on status model
Date note status model
Incorporated models or components:

TopoFlow-Channels-Diffusive Wave, TopoFlow-Channels-Dynamic Wave, TopoFlow-Channels-Kinematic Wave, TopoFlow-Diversions, TopoFlow-Evaporation-Energy Balance, TopoFlow-Evaporation-Priestley Taylor, TopoFlow-Evaporation-Read File, TopoFlow-Infiltration-Green-Ampt, TopoFlow-Infiltration-Richards 1D, TopoFlow-Infiltration-Smith-Parlange, TopoFlow-Meteorology, TopoFlow-Saturated Zone-Darcy Law, TopoFlow-Snowmelt-Degree-Day, TopoFlow-Snowmelt-Energy Balance,

Spatial dimensions 2D
Spatial extent Landscape-Scale, Watershed-Scale
Model domain Hydrology
One-line model description Spatially-distributed, D8-based hydrologic model
Extended model 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.
Keywords:

basins,

Name Scott Peckham
Type of contact Model developer
Institute / Organization CSDMS, INSTAAR, University of Colorado
Postal address 1 1560 30th street
Postal address 2
Town / City Boulder
Postal code 80305
State Colorado
Country United States
Email address Scott.Peckham@colorado.edu
Phone 303-492-6752
Fax


Supported platforms
Unix, Linux, Mac OS, Windows
Other platform
Programming language

Python

Other program language IDL (used for version 1.5)
Code optimized Single Processor
Multiple processors implemented
Nr of distributed processors
Nr of shared processors
Start year development 2001
Does model development still take place? Yes
If above answer is no, provide end year model development
Code development status Active
When did you indicate the 'code development status'? 2020
Model availability As code
Source code availability
(Or provide future intension)
Through web repository
Source web address https://github.com/peckhams/topoflow
Source csdms web address
Program license type Apache public license
Program license type other
Memory requirements Standard
Typical run time Minutes to hours


Describe input parameters Too many to list here. Please see the HTML help system and the wiki pages for all of the process components.
Input format ASCII, Binary
Other input format
Describe output parameters Too many to list here. Please see the HTML help system and the wiki pages for all of the process components.
Output format ASCII, Binary
Other output format
Pre-processing software needed? Yes
Describe pre-processing software Another program must be used to prepare the required input grids. These include a D8 flow grid and a slope grid, extracted from a DEM of the area.
Post-processing software needed? Yes
Describe post-processing software RiverTools, VisIt or IDL can be used for visualization.
Visualization software needed? Yes
If above answer is yes
Other visualization software VisIt or RiverTools


Describe processes represented by the model Modeled processes include:
  • Channelized flow (kinematic, diffusive or dynamic wave, all 1D and D8-based)
  • Overland flow
  • Snowmelt (degree-day or energy balance)
  • Icemelt (from valley glaciers using GC2D)
  • Meteorology (including precipitation, air temperature, shortwave and longwave radiation, etc.)
  • Evaporation (Priestley-Taylor or energy balance)
  • Infiltration (Green-Ampt, Smith-Parlange or Richards' 1D, multi-layer), *Shallow subsurface flow (Darcy, up to 6 layers)
  • Flow diversions (sinks, sources or canals)
Describe key physical parameters and equations Too many to list here. Please see the wiki page and HTML help page for each process component.
Describe length scale and 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.
Describe time scale and 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.

Describe any numerical limitations and issues Overland flow is currently modeled in a nonstandard way. Diffusive wave and dynamic wave routing routines need more testing. The linkage between the unsaturated zone (infiltration component) and saturated zone (subsurface flow component and water table) is not robust.


Describe available calibration data sets TopoFlow is typically not calibrated to fit data, but is run with best guesses of the physical parameters.
Upload calibration data sets if available:
Describe available test data sets Available test datat sets:
  • Treynor watershed, in the Nishnabotna River basin, Iowa, USA. (Two large rainfall events.)
  • Small basin in Kentucky.
  • Inclined plane for testing.
  • Arctic watershed data from Larry Hinzman (UAF).
  • See /data/progs/topoflow/3.0/data on CSDMS cluster.
Upload test data sets if available:
Describe ideal data for testing Several test datasets can be downloaded from the TopoFlow website. See /data/progs/topoflow/3.0/data on the CSDMS cluster.


Do you have current or future plans for collaborating with other researchers? Collaborators include: Larry Hinzman (UAF), Bob Bolton, Anna Liljedahl (UAF), Stefan Pohl, Tom Over and others
Is there a manual available? Yes
Upload manual if available:
Model website if any This site
Model forum / discussion board
Comments About this component:
  • The TopoFlow hydrologic model was originally written in IDL and had a complete point-and-click GUI. For more information on TopoFlow, please goto: https://csdms.colorado.edu/wiki/Model:TopoFlow.
  • When used from within the CSDMS Modeling Tool (CMT), this component has a "config" button which launches a graphical user interface (GUI) for changing input parameters. The GUI is a tabbed dialog with a Help button at the bottom that displays HTML help in a browser window.
  • Each of the hydrologic process components used by TopoFlow can now be used either as components in a larger model (such as TopoFlow) or as stand-alone "submodels".
  • TopoFlow has a 90+ page HTML help system and intuitive GUI that is ideal for teaching.
  • This component also has a configuration (CFG) file, with a name of the form: <case_prefix>_topoflow.cfg. This file can be edited with a text editor.
  • The Numerical Python module (numpy) is used for fast, array-based processing.
  • This model has an OpenMI-style interface, similar to OpenMI 2.0. Part of this interface is inherited from "CSDMS_base.py".
  • This version was converted from IDL to Python with the help of i2py 2.0.


Model info
Nr. of publications: 8
Total citations: 124
h-index: 5
m-quotient: 0.25

Link to this page



Latest News

TopoFlow 3.0 is now available (January 2010) as a set of 20 or so CSDMS/CCA plug-and-play components that can be used with the CSDMS Modeling Tool (CMT). This version has been converted to Python and uses Numerical Python or NumPy for fast numerics. Process components (such as the Green-Ampt component for infiltration) now show up as boxes in the CMT GUI. Each box has a "config" button which launches a tabbed dialog for changing input parameters. At the bottom of the tabbed dialog is a Help button that displays HTML help pages. The tabbed dialogs are not yet complete for all components, but are expected to be finished soon. Each process component now has the option to be run as a stand-alone model and has its own "configuration" file ending with ".cfg". Grid stack output is now saved in netCDF format and can be animated using VisIt within the CMT. This version has also been successfully linked to a valley glacier model (for meltrates) called GC2D.

A beta version of TopoFlow 1.5, written in IDL, is still available (since September 3, 2008). You can download this version, with GUI, HTML help system and documentation by clicking on the links below.

A new modeling paper by Pohl et al. (2009) obtained good results using TopoFlow and is listed in the References section below.

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.

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:

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.

References




Nr. of publications: 8
Total citations: 124
h-index: 5
m-quotient: 0.25



Who Uses TopoFlow?

TopoFlow has so far been used for the following projects:

  • Bachman, S.D. and M.T. Hannon (2009) A TopoFlow modeling study of discharge from the Niger River delta, poster, (which meeting ??).
  • Bolton, W.R. and L.D. Hinzman (2006) Simulation of the influence of discontinuous permafrost on hydrological processes, abstract, Proceedings of a Workshop on Hydrological Modeling of Freshwater Discharge from Alaska's Arctic Coast, J. Wang (Ed.), Final Report, OCS Study MMS 2006-043, 56 pp., Coastal Marine Institute, UAF.
  • 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.D. 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.
  • Bolton, W.R., L.D. Hinzman, S.D. Peckham, D.L. Kane and K. Yoshikawa (2003) Characterizing the influence of permafrost on hydrological processes through a spatially distributed model, American Geophysical Union, Fall Meeting 2003, abstract #H22B-0929, San Francisco, CA.
  • 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. doi:10.1016/j.geomorph.2007.03.017
  • 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.
  • Hinzman, L., W.R. Bolton, P. Prokein, M. Nolan and K. Yoshikawa (2006) Spatially distributed simulations of permafrost hydrology, abstract, Proceedings of a Workshop on Hydrological Modeling of Freshwater Discharge from Alaska's Arctic Coast, J. Wang (Ed.), Final Report, OCS Study MMS 2006-043, 56 pp., Coastal Marine Institute, UAF.
  • 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. (2008) Modeling soil moisture distrubtion in northern Alaska: Today +/- 100-years, abstract, p. 45, Arctic Forum 2007. The Arctic Research Consortium of the U.S. (ARCUS), Fairbanks, AK. 2008, 103 pp. ( Water in the Arctic: International Collaborations and Understanding Environmental Change)
  • Liljedahl, A. and L. Hinzman (2005) Hydrological model simulations and physical impacts of a tundra watershed affected by wildfire, Seward Peninsula, Alaska. Impacs of Global Climate Change, Proceedings of World Water and Environmental Resources Congress, ASCE Conf. Proc., Cold Regions Symposium, doi 10.1061/40792(173)248.
  • 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, C. Onclin and M. Russell (2009) The summer hydrology of a small upland tundra thaw lake: implications to lake drainage, Hydrol. Proc., 23, 2536-2546. (Special Issue: Thematic set of subsurface, surface and atmospheric processes in cold regions hydrology)
  • Pohl, S., P. Marsh, A. Pietroniro, B. Davison, C. Onclin and M. Russell (2006) Hydrologic modeling in the tundra region of NW Canada, abstract, Proceedings of a Workshop on Hydrological Modeling of Freshwater Discharge from Alaska's Arctic Coast, J. Wang (Ed.), Final Report, OCS Study MMS 2006-043, 56 pp., Coastal Marine Institute, UAF.
  • 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. (2006) Hydrological modeling of Imnavait Creek, Alaska's North Slope, abstract, Proceedings of a Workshop on Hydrological Modeling of Freshwater Discharge from Alaska's Arctic Coast, J. Wang (Ed.), Final Report, OCS Study MMS 2006-043, 56 pp., Coastal Marine Institute, UAF.
  • 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)
  • Susens, K. and L.D. Hinzman (2006) Dynamic hydrologic processes on the Seward Peninsula, abstract, Proceedings of a Workshop on Hydrological Modeling of Freshwater Discharge from Alaska's Arctic Coast, J. Wang (Ed.), Final Report, OCS Study MMS 2006-043, 56 pp., Coastal Marine Institute, UAF.
  • 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.

Issues

Help

  • For some basic (and partly outdated) information on setting up a TopoFlow model run, see: TopoFlow.
  • TopoFlow consists of a set of stand-alone process components that provide multiple methods for modeling a given hydrologic process. Each component has its own help page. See:

  Channels-Diffusive Wave, Channels-Dynamic Wave, Channels-Kinematic Wave,
  Diversions,
  Evaporation-Energy Balance, Evaporation-Priestley Taylor, Evaporation-Read File,
  Infiltration-Green-Ampt, Infiltration-Richards 1D, Infiltration-Smith-Parlange,
  Meteorology,
  Snowmelt-Degree-Day, Snowmelt-Energy Balance,
  Saturated Zone-Darcy Layers.

  • TopoFlow can also be linked to the GC2D glacier model. See: GC2D.
  • Additional components can be used to prepare some of the input data required for the TopoFlow components. See: Data-HIS, D8-Global and DEM Smoother. The IDL version of TopoFlow contains additional pre-processing tools that are not yet available as components in the CSDMS Modeling Tool (CMT).

Input Files

Output Files