Starting Garfield on Unix

Garfield can be run both interactively and in batch. Most of the steps described in this page apply to both.

Preparing the PC

The graphics package used by Garfield relies on the so-called "backing store" to ensure that graphics windows are restored after having been partially hidden by other windows. Unfortunately, the backing store is not by default enabled on a many private PCs and laptops in use at CERN.

Enabling the backing store varies from system to system. In SLC6, run Xorg -configure as root to produce the file /root/xorg.conf. Keep only the relevant Section "Device" block, edit it as described for SLC5 and place it in the /etc/X11/xorg.conf.d directory. For SLC5 laptops, edit /etc/X11/xorg.conf and locate Section "Device". If not yet done, add the following lines to this section:

Option "BackingStore" "on"
Option "SaveUnder" "on"

On older systems, edit /usr/lib/X11/xdm/Xservers and replace :0 local /usr/X11R6/bin/X by :0 local /usr/X11R6/bin/X +bs. Similarly, in /etc/X11/gdm/gdm.conf, replace command=/usr/X11R6/bin/X by command=/usr/X11R6/bin/X +bs.

Restart the X server (or reboot) after these changes.

Preparing your account

At CERN, you would use one of the systems on which Garfield runs, currently the LXPLUS cluster and private Linux machines which have AFS access.

Before using Garfield for the first time, you will want to

get a copy of the initialisation file for
- fast output on a colour screen, using software fonts and thin lines;
- better quality colour slides, using Times Roman PostScript fonts and thicker lines;
- making paper graphs, in black and white, using Times Roman PostScript fonts.
Place one of these files in your top level directory under the name .garfinit;
add the directory which contains the executable, /afs/cern.ch/user/r/rjd/Garfield/Files/ to your PATH environment variable.

create a link to the help file in your top level directory:

ln -s /afs/cern.ch/user/r/rjd/Garfield/Files/garfield.packhelp .garfield.packhelp

ensure that your LD_LIBRARY_PATH environment variable contains directories that contain shift and 32-bit versions of the BLAS and GSL shared libraries: /afs/cern.ch/user/r/rjd/Garfield/Files/Libshift/, /afs/cern.ch/user/r/rjd/Garfield/Files/GSL/gsl-1.12/.libs and /afs/cern.ch/user/r/rjd/Garfield/Files/GSL/gsl-1.12/cblas/.libs.

After having used Garfield for a while, you will probably modify the initialisation file to suit your taste. You only once have to create the link to the help file.

The display

For interactive runs, you need a graphics screen, preferably one with good resolution and colours. PuTTY connections are not adequate for this purpose.

Garfield will send graphics output to the display, you should therefore ensure that your display is willing to receive such output:

xhost +machine

where machine is the name of the machine on which Garfield will be running, i.e. the system to which you will be logging in. You can also leave this field blank, in which case access from all machines anywhere will be permitted.

After logging in, you may have to identify your screen with a command similar to one of the following, respectively for tcsh and zsh:

setenv DISPLAY display
export DISPLAY=display

where display is the address of your screen, usually ending in :0.0 The standard CERN window manager for X terminals will take care of this, but you probably have to take these steps yourself if you use a workstation or an X terminal in its native mode.

If you have run PAW before, you may have a file called higz_windows.dat in your top level directory. This file may contain a display specification and it would be a good idea to verify that the contents is still valid. In case of doubt, you can simply delete the file - a new copy will be created when you run PAW, Garfield or another program that uses HIGZ for its graphics output.

Starting Garfield

Garfield can be started by simply typing the name of the executable. If you have taken the precaution to add the name of the directory that contains the executable to your PATH environment variable, then you can omit the directory and type:

garfield-9

Garfield will prompt for a terminal type, to which you can respond with a simple return if the higz_windows.dat file is either absent or up to date and your DISPLAY environment variable has been set properly. Next, a graphics window should appear and, after displaying some news, Garfield will show the prompt

Main:

to indicate that it is waiting for command input.

If you want to read an input file, then you have the following options:

Start Garfield as above and paste commands by mouse from an editor window into the prompt.
Start Garfield as above and read the file myinput as follows:
```
Main: < myinput
```
Run in the background. This produces only metafile output, no terminal graphics. Note the ampersand (&) at the end of the line. If omitted, the calculation would run interactively, but input would be taken from the file, not from the terminal. This may lead to unexpected results: in interactive runs, the program waits until the return key is hit, each time a plot is complete. In case of an interactive process with input re-direct, the line after the plot command acts as the return key being hit. Any contents of this line would therefore not be executed as command.
```
garfield  < myinput &
```
Run in batch, as explained below.

For information on the format of the Garfield commands, you can either type help or read the same information via www, which is currently the recommended technique.

Command line options

Garfield accepts the following command line options:

garfield -terminal type model
                   GKS_identifier gksid
                   connection_identifier conid
         -noterminal
         -metafile type format
                   name file
                   GKS_identifier gksid
                   offset offset
                   multiple-frame-file | single-frame-file
         -nometafile
         -GKSlog logfile
         -arguments arg
         -debug               | -nodebug
         -identification      | -noidentification
         -input_listing       | -noinput_listing
         -profile             | -noprofile
         -progress_print      | -noprogress_print
         -recording           | -norecording
         -RNDM_initialisation | -noRNDM_initialisation

All command line options can be abbreviated. With the exception of -profile, they can be switched on and off inside Garfield. The have the following meaning:

-terminal: Describes your terminal.
-metafile: Requests metafile output.
-GKSlog: Establishes an alternative name for the GKS error log file. This can be useful if you don't have write access for the working directory in which you start the program.
By default, "GKS_error.log" in the working directory.
-arguments: The string that follows is made available inside the program to a Parse Arguments command.
By default, a blank string.
-debug: Generates debugging from the start of the initialisation process onwards. This option generates a lot of output.
The option is off by default.
-identification: Prints the names of selected routines when they are called, helpful for tracing the program flow.
The option is off by default.
-input_listing: Copies input statements to output.
The option is by default on when running in batch, off during interactive runs.
-profile: Makes Garfield read the .garfinit file before reading any other commands.
The option is by default on.
-progress_print: Makes time consuming commands show how far they have progressed.
The option is by default off when running in batch, on during interactive runs.
-recording: Records terminal input in a file called garflast.dat.
The option is by default off when running in batch, on during interactive runs.
-RNDM_initialisation: Initialises random number generation by drawing a number of random numbers determined by the time of the day and the date.
The option is by default on.

Garfield recognises a few more options which are not normally used when starting the program from the command line. They are useful when invoking the program from e.g. Tk/Tcl:

-interactive: Forces the program to behave as if run interactively.
Usually, the program assumes interactive running if input is coming from a terminal.
-batch: Forces the program to behave as if run in batch.
Usually, the program assumes batch running if input is coming from a file.
-synchronise: Makes the program generate additional output which can be used by a front-end program to synchronise its data with the data available inside the program.
Usually, the program does not generate this type of output.

Running in batch

Submission in batch is simplified by a graphical user interface which has its own built-in help facility. This interface is still being worked on and comments are welcome:

/afs/cern.ch/user/r/rjd/Garfield/Files/garfield.tcl &

In these pages, text set in olive green Courier should be typed as-is. Text set in orange Courier should be replaced by a value of a type which is usually specified.

Last updated on 14/11/11.