introduction
If this is the first time you use the program, and you happen to
be at CERN, then do not hesitate to contact me. This will get you
started faster, and you will also not loose time if the program is
not suited for your application. Some applications become a lot
easier with small modifications in the program.
Although Garfield can be run in batch mode, it is easier to run
it from a workstation or graphics terminal. You should be able to
issue any combinations of commands without causing core dumps,
abends etc. (please contact me if this nevertheless happens !).
A simple example to start with:
& CELL
plane x -1
plane y -1
rows
S 5 * i i 1000*i
& FIELD
plot surf V, contour V
More elaborate examples can be found via WWW at the URL:
http://consult.cern.ch/writeup/garfield/examples
The program is structured in a set of so-called sections (cell, gas,
magnetic, optimise, field, drift and signal) that each contain a set
of instructions performing certain tasks. The cell section e.g. will
read the cell description, the field section offers facilities for
plotting the field etc. The sections are headed by a line starting
with an ampersand (&), & CELL and & FIELD start sections in the
above example. You may insert one or more blanks between the & and
the section name.
There is one special header: &STOP (or &QUIT or &EXIT if you prefer)
which will stop program execution. An End-Of-File (control-Z) does
the same job, except on VM/CMS where EOF is represented by a blank
return (which is intercepted).
The instructions within the sections are free format lines. Input
files can be both fixed and variable record length. The maximum record
length is large, about 500 characters.
An ellipsis (...) at the end of one physical line indicates that the
instruction continues on the next. There can be only 1 instruction
per input line.
Case is irrelevant, except in file names when running under Unix
and Unix-like systems. All input is converted to upper case before
processing unless enclosed by double quotes (e.g. "abc"). Quotes
also keep strings together that contain separation characters (see
below). Case conversion does occur in strings enclosed by single
quotes (e.g. 'abc' becomes 'ABC').
The commands consist of a series of words, separated by a blanc ( ),
a comma (,), a colon (:) or an equal sign (=). Choose whatever you
prefer. The first word on each line is the command proper. The other
words can be viewed as a set of parameters, with sometimes a value
assigned to them. Here is an example of a cell description:
&CELL
plane x=10, V=1000
plane x -10 V 1000
period y 3
rows
S * * 0 0 5000
cell-id "Test cell"
The words "PLANE", "PERIOD", "ROWS" and "CELL-ID" are the commands.
The command "PLANE" has two arguments with a value for each. You
may if you wish invert their order:
PLANE V=1000 X=10
without affecting the meaning of the command. This is true in
general (except where explicitly stated otherwise).
The ROWS command has a slighly different syntax from the rest: apart
from having arguments of its own (not shown in the example), it is
followed by a series of lines (1 in this example) that contain the
actual data. The end of the list is signaled by a blank line. There
are also a few commands of this type in the gas section (CLUSTER and
TABLE).
Nearly all words in the input may be abbreviated to some extent in
each of the 'segments':
E-MOST-PROBABLE & CELL PLANE
E-MOST-PROB &CELL PLAN
E-M-PROB &C PL
Text strings (such as the "Test cell" in the example above) that
contain any of the word separators or in which the case should be
preserved, should be delimited by double quotes. Single quotes
also keep strings together but all lower case text is converted
to upper case.
After a little practice, you should become aware of the global
commands. They can be used to change the graphics settings, to
issue commands to the shell (Aegis, DCL or VM/CMS), to read,
write and inspect datasets, to obtain help.
Garfield also has a reasonable set of loops, conditional execution
of blocks, variable substitution and the like.
The syntax conventions used here are the same as in the manual:
-------------------------------------------------------------------
Syntax element Description
-------------------------------------------------------------------
{ a | b ... } One, and only one, of the items between the brackets
must be present. If the item is omitted, the command
as a whole will be declared as not valid.
[ a | b ... ] You may select one item from the list between
brackets, but this is optional. A default value
will be used if you omit this item.
CAPITALS Are used for things that should be typed as-is.
lower case Is used for things that should be replaced by some
value (values can be numeric, strings and Booleans).
-------------------------------------------------------------------
Note: curly brackets that are input to the program have a
special meaning: the expression that is enclosed by them
is evaluated using the global variables (see there).
There are also some rules concerning the input to the program:
-------------------------------------------------------------------
Input element Description
-------------------------------------------------------------------
case Is irrelevant on most computers, except for file
names on some (like Cray); by default all input is
converted to upper case right after reading the
command (see also "double quote").
defaults Default arguments are chosen by typing an asterisk.
long commands A line that is to be continued on the next line
should end in ... (elipsis), there is no limit
on the number of continuation lines by itself but
the total length of a line shouldn't exceed some
fixed number (at present 500).
abbreviations Abbreviations are usually permitted, those words
that contain hyphens (-) may be abbreviated in each
each of the hyphen-separated segments independently.
separators Words in the input lines must be separated by one or
more of the following sybols: blanc, comma, colon or
equal sign.
single quotes Separators are meaningless inside quoted strings,
the string inside quotes is considered as one word.
double quotes Like single quotes but the case is respected,
can also act as string delimiters for algebra but
the reverse quote is more suited for that purpose.
reverse quotes Act like double quotes with the exception that the
quotes form part of the string, this is useful when
doing e.g. a PARSE or algebra operations.
-------------------------------------------------------------------
File names frequently contain separators and quotes are therefore
needed. Some operating systems (eg VM/CMS) demand that file names
be in upper case. To be safe on such systems, the single quote is
preferable since it respects separators but not the case. Unix
file names are case sensitive and double quotes should therefore
be used for all file names, even if they do not contain separators.
Case does not matter for Vax/VMS.
Some lines start with a non-alphabetic character. Such lines are
dealt with in a different way as is described below. They are for
instance not part of the input for the section you are in at the
time the command is issued. You may omit the blank between the main
text on the line and the first character if you wish.
-------------------------------------------------------------------
Character Description Example
-------------------------------------------------------------------
& Start of a new section & CELL
! Graphics commands ! REP DR-L POLYL-COL RED
% Dataset commands % DIR TEST.DAT
< Input from a file < CELL.INPUT
> Output to a file > OUTPUT.LIS
>> Recording of terminal input >> record.dat
$ Commands to the environment $ SHOW TIME
* Comment line * Modified DC1 cell
? Enter the help facility ? &OPTIMISE SET
@ Enter the algebra editor @
-------------------------------------------------------------------
Some characters have a special meaning when used inside commands:
-------------------------------------------------------------------
Character Description Example
-------------------------------------------------------------------
* Default value AREA * -2 * 2
* Wildcard GET CELL.DAT PL*
@ Enter the algebra editor PLOT CONT @ HIST E
\ Escape character \{abc\}
... Continuation lines PLANE X ...
2, V=1000
{ ... } Formula evaluation Say "Two x pi={2*pi}"
[ ... ] Matrix indexing Global a=b[2;]
' ... ' Keep string together get 'cell lib d'
" ... " Like '' but preserve case get "/cell/lib/dc1"
` ... ` Algebra string delimiters Parse Input . `phi=` phi
-------------------------------------------------------------------
Three kinds of parentheses are used in Garfield. One of them,
the curly bracket, is very often misused.
- Round brackets "( ... )": Used in formulae, for arguments
of functions and procedures, and also around sub-expressions
that need to be evaluated first.
Examples:
Global a=cos(2*pi/3)
Call print(1+2*(3+4))
- Square brackets "[ ... ]": Used in formulae, when indexing
matrices.
Example:
Global a=number(b[3;3])
- Curly brackets "{ ... }": Form the bridge between normal
statements and global variables. A formula between curly
brackets is evaluated and the result is substituted before
the statement is further processed.
CURLY BRACKETS MUST NOT BE USED IN CONTROL STATEMENTS
Example:
Global argon=80
Global co2=20
Global gas_file=`Ar`/string(argon)/`CO2`/string(co2)
Call inquire_file(gas_file)
If exist Then
get {gas_file}
Else
magboltz argon {argon} co2 {co2}
heed argon {argon} co2 {co2}
add mobility 1.5e-6
write {gas_file}
Endif
Please note that curly brackets are used only in the GET,
WRITE, MAGBOLTZ and HEED statements - these are commands,
not control statements. Curly brackets are not used when
the global variable GAS_FILE is used as argument of the
INQUIRE_FILE procedure. Similarly, EXIST is not enclosed
in curly brackets in the If-condition. When ARGON and CO2
are used without brackets in the Global statement, but with
curly brackets in MAGBOLTZ and Heed.
Three kinds of quotes are used in Garfield. Please use them
correctly !!!
- Double quote ("): Is used in normal input statements, around
strings that need to form a single input word but that contain
special characters such as spaces, equal signs, commas, double
quotes etc. Case is preserved between double quotes.
Examples:
Say "Hello, how are you doing ?"
arrival dataset "arrival.dat"
- Single quote ('): Are like double quotes, but the text between
single quotes is converted to upper case.
Example:
Call threshold_crossing(1,-0.02,`rising,linear`,n,t1,t2)
If 'n=0' Then
Say "Warning: No crossing found."
Iterate
Endif
The condition of If statements must be a single word which must
moreover be in upper case. In this case, an equal sign is used
in the condition. Since equal signs are treated like commas and
blanks, the condition without quotes would be read as 2 words:
"n" and "0". We could also have typed: If "N=0" Then
- Reverse quote (`): Are used only, but extensively, in control
statements: Call, If, Do, Global and Parse. Reverse quotes
delimit character strings in any algebraic statement.
Example:
Global argon=80
Global co2=20
Global gas_file=`Ar`/string(argon)/`CO2`/string(co2)
A file name is contructed from the percentages of Ar and CO2.
Garfield is not a professional program and a warranty is given that
bugs are present. You are urged to check the results do make sense.
Garfield is a fairly large drift chamber simulation program: around
85000 lines plus libraries. Moreover it is a one person enterprise
and the program changes rapidly.
Please contact the author in case of trouble and if you need further
information, have suggestions for extensions etc. In case you suspect
a bug, send the following:
* a complete copy of the input, not just the relevant part
* a complete copy of the output, not just the relevant part
* a description of the system you are running on plus version
indication of the program.
A common source of problems is the use of a manual that is out of
date. As a rule, it is better to consult the help file via WWW for
up to date information concerning the commands:
http://consult.cern.ch/writeup/garfield/cnl for modifications
http://consult.cern.ch/writeup/garfield/examples for examples
http://consult.cern.ch/writeup/garfield/files for the files
http://consult.cern.ch/writeup/garfield/help for help
Heed has been written by Igor Smirnov, PNPI.
Magboltz is the work of Steve Biagi.
Most of Garfield has been written by Rob Veenhof (referred to as
'I' or 'me' in the documentation). My electronic mail address
at CERN is: Rob.Veenhof@cern.ch
If you prefer more traditional means:
Rob Veenhof Rob Veenhof
CERN / PPE-division 2, Rue du Reculet
CH-1211 Geneve 23 F-01630 St Genis-Pouilly
Suisse France
tel: + 41 22 7671156 tel: + 33 4 50421784
A prompt response can not be guaranteed because maintaining this
program is not part of my regular work, but I do my best.
For technical questions and remarks about the control-C mechanism
and other typical Vax features, please contact Carlo Mekenkamp
directly (MEKENKAM@HLERUL5).
G.A. Erskine contributed key ideas but he should not be called
in case of problems. Please contact me in case of questions about
his parts (theta functions, polygone mappings).
The program was originally written (summer 1984) for the optimisation
of the HELIOS drift chambers, which feature amongst others channeling,
a non-linear and non-saturated gas (CO2-ethane) and a geometry that
gives a very high spatial resolution. These chambers are rectangular
and do not have a magnetic field applied to them.
Since then, the program has grown enormously:
- cylindric geometries have been added
- a magnetic field can be taken into account
- interfaces with Magboltz and Heed have been added
- finite element field maps can be read
In 1984 the program had a length of 5000 lines. In 1998 the main
program (excluding Magboltz and Heed) counts 105000 lines (4 Mb).
The physical units used throughout for both input and output are
the following:
-----------------------------------------------------------
Dimension Input unit Internal unit
-----------------------------------------------------------
angle degree rad
B field user has the choice 100 G
charge electron charge 1.6e-19 C
current micro Ampere 1e-18 A
energy eV [Garfield] or MeV [Heed] eV or MeV
length centimeter cm
potential Volt V
pressure user has the choice Torr
temperature user has the choice K
time micro second micro sec
-----------------------------------------------------------
When the input unit is shown as "user has the choice", then
the quantity can, on input, be followed by a unit of the users
choice. If no unit is indicated, then internal units are
assumed.
Garfield is formally part of the CERN program library, which
is currently (1998) no longer being updated. For the moment,
only one version exists. The source files are available over
WWW:
http://wwwinfo.cern.ch/writeup/garfield/files
Executables at CERN can be found on AFS in the PaRC area, and
also in the author's private area:
/afs/cern.ch/project/parc/bin/garfield
/afs/cern.ch/user/r/rjd/Garfield/Files/garfield
Keyword index.
Formatted on 10/11/98.