introduction

getting_started

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 save 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 examples of the use of Garfield can be found on WWW.

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. End-Of-File on input will have the same effect.

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.

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.

The elements on the input are separated from each other by a blanc ( ), a comma (,), a colon (:) or an equal sign (=). There is no difference in meaning between these separators. You may if you wish place several between the words.

Case is irrelevant in commands. Strings of which the case matters, such as file names on Unix systems and also in identifiers, should be delimited by double quotes.

Here is an example of a cell description:

&CELL plane x=10, V=1000 plane x -10 ... V 1000 periodicity y 3 rows S * * 0 0 5000

cell-identifier "Test cell"

The words PLANE, PERIODICITY, ROWS and CELL-IDENTIFIER are the commands. The command "PLANE" has two arguments with a value for each. You may if you wish invert their order without affecting the meaning of the command:

    PLANE V=1000 X=10

This is true in general - exceptions are explicitly stated. PLANE, like most commands, can have more arguments. If no value is given, defaults are used for these, if a meaningful default is available.

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 is one more such command in the cell section (SOLIDS) and 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

Garfield does not pretend to be programmable, but Do_loops and conditional execution of statements (If_lines and If_blocks) exist. For clarity, all control statements are shown with initial capital in the documentation. Here is an example:

    Global ok False
    Until ok Do
       Say "Please enter an integer number"
       Parse Terminal n
       If n<0 Then
          Say "The number you entered, {n}, is negative."
          Iterate
       Elseif entier(n)#n Then
          Say "The number you entered, {n}, is not an integer"
          Iterate
       Endif
       Global fac=1
       For i From 1 To n Do
          Global fac=fac*i
       Enddo
       Say "Factorial of {n} is {fac}."
       Global ok True
    Enddo

A large collection of procedures, mainly in the areas of field and drift line calculation, are available - and they are more and more widely used. They are described under Call.

After a little practice, you should become aware of the utility commands. They can be used to change the graphics settings, to issue commands to the shell (Aegis, DCL, Unix or VM/CMS), to take input from and to output data to files etc.

command_descriptions

The syntax conventions used in the command descriptions are:

{ 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. The curly brackets are not part of the command, they are only typed when substitution of expressions of global variables is desired.
[ a | b ... ]: You may select one, and not more than one. item from the list between brackets, but you don't have to. A default value will be used if you omit this item. The square brackets are not part of the command, such brackets are only typed when indexing a Matrix.
[ a ]: The contents of the brackets is an optional part of the command, you may use it but don't have to. The square brackets are not part of the command, they are only used when indexing a Matrix.
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).

input_elements

The following rules concerning the input should be observed:

abbreviations: Abbreviations are usually permitted, those words that contain hyphens (-) may be abbreviated in each each of the hyphen-separated segments independently.
brackets: Garfield uses 3 kinds of brackets which serve entirely different purposes.
case: Matters for file names on Unix and VM/CMS systems. By default all input is converted to upper case when reading the command, but this can be avoided by using quotes.
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).
separators: Words in the input lines must be separated by one or more of the separators.
quotes: Like with brackets, care should be taken to use the various quotes correctly.

special_characters

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
$ shell commands $ SHOW TIME
* comment line * Modified DC1 cell
? Enter the help facility ? &OPTIMISE SET
@ algebra commands @

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`
`$`	shell commands	`$ SHOW TIME`
`*`	comment line	`* Modified DC1 cell`
`?`	Enter the help facility	`? &OPTIMISE SET`
`@`	algebra commands	`@`

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

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

brackets

Three kinds of parentheses are used in Garfield. One of them, the curly bracket, is very often mis-used.

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 a Matrix.
Example:
```
Global a=number(b[3;3])
```
Curly brackets "{ ... }": Form the bridge between normal statements and Global variables. Curly brackets request evaluation of what is between the brackets followed by substitution of the result in the input statement.
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.

quotes

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_lines and If_blocks must be a single word which must moreover be in upper case. In the example, 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 to delimit Strings. They appear only in control statements such as Call, Global, If_line, If_block, Do_loop and Parse.
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.

separators

The following characters act as word separators in Garfield:

comma: ","
blank: " "
equal sign: "="
colon: ":"

Text strings, such as formulae, that should not be broken up but which contain a word separator, should be put between single or double quotes. The string is converted to upper case when single quotes are used, while the case is preserved with double quotes.

trouble

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, 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

authors

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). The best way to contact me is by electronic mail.

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 (cmekenkamp@vx8000.nl).

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).

origin

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 1999 the main program (excluding Magboltz and Heed) counts 114000 lines (4.4 Mb).

units

The physical units used throughout for both input and output are the following:

Dimension Input unit Internal unit
angle degree radian
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
weight grams g
wire charge - 1/V

Dimension	Input unit	Internal unit
angle	degree	radian
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
weight	grams	g
wire charge	-	1/V

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.

To convert the wire charge into the more usual units of C/cm, one should multiply the charge obtained from procedures such as GET_WIRE_DATA with 2 pi epsilon0, approximately 5.56e-13 F/cm. The wire charge shown in the table printed in response to the CELL-PRINT option and the PRINT-CELL command includes this conversion factor.

versions

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://consult.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

Go to the top level, to introduction, to the topic index, to the table of contents, or to the full text.

Formatted on 15/01/01 at 23:07.