Just what is the role of TCL in ParFlow?

A common question arises around the role of TCL scrip in ParFlow. These questions often center around how ParFlow is executed and whether the executable is TCL/TK or something else. ParFlow is written in primarily in C, and the executable sits in the /exe/bin directory. How it’s actually run is a bit more complicated. ParFlow uses TCL script (with modified “pftcl” commands) to act as a front-end for the executable. The primary role of TCL is to build the database which ParFlow reads as input. This database is a text file with each database key and that key’s value and has the file extension .pfidb. These keys are all set using the pftcl command pfset and are written to the database (with some minor error checking) when the pfrun command is executed from the TCL script. This is all done by the parflow.tcl script which sits in /exe/bin. At this point, the script does some operations to set up parallel parameters (number of processors, etc) then executes another script called run. This script runs the ParFlow executable, using a different command line syntax depending upon a number of things, what type of architecture and whether ParFlow is being run in parallel or serial.
This can be thought of as follows:


This diagram illustrates how even though the TCL scripting language is used to set up and run ParFlow, it’s really not involved in running ParFlow at a basic level. This is usually transparent to the user, but occasionally the run or even the parflow.tcl files need to be modified to fit the syntax of running on a particular platform. The run file can be pretty easily modified to fit any specific system. In this script there are if-then constructs to identify what platform a user is running on, then machine-specific routines for that platform. For example, on a linux cluster using mpirun, ParFlow is executed using mpirun:

mpirun -nodes $3 -np $2 $PARFLOW_DIR/bin/$PROGRAM $1

Where $PARFLOW_DIR is the environment variable set for the location of ParFlow and $PROGRAM is the executable, parflow. Argument one ($1) is the run name and arguments two and three are the numbers of nodes and processors used in the simulation. Of course on a system that did not use mpirun (or used a variation with different command arguments) this file could be edited to match that system’s specifics. One caution, this file is overwritten upon rebuilding ParFlow, so make sure you save a copy. You will need to copy this new copy of run back over again or you can replace the original version in /src/amps/mpi1 (if you are using mpi- use caution unless you know what you are doing here!).

This article should provide some understanding of how TCL is used in ParFlow and how ParFlow is run. It also provides some tips on how to get ParFlow to run on a particular parallel system.