ClimTools Home Paper Overview User Manual File Formats Functions

ClimTools 2.9.1 User Manual

Dimitrios Gyalistras
Systems Ecology Group, ETH Zurich, Switzerland

Version 0.8, 4. February 2005
 

Table of Contents

Appendices


 

1. Installation

1.1 ClimTools Programs and Libraries

Below follows a description of all steps needed to install the ClimTools 2.9.1 software. Text like_this is used to indicate the Unix sh, ksh or bash shell commands associated with each step. Text like_this is used to denote names of the recommended installation directories. Note, in order to create or have write access to these directories you may have to log in as a system administrator.
  1. Unpack the "tar" file:
    tar -vfx CT.2.9.1.tar
  2. Create the ClimTools programs directory:
    mkdir /usr/local/bin/CT.2.9.1
  3. Move the ClimTools programs to your programs directory:
    mv CT.2.9.1/PROGS/* /usr/local/bin/CT.2.9.1
  4. Create the ClimTools shared objects libraries directory:
    mkdir /usr/local/lib/CT.2.9.1
  5. Move the ClimTools libraries to this directory:
    mv CT.2.9.1/LIBS/* /usr/local/lib/CT.2.9.1

 

1.2 Unix Environment Variables

The following Unix environment variables are needed and must be correctly set in order to be able to run the ClimTools software:
  1. The ClimTools programs directory should be specified in an environment variable named CTDIR. In order to define this variable use the following sh, ksh or bash shell command:
    CTDIR=/usr/local/bin/CT.2.9.1;  export CTDIR
  2. The two standard Unix environment variables PATH and LD_LIBRARY_PATH must be configured as follows: PATH must contain the paths of the ClimTools programs directory and the relevant sub-directories, whereas variable LD_LIBRARY_PATH must contain the path of the ClimTools shared objects libraries directory. To appropriately extend the paths lists held in these variables you may use the following sequence of sh, ksh or bash shell commands:
    PATH=$PATH:$CTDIR:$CTDIR/GRIB:$CTDIR/PGM:$CTDIR/PGT LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/CT.2.9.1
Note, whereas the steps (1) to (5) from Section 1.1 must be executed only once, the above steps (i) and (ii) must be repeated each time you start a new shell within the Unix environment. This task can be automated by introducing the above shell commands in your shell configuration files. For the sh, ksh and bash shells you will typically have to insert the commands in file /etc/profile (= the basic shell configuration file that is valid for all users), or in file /home/username/.profile (= the custom shell configuration file for the particular user username).
 

1.3 Other Software Packages

The ClimTools package was designed to work together with the PINGO (Procedural INterface for Grib formatted Objects) package. PINGO provides a large collection of data retrieval, data manipulation and statistical analysis functions that can be flexibly called via the Unix command line interface. The PINGO software can be downloaded from the following web site:
http://www.mad.zmaw.de/Pingo/pingohome.html
The ClimTools gridded data plotting programs depend on the GrADS (Gridded Analysis and Display System) software. The latest release is available from:
http://grads.iges.org/grads/grads.html
By default the ClimTools gridded data plotting programs produce ps (postscript) formatted output files. If ou prefer an other format you can use the ImageMagick software to convert ps files to a large variety of other graphics formats (such as PNG or JPEG), and to flexibly manipulate your image files:
http://www.imagemagick.org/
Finally, ClimTools programs that operate on GRIB (GRIdded Binary) formatted files depend on the program wgrib. The present ClimTools release includes the executable wgrib program version 1.7.3.1 (see directory $CTDIR/_GRIB). The ClimTools package was found to work well with this version, but if problems occur with the reading of a particular GRIB-formatted file you might want to try using a newer wgrib version that can be downloaded from:
http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html

 

2. Working with ClimTools

2.1 Calling ClimTools Programs

(in prep.)
 

2.2 Getting Help

(in prep.)
 

2.3 Search Strategy for Input Files

All ClimTools programs proceed according to the same strategy for the searching of input files:
  1. The program attempts to access the file exactly as specified;
  2. If the file could not be found, it is searched in a list of directories as specified in the environment variable M2PATH.
For example, in order to search input files in the two directories named /home/me/myDir1 and mySubDir define M2PATH as follows (sh, ksh or bash shell commands:):
M2PATH=/home/me/myDir1:mySubDir;  export M2PATH
Given this setting and an input file specification testDir/testFile a ClimTools program will proceed as follows: An input file named testFile will be searched, firstly, in sub-directory testDir of the current working directory, secondly as /home/me/myDir1/testDir/testFile, and thirdly it will be searched in the sub-directory mySubDir/testDir.

Note, a "/" at the begin of an input file specification signifies an absolute search path, i.e. the file is searched exactly at the specified location. Otherwise the file will be searched relative to the current working directory.
 

3. Examples

(in prep.)
 

A. Notation

Throughout the ClimTools documentation the syntax of command line inputs and file formats is given based on the BNF-like notation proposed by Wirth (1977):
=           metasymbol used to define a production
. metasymbol denoting the end of a production
a|b choice (a or b)
{a} repetition (n >= 0 occurrences of a)
[a] optionality (zero or exactly one occurrence of a)
(a|b)c grouping (same as ac|bc)
"text" literal text
"" use of quote mark (") as a literal
In addition, the ClimTools documentation uses the following conventions: Nonterminal symbols start with an upper case letter. Terminal symbols and symbols that are equated to one of the special nonterminal symbols (see below) start with a lower case letter. The special nonterminal symbols are written throughout in uppercase.

The special nonterminal symbols are defined as follows:

BOOLEAN      = "TRUE"|"FALSE".
INTEGER = ["+"|"-"] digit {digit}.
REAL = ["+"|"-"] digit {digit} "." digit {digit} [("E"|"e") ["+"|"-"] digit {digit}].
STRING = "'" {character} '"' | "" {character} "".
IDENTIFIER = letter {letter|digit|"_"}.
digit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9".
letter = "a" ... |"z"|"A"| ... |"Z"|.
EOL "End-of-Line" marker.
character any character from the extended (8-bit) ASCII character set except EOL and NUL.

B. Glossary

ASCII "American Standard Code for Information Interchange". The de facto world-wide standard for the code numbers used by computers to represent all the upper and lower-case Latin letters, numbers, punctuation, etc. There are 128 standard ASCII codes each of which can be represented by a 7 digit binary number.
BNF "Backus Naur Form", a formal notation introduced for the first time by John Backus and Peter Naur to describe the syntax of a given language.
EOL "End-of-Line" marker. Varies by operating system:
Unix:LF ("Line Feed", ASCII octal code = 012).
Macintosh:CR ("Carriage Return", ASCII octal code = 015).
Windows/DOS:CR followed by LF.
NUL "Null" character. This character is usually not displayed. In some languages such as 'C', it is used to indicate the end of a group of characters (a so-called "string").
alphabet            A finite set of symbols (abstract entities that stand for something else).
syntax A set of rules for combining symbols. Defines the valid sentences of a language.
formal language A set of strings over a certain alphabet.
formal grammar A system for describing the syntax of a formal language.
production A rule for constructing sentences in a formal grammar.
terminal symbol A grammar symbol that has no rules in the grammar and therefore is grammatically indivisible.
nonterminal symbol A symbol in a grammar that can be expressed in terms of terminal and nonterminal symbols.
metasymbol A symbol outside the language to prevent circularity (same as a metacharacter).

C. References

Wirth, N., 1977. What can we do about the unnecessary diversity of notation for syntactic definitions? Commun. ACM, 20(11): 822-823.

This documentation is maintained by Dimitrios Gyalistras. Last updated 10-Oct-2006.