CHAPTER 10 Command Line Interface

Overview

http://www.cis.ohio-state.edu/hypertext/faq/usenet/tcl-faq/top.htm

freud

freud>

set a 5

expr 8+9

In the first example, a new variable, a, is created and assigned the value 5. In the second example, the expression "8+9" is evaluated. Note that there are no spaces between the `8', the `+', and the `9'. The command expr expects only one argument; if there are spaces, then the Tcl interpreter assumes that there are additional arguments. We can get around this limitation by quoting (see below).

set a 5
echo $a

The first command sets the variable a to 5; the second command prints out the first argument, which is $a; the value of a is then substituted.

The second type of substitution is command substitution. This can be used to replace an argument with the return value of a command, and is invoked by enclosing the substituted command with square brackets:

set a [expr 10+2]

a is set to the result of expr 10+2. Variable and command substitution can be combined:

set a 5
set a [expr $a+2]

set a 5
set b "The value of a is $a"

Note that variable substitution takes place within double quotes; command substitution also takes place.

If you don't want command or variable substitution to take place, you can use curly braces:

set a 5
set b {The value of a is $a}

Curly braces can be nested:

set a {1 {2 3} 4}

expr {1 < 2}

expr {1 == 2}

set a 5; set b 4
expr {($a > 0) && ($b > 0)}

The if command behaves like if in C: it evaluates an expression, tests the result, and conditionally executes a sequence of commands based on the result. For instance

if {$x < 0} {set x 0}

if {$x < 0) {
			set x 0
}

if {$x < 0) {
			set x 0
	echo $x
}

for {set i 0} {$i < 2} {incr i} {
		echo $i
}

1

The first argument ({set i 0}) is evaluated before the loop begins; the loop continues as long as the second argument (tested at the top of the loop) is true; the third argument is executed after each completion of a loop. Note the importance of enclosing the arguments in curly brackets; if they were enclosed in double quotes, then they would be evaluated at the time the command was parsed, rather than each time the loop returned to the top.

The foreach command allows looping over a list (see the Tcl book for more info on lists). For example:

set a {This is a list}
foreach i $a {echo $i}

is

a

list

The source command allows you to read a set of commands from a file. It takes a single argument that contains the name of a file. For example, the command:

source freud.tcl

proc plus {a b} {expr $a+$b}

plus 3 4

You will see the result 7 displayed. The a parameter is set to the value of 3, the b parameter is set to the value of 4, and then the expression in the third argument to the proc command is executed.

fropen testh.cdf

to open the dataset named testh.cdf. The returned value of 1 is used later when creating a new instantiation.

The following will instantiate a generic map background:

frmap

frmap ~/.freud/map/mymap

frxy ~/.freud/xy/myxy

	frcontour 1 {Z(frtime=3,level=4)}

A defaults file can also be specified for frcontour:

frcontour 1 {Z(frtime=3,level=4)} ~/.freud/contour/mycontour

The frvector command requires two datasets and two variables (one each for the u and v components):

frvector 1 {u(frtime=3,level=4)} 1 {v(frtime=3, level=4)

Plotting and printing

frplot

frprint printer printer

frprint file file

frclear sources

frclear instances

frtile 1 4

The active window is set by the frpage command:

frpage active 2

If you wish to reset the display to one window, type:

frclear viewports

Programming example

cd /usr/local/lib/freud/sample
source easy.tcl

#
# Simple automated plotting example
#

# Get the current library directory
if [info exists env(FREUD_LIB_DIR)] {
    set mydir $env(FREUD_LIB_DIR)
} else {
    set mydir /usr/local/lib/freud
}

# Clear out any old instantiations, sources or viewports
frclear instances sources viewports

# Create two windows
frtile 1 2

# Open the netCDF file testh.cdf and save the returned dataset number
set dsetNumber [fropen $mydir/sample/testh.cdf]

# Create a contour instantiation use the defaults file ngm_contour 
# and the previously opened dataset; slice variable Z (which is 4d)
# at level 3 and frtime 0

for {set i 0} {$i < 2} {incr i} {

# Clear all previous instantiations

    frclear instances
# Create a contour instantation using the defaults file ngm_contour
# and the dataset number returned by the fropen command; the variable
# Z at level 3 and frtime equal to the loop index is loaded into the
# instantiation

    frcontour $dsetNumber "Z(frtime=$i,level=3)" $mydir/sample/ngm_contour

# Create a map instantiation using the defaults file ngm_map

    frmap $mydir/sample/ngm_map
# Set the current active window to the loop index + 1
    frpage active [expr $i+1]
# Set the label
    frlabel "NGM 500mb heights at time $i" 

# Plot it
    frplot
}

Advanced Freud Tcl extensions

frinstance mycontour contour mydefaults

frdelete mycontour

frsource mydata test.cdf

Suppose the file test.cdf contains a variable Z.You can create a handle to this variable by typing:

frvar myvar mydata Z

This variable may not be in the correct form for plotting--for instance, it might be a four dimensional variable, and Freud can only plot functions of two dimensions. The variable needs to be sliced. To slice a variable, you can use a slice expression. Suppose Z is a function of the dimensions frtime, level, lat, and lon (the names of the dimensions can be determined by using the data browser), and that you want to display the 2D slice of Z at the frtime=0 and level=3, where the numbers are the indices of the dimensions, not the actual values. To create a handle to such a sliced variable, you can type:

frvar myv1 mydata "Z_0=Z(frtime=0,level=3)"

Data can be loaded into an instance by using the frload command. For example, the sliced variable Z_0 can be loaded into the contour instance mycontour by typing the line:

frload mycontour myv1

frinfo instances

If you load the source /usr/local/lib/freud/sample/testh.cdf and the variable Z, slice it at frtime=0, level =0, and type:

frinfo loaded Contour-1

Note that this is in the form of a Tcl list of lists, and can be manipulated as such. For instance, the command:

	lindex [frinfo loaded Contour-1] 0

/usr/local/lib/freud/sample/testh.cdf Z(frtime=0,level=0)

and

lindex [lindex [frinfo loaded Contour-1] 0] 0

/usr/local/lib/freud/sample/testh.cdf

You can return information on all of the loaded sources:

	frinfo sources

if you have loaded two sources named testh.cdf and testu.cdf.

You can get a list of all of the variables in a source:

frinfo vars /usr/local/lib/freud/sample/testh.cdf

You can also return information on a given variable in a source:

	frinfo var /usr/local/lib/freud/sample/testh.cdf Z

This command returns the dimensions associated with the variable. Each dimension is a list containing the name of the dimension, the index range of the dimension, and the values associated with the dimension. In this example frtime has a low index of 0, a high index of 7, and contains the values 0, 12, 6, 18, 24, 30, 36, and 48.

frhandle instance Contour-1

_instance0

If you type the command again, you will see the same return value, since one and only one handle is associated with an instance, source, or variable. If you type:

frhandle source /usr/local/lib/freud/sample/testh.cdf

_source1

Similarly:

frhandle source /usr/local/lib/freud/sample/testh.cdf Z(frtime=0,level=3)

if you have already created the slice Z(frtime=0,level=3). You can now use these handles to load data into the contour instantiation:

frload _instance0 _var4

Programming example

cd /usr/local/lib/freud/sample
source sample.tcl
#
# Display a sequence of slices from the netCDF files testu.cdf, 
# testv.cdf, testh.cdf
#

#
# Procedure to create instances
#

proc create_instances {} {
# Create a contour instance using the defaults file
# ngm_contour
	frinstance c contour /usr/local/lib/freud/sample/ngm_contour
# Create a map instance using the defaults file ngm_map
 	frinstance m map /usr/local/lib/freud/sample/ngm_map
# Create a vector instance using the defaults file ngm_vector
 	frinstance vec vector /usr/local/lib/freud/sample/ngm_vector
}


#
# Procedures to load in data files
#

proc load_files {} {
# Load the file testh.cdf into source handle s
 	frsource s /usr/local/lib/freud/sample/testh.cdf
# Load the file testu.cdf into source handle v1
	frsource v1 /usr/local/lib/freud/sample/testu.cdf
# Load the file testv.cdf into source handle v2
 	frsource v2 /usr/local/lib/freud/sample/testv.cdf
# Create variables
 for { set i 0 } {$i < 4} {incr i} {
 	frvar z_$i s "Z_${i} = Z(frtime=${i}, level=3)"
 	frvar u_$i v1 "u_$i = u(frtime=${i}, level=3)"
 	frvar v_$i v2 "v_$i = v(frtime=${i}, level=3)"
 	}
}

#
# Loop through drawings
#

proc do_work {} {
# Create list of titles
 	set thead {NGM model output 500 MB heights, winds at}
 	set ttimes {{0 hr} {12 hr} {6 hr} {18 hr}}
 	set ttail {from model init}
# Loop and create a series of plots
 	for { set i 0 } {$i < 4} {incr i} {
 		frload c z_$i
 		frload vec u_$i v_$i
 		frlabel "$thead [lindex $ttimes $i] $ttail"
 		frplot
 		echo "Snoozing for five seconds ..."
 		exec sleep 5
 	}
}

# Delete all instances and sources (which implicitly deletes 
# variables)

proc delete_all {} {frdelete c m vec s v1 v2}

create_instances
load_files
do_work

	delete_all