GRASS Scripting

GRASS can be very resource intensive so it should not be run directly on SciClone's login servers. Instead, GRASS jobs should be submitted to an appropriate compute node on the cluster via the job scheduler. In order to do this, a few setup steps are required. First, you need to load the GRASS 6.4.2 module into your shell environment. This sets the proper environment variables for GRASS, and also loads a number of other software packages upon which GRASS depends. Use a text editor to put the following line at the end of your ~/.cshrc.rhel6-xeon file:

module load grass/6.4.2

After saving the file, log out and log back in to load the changes into your environment. The GRASS software package is now available for use.

Next, create a subdirectory called grassdata in which to store scripts and data:

mkdir $HOME/grassdata

Now you will need to create a script of commands for GRASS to run. For the purposes of this tutorial, we will use the following very simple GRASS script. In your grassdata directory, create a file titled myscript.sh which contains the following:

#!/bin/sh
export GRASS_PNGFILE=spearfish_elevation.png
d.mon start=png1
r.colors map=elevation.10m rules=elevation
d.rast map=elevation.10m -o
d.vect map=landuse

Make the script executable:

chmod u+x myscript.sh

To finish setting up the GRASS environment, you will need to have a mapset available in your grassdata directory. For this example we will use the Spearfish mapset. To download and unpack the mapset, run the following two commands:

wget http://hpc.wm.edu/grass/spearfish_grass60data-0.3.tar.gz
tar xzvf spearfish_grass60data-0.3.tar.gz

Now you have a location and a mapset to use in GRASS. If you were running GRASS interactively using the wxGUI interface, you would manually direct the program to the appropriate files. But since you are running in batch mode through a job scheduler, you will need to write a job script instead. The job script passes the necessary information to GRASS via environment variables and command line arguments, as described in the grass64 man page. We'll call the job script jobscript. It should look something like the following:

The lines that begin with #PBS are embedded options for TORQUE's qsub command; the rest are shell commands. This script creates a job called "Spearfish" and requests execution on any available compute node in SciClone's RHEL6/Xeon environment (i.e. Hurricane/Whirlwind). Because the simple computations in myscript.sh should run very quickly, the time limit for the job is correspondingly short, just 1 minute. More substantial processing would require longer walltimes. The final option merges all text output from the job into a single file to reduce clutter.

Now jobscript is ready to be executed by the job scheduler:

qsub jobscript

Your job will execute when a compute node with the requested attributes becomes available. This will often happen almost immediately, but when the system is very busy, a job might have to wait in the queue until an appropriate node becomes free.

You can use the qstat command to monitor the status of your job:

qstat -u $user

Once jobscript has completed execution, TORQUE will return the textual output in a file called $HOME/grassdata/Spearfish.oNNNNNN, where "Spearfish" is obtained from the job name and "NNNNNN" is a unique job number assigned by the scheduler. Graphical output will be written to the file $HOME/grassdata/spearfish_elevation.png. The text output should look something like this:

The first two lines are normal warning messages for batch jobs and can be safely ignored. The remaining output is from GRASS and the commands in your GRASS script.

The graphical output in spearfish_elevation.png should look like this:

If your output matches the above results, you have successfully set up your environment to run GRASS scripts on SciClone. To learn more about the grass64 API we recommend diving into the grass64 documentation. For additional GRASS scripting examples and resources, the following tutorials and mapsets are provided.