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:

&CELL plane x -1 plane y -1 rows S 5 * i i 1000*i

&FIELD plot-field surface V, contour V

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 blank ( ), 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 slightly 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 signalled 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 ... (ellipsis), 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	`@`

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 ...\<BR\>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 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 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, exist)
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, commata, 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
```
In earlier versions of Garfield, the condition of If_lines and If_blocks had to be a single word in upper case. In the example, an equal sign is used in the condition. Since equal signs are separators, like commata and blanks, the condition without quotes would be read as 2 words: "N" and "0".
Reverse quote (`): Are used to delimit Strings. They appear only in control statements such as Call, Global, If_line, If_block, Do and Parse.
Example:
```
Global argon=80
Global co2=20
Global gas_file=`Ar`/string(argon)/`CO2`/string(co2)
```
A file name is constructed from the percentages of Ar and CO\<SUB\>2\</SUB\>.

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

You are urged to always check the results you obtain with Garfield make sense. It is remarkably easy to obtain incorrect results by using inappropriate parameter settings. Furthermore, the presence of accidental errors in the Garfield program is guaranteed.

Garfield is a fairly large drift chamber simulation program, it is a one person enterprise and the program changes rapidly. This has the advantage for the user that the program tries to track changes in the design considerations of gas detectors. The drawback is a lack of (complete) backwards compatibility of input files.

Please contact the author in case of trouble and if you need further information, have suggestions for extensions etc. In case you suspect an error, 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://cern.ch/garfield/cnl       for modifications
http://cern.ch/garfield/examples  for examples
http://cern.ch/garfield/files     for the files
http://cern.ch/garfield/help      for help

authors

Heed has been written by Igor Smirnov, PNPI.

Magboltz is the work of Steve Biagi.

The TRIM interface has been contributed by James Butterworth.

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 / PH department   2, Rue du Reculet
CH-1211 Gen\&egrave;ve 23      F-01630 St Genis-Pouilly
Suisse                 France
tel: + 41 22 7673222   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, polygon 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 (CO\<SUB\>2\</SUB\>-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. By 2001, Garfield had grown to 127000\ lines (4.9\ Mb), while Magboltz and Heed count respectively 21800 and 19800\ lines (780\ kb and 507\ kb).

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.6 10\<SUP\>-19\</SUP\> C
current	\μA	10\<SUP\>-18\</SUP\> A
energy	eV [Garfield] or MeV [Heed]	eV or MeV
length	centimetre	cm
potential	Volt	V
pressure	user has the choice	Torr
temperature	user has the choice	K
time	\μsec	\μsec
weight	grams	g
line charge	-	V
point charge	V.cm	V.cm

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 line charges into the more usual unit of C/cm, one should multiply the charge obtained from procedures such as GET_WIRE_DATA with 2\π\ε\<SUB\>0\</SUB\>, approximately 5.56\ 10\<SUP\>-13\</SUP\>\ C/V.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.

Similarly, to convert point charges to C, one should multiply the charge expressed in V.cm with 4\π\ε\<SUB\>0\</SUB\>.

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://cern.ch/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/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 21/01/18 at 16:55.