Garfield is a program for the detailed simulation of two-dimensional drift chambers consisting only of thin wires and infinite equipotential planes. As a general rule, no sacrifice in terms of numerical quality has been permitted in favour of CPU time or program length. Thus, the program has an entirely different range of application than say GEANT. It is a program that can be run both interactively and in batch on a wide variety of computers without significant change in outwards appearance. The program is fully command driven but if you desire to add some pieces, you'll find no major obstacles (the program has been written in Fortran-77 and uses Patchy as pre-processor). The help facility you are in at present is the normal Vax HELP on Vax computers and something closely resembling it on other machines. You can obtain further information by typing one of the items listed under "additional information". A return without input will take you back by one level. Wildcards are permitted: P* will match both PLANE and PERIODICITY, an asterisk at the end is always assumed. A question mark as only input will cause the list of alternatives to be redisplayed. This help file can also be read via WWW at the address: http://consult.cern.ch/writeup/garfield/help Examples of the use of the program can be found at: http://consult.cern.ch/writeup/garfield/examples
Additional Information on:
Garfield input exists at 3 levels: Main -> Cell section -> algebra sub-section graphics sub-section ... Gas section -> algebra sub-section graphics sub-section ... The &MAIN command moves you back to the top level of program input, i.e. the level at which one enters the program. This level is used for instance to issue procedure calls that use cell or gas data. Since cell and gas data are made available only when leaving the respective sections, one can not perform e.g. drift line calculations before having left both the gas and cell sections.
Enters the cell section. This is the first stage in most simulations. By entering this section, you clear the cell information entered in earlier cell sections, if any. Everything you enter, is simply stored. A comprehensive check of the input is only performed when leaving the section. That is also the time the compact format cell dataset is written, if requested, the layout is plotted, the cell description is printed etc. Format: &CELL
Additional Information on:
This is the command you type to set or change the setting of the magnetic field. The cell description is not touched by this, but any existing gas data is cleared when this section is entered since the transport properties of gasses depend on the magnetic field. Initially, the magnetic field is off.
Additional Information on:
Enters the gas section. This section establishes the gas mixture to be used when drifting electrons and ions. The main quantities that are needed for such calculations are the electron and ion transport properties, as well as the cluster size distribution and the cluster spacing. Some of these properties can be computed: the Magboltz program will calculate the electron drift velocity, diffusion, Townsend and attachment coefficient for nearly arbitrary gas mixtures. The Heed program takes care of clustering, also for nearly arbitrary gas mixtures. If you have measured gas properties, or have access to measurements you trust, you can enter this data in the form of tables. One can also replace parts of the Magboltz tables with measurements. For rapid studies which do not require great accuracy, descriptions of a few common gas mixtures are built in to the program. All existing gas information is cleared by entering the gas section or the magnetic field section since the transport properties of gasses depend on the magnetic field. Format: &GAS
Additional Information on:
Assists in finding optimal potential settings. The original settings may at any time be recovered by typing RESTORE (without arguments). The potentials are not restored by the program itself when you leave the section (which is probably what you want anyway !). This section also offers some instructions that modify the cell. Format: &OPTIMISE
Additional Information on:
The field section is used to inspect the electrostatic aspects of your chamber. The main command of the section (PLOT) enables you to plot contours, 3D views, vector fields and histograms of almost any field-related quantity. Format: &FIELD
Additional Information on:
Enters the part of the program devoted to displaying the behaviour of electrons and ions in the chamber. Both the gas and the cell data play a role in the computations. The central instruction is the DRIFT command, but also ARRIVAL and XT-PLOT can be useful for a coarse chamber calibration.
Additional Information on:
Enters the section performing signal calculations. Since SIGNAL calculation and processing is strongly experiment dependent, this section consists only of a series of building blocks with which you can build an hopefully detailed simulation of your signal.
Additional Information on:
Terminates program execution decently. &EXIT and &QUIT are synonymous.
In Garfield input, one makes frequent use of variables: For instance, when you make a contour plot of the electrostatic potential, you type "PLOT CONTOUR V". The "V" in this statement is a local variable of the PLOT command which is equal to the electrostatic potential at a given point. When using such local variables, you normally don't have to take any precaution. There are however also cases when you wish to have some variables under your own control. Such variables exist in Garfield and are called global variables, or "globals" for short. The name has been chosen to reflect the broader scope of globals, as compared to the local variables mentioned above. Local variables have a scope limited to one command, while global variables can be used across sections. Since these variables are essentially under your own control, they are for instance not automatically evaluated. It is the purpose of this help topic to explain their correct use. Please be familiar with the contents when using globals ! Global variables can be used for a variety of things: - you can use them for doing ordinary arithmetic; - they are used to construct DO loops, to have some statements executed conditionally (IF statements) and they also appear in CALL and PARSE; - their value can be substituted in ordinary commands.
Additional Information on:
+------------------------------------------------+ | Do not use curly brackets in GLOBAL statements | +------------------------------------------------+ Assigns a value to a global variable. This statement has 2 arguments, the name of the global variable (one may re-use a variable used before) and the value to be assigned to the global variable. The value to be assigned can be a formula in terms of other global variables (including the variable itself if it already had a value): Format: GLOBAL variable value Examples: Global my_name=`abc DEF` Global argon=80 Global ethane=20 Global member=`a`/string(argon)/`e`/string(ethane) (The first example assigns the character string "abc DEF" to the variable my_name. In the second example, a suitable member name of a compact gas description is constructed from the Argon and ethane contents. Note that no curly brackets are used.)
Creates a new 1-dimensional Matrix, also called vector, or reads new data into an already existing Matrix. Newly created Matrices are 1-dimensional and have a length that is equal to the number of elements entered. For existing 1-dimensional Matrices, a new vector is created that replaces the old one. For higher dimensional Matrices, however, the number of dimensions and the size are kept as they were, and new elements replace old elements in the order in which the Matrix is internally stored (opposite to the Fortran convention). The VECTOR statement can read data into one or more Matrices at the time. If more than one Matrix is present, then the statement should be followed by a series of lines which contain precisely one new element of each of the Matrices. If only one Matrix is present, then one may type an arbitrary number of elements on an arbitrary number of lines following the statement. In either case, there should be a blank line to signal that all elements have been entered. Format: VECTOR x y z ... VECTOR x x1 y1 z1 ... x1 x2 x3 ... x2 y2 z2 ... ... ... ... xn yn zn ... ... xn (blank line) (blank line) Example: Vector zzz 0 1 2 3 4 5 6 Call reshape_matrix(zzz,2,4,pi) (The VECTOR statement results in a 1-dimensional matrix of length 7, called ZZZ, which contains the numbers 0 to 6. The RESHAPE_MATRIX procedure call re-arranges this vector to a 2x4 matrix. This matrix has one element more than the original vector, which is filled with the value PI.)
+-----------------------------------------------------------+ | Do not use curly brackets in CALL statements | +-----------------------------------------------------------+ CALL gives direct access to a wide variety of routines and data inside Garfield. Since this statement was originally intended as a debugging aid, most procedures do not attempt to perform a complete check of their arguments nor of the appropriateness of the procedure call. It is for instance technically possible to issue a CALL DRIFT_ELECTRON when neither the gas nor the cell are defined. To ensure that the procedures that rely on cell and gas data work, one should call them only after the cell and gas sections have been left (e.g. via &MAIN) - it is not enough to have entered the cell and gas data, cell and gas data become available to the procedures only when the sections have been left. Procedure arguments which are only used as input, must have the type shown in the description. Input arguments can be global variables but also expressions that result in a an object of the required type. Arguments that are only used for output need not be declared on beforehand. Worse, if they are declared then any string, histogram or matrix associated with it, will be lost. Output arguments must be simple global variables - not constants, nor expressions. Many procedures are overloaded in the C++ sense: the same name is used for several procedures that differ by the data types that they handle. Optional arguments are enclosed in square brackets in the descriptions below - these brackets should not be typed ! Format: CALL procedure(arg1, arg2, ... ) Examples: see the various procedures.
Additional Information on:
+-----------------------------------------------------------+ | Do not use curly brackets in DO statements | +-----------------------------------------------------------+ DO loops allow repeated execution of a set of lines. Loops in Garfield do not necessarily have a loop variable. If a loop has one, it will run through the range you indicate until either the WHILE or UNTIL condition fails resp. holds. In addition, there are instructions to leave the loop and to skip the remainder. Do not attempt to read in a file with < while in a DO loop. Format: [FOR var FROM from [STEP step] TO to] [WHILE while] [UNTIL until] DO [statement | LEAVE [var] | ITERATE [var]] ENDDO Example: For i from 1 to 5 do Say "Now I has the value {I}." Enddo Say "Finished !"
Additional Information on:
+-----------------------------------------------------------+ | Do not use curly brackets in IF statements | +-----------------------------------------------------------+ The IF line is used to execute conditionally only one line, for instance a &STOP if the amount of CPU time left to the job is less than a few seconds. An IF line is also used to conditionally execute an entire DO loop. Format 1: IF cond THEN statement Format 2: IF cond THEN ... DO statement | LEAVE [var] | ITERATE [var] ENDDO Examples: If time_left<10 Then & Stop If vax Then Say "Running on a Vax." If x>10 Then For i From 10 To 1 Step -1 Do If 'entier(i/3+0.001)=3' Then Iterate Say "x+i/3 = {x+i/3}" Enddo
+------------------------------------------------------------+ | Do not use curly brackets in IF, ELSEIF, ITERATE and LEAVE | +------------------------------------------------------------+ IF blocks are used to conditionally execute a group of statements and to execute only one of a set of groups of statements depending on a series of conditions. IF blocks may be nested and may also contain entire DO loops in their branches. Format: IF cond THEN [ELSEIF cond THEN] [ELSE] ENDIF Example: If vax Then get 'disk$food:[garfield]lasagne.dat' Elseif cray|apollo|sun Then If Cray Then $ fetch //food/garfield/lasagne.dat ... -t'fn=FOOD,ft=LASAGNE' get "//food/garfield/lasagne.dat" Elseif cms Then get food.lasagne.* Else Say "No GET for this machine; stopping." & Stop Endif In this example, a cell (or gas) compact description is fetched from a file - the name depends on the machine. In the case of the Cray, the file is first read from the IBM.
This instruction enables you to make input files that prompt for parameters. For instance, in a magnetic field section, you could ask for the value of the magnetic field and then issue a COMPONENTS instruction with the B-field the user specifies. You could also ask the user to enter the name of a cell description and then load it from a library of such descriptions. If you're familiar with REXX, you'll note the similarity with the REXX command by the same name. Keep in mind however that the REXX syntax is far richer than what is offered here. Also, in Garfield, all input is automatically evaluated as expressions in terms of global variables. An error results if the syntax is not correct. This could for instance happen if you try to enter character input without surrounding quotes: an attempt would be made to evaluate the string as an expression in terms of the global variables. Format: PARSE {GLOBAL var | INPUT | TERMINAL | VALUE expression} template Example 1: Get the piece before and after the decimal dot of pi**2 Parse Val pi**2 int'.'frac Example 2: Ask for a yes/no answer &FIELD Global yes=true Global no=false Say "Make a 3D plot ? (yes/no)" Until OK Do Parse Terminal plot_3D Call inquire_type(plot_3D,type) If 'type=`Logical`' Then Global OK=true Else Say "Please give an answer that evaluates to TRUE or FALSE." Global OK=false Endif Enddo If plot_3D Then plot surface The global variables YES and NO are set respectively to the values TRUE and FALSE so that the user can simply type. The user may still answer with any expression that evaluates to a Logical (e.g.: 3>4, FALSE etc). Note that the variables YES and NO are defined in the default initialisation file. Example 3: Ask for a cell name Say "Please enter the name of the cell to be read:" Parse Terminal cell (The user responds with (note the quotes !): `DC1`) get cell.lib {cell} Note the use of the reverse quote in the user response: since the global variable CELL should be a string, it should be enclosed in quotes. Single and double quotes would disappear in the process since these quotes are not part of the string that is entered. An equivalent, but more clumsy, user response would have been '"DC1"', with an outer layer of single quotes to keep make the double quotes inside part of the string.
Additional Information on:
The SAY command outputs the string that follows it, performing substitions of global expressions as usual. Format: SAY string Example: Say "Only {time_left} seconds left !"
Comment lines start with an asterisk. Format: * anything you wish
The dataset commands assist you in inspecting Garfield datasets. Garfield datasets are (for Garfield purposes only) organised as libraries (they are sequential datasets to the operating system). Each member in such a dataset has a member name and a type. There may in addition be a remark for easier identification. Garfield datasets can be moved between machines, you may also operate on such datasets on other computers if the OS allows, at CERN for instance you can read libraries on VM from the Vaxes. All dataset commands start with a % sign. If you have lots of dataset commands to do, you may prefer to enter the dataset subsection by typing only the % sign, without arguments. In the dataset subsection no % has to be prefixed to the commands. You may not enter other subsections from within the dataset subsection. EXIT will get you back to the section you came from.
Additional Information on:
Most of the graphics settings can be changed during the run. For instance, one can: - add, open and activate workstations, - control waiting and screen clearing before and after plots, - switch between linear and log scales, - add or change colour definitions, - change the appearance of elements of the plots. Settings that are common for most of your runs can be placed more conventiently in your .garfinit (or GARFINIT.DAT) file. This is for instance the case of the representations, as is illustrated in the default .garfinit distributed with Garfield. All graphics commands start with a ! sign. If you have lots of graphics things to do, you may prefer to enter the graphics subsection by typing only the ! sign, without arguments. In the graphics subsection no ! has to be prefixed to the commands. You may not enter other subsections from within the graphics subsection. EXIT will get you back to the section you came from.
Additional Information on:
When you start Garfield, the program performs some initialisation and then waits for input from the normal input stream. For jobs that are not likely to be repeated, one would type the various commands at the terminal and have them executed immediately. If, on the other hand, it is likely that you will re-run a given set of commands several times, changing perhaps a few parameters, then it is probably more convenient to place the set of commands in a file which is then read by Garfield. You can also create such a file starting from the commands recorded during a session (file called "garflast.dat" or similar, depending on the system) and edit it. Reading a file that contains normal input statements, is achieved with the "<" command. Format: < dsname [<< label] Example: < cell_section (To read the file CELL_SECTION.DAT until the end of the file.)
Additional Information on:
Garfield can at your request record your terminal input. The command to start recording to a file called dsname is: >> dsname To stop recording, type: >> Example: >> a.b Say "Recording on a.b" >> c.d Say "Recording on c.d" >> Say "Not recording anymore"
Additional Information on:
Rerouts most of the output to a dataset. To revert to terminal output, enter the command without dataset. Format to start rerouting: > dsname Format to stop rerouting: > Example: > field.map print ex,ey,e,v > (This example works in the field section. First the output is rerouted to the dataset FIELD.MAP, this file captures the long printout from the PRINT command and then output is sent to the terminal again.) This command is taken care of by the low-level input reading routine. The section doesn't see it and doesn't know either where the output is being sent.
Additional Information on:
When a CERN library routine detects an error, it calls the KERNLIB error processing routines. These routines keep a table that contains the number of times each error message should be printed and how many errors of the kind are allowed before execution is terminated. You should not normally see KERNLIB error messages, the instruction described below is therefore mainly useful for debugging the program. Format: ERROR-HANDLING MESSAGE mess-id [PRINT {ALWAYS | NEVER | nprint}] [ABEND {NEVER | nabend}] mess-id Is the identifier of the message as listed in the 'green book' of CERN program library writeups. Both nprint and nabend are meaningful only in the range 0 to 100. Execution is terminated at the nabend+1 occurence of the error. For further details, see short writeup N001 (KERSET).
There are global and local options. The local ones are mentioned in the respective sections, the global ones are described here. Global and local options may freely be mixed in a single OPTIONS line. Format: OPTIONS [NODEBUG | DEBUG] ... [NOIDENTIFY | IDENTIFY] ... [NOINPUT-LISTING | INPUT-LISTING] ... [RECORDING | NORECORDING] ... [PROGRESS-PRINT | NOPROGRESS-PRINT] ... [ON-ERROR-CONTINUE | ON-ERROR-SKIP | ON-ERROR-TERMINATE] ... [NODUMP-ON-GRAPHICS-ERROR | DUMP-ON-GRAPHICS-ERROR] ... [WARN-BUT-WRITE | WARN-AND-NOWRITE | DELETE-OLD-MEMBER ] Example: OPT ID Note: Actions depending on the setting of the ON-ERROR-... options are only gradually being introduced.
Additional Information on:
Translation of input characters is useful if the program has not been transferred properly to your computer and as a result doesn't recognise some special characters (such as curly brackets, carets). Your terminal may also lack some keys. The initial translation table converts tabulation characters to spaces on Vax, Alpha and Unix computers. You may occasionally also have to bypass the translation mechanism by using or modifying the escape character.
Additional Information on:
Aegis, DCL, Unix and VM/CMS commands can be issued from inside the program without having to exit the program. You may wish to view the shell as a sub-section - like with the sub-sections, you stay in the shell if you omit the command. Format for a single line command: $ [Aegis, DCL, Unix or VM/CMS instruction] Format for an excursion: $ $ $ $ (Aegis commands) (Vax commands) (Unix commands) (CMS commands) return LO exit RETURN
Additional Information on:
Garfield can evaluate certain formulae with symbolic parameters without need for external compilation and linking. Although the use of formulae is fairly intuitive, it may be useful for some applications to have good understanding of the way formulae are dealt with. Formulae can be typed as usual in Fortran, with some exceptions: * Blanks are significant separators, e.g. 'EXP X' is an acceptable formula (the quotes serve to keep the string together). * Identifiers (symbolic names) are up to 10 characters long. * Not all the Fortran instrinsic functions are available and some intrinsic functions have a different name. Known intrinsic functions include: SIN, COS, TAN, ARCSIN, ARCCOS, ARCTAN, SINH, COSH, TANH, ARCSINH, ARCCOSH, ARCTANH, EXP, LOG, SQRT, ABS, ENTIER, TRAILING, STRING, NUMBER, PRODUCT, SUM, REFERENCE, GLOBAL, TYPE, LANDAU. In addition, various random number generators (uniform, Gaussian, exponential, Poisson, Polya and Landau) are available. Further intrinsic functions can be added on request. * The data types are different from those in Fortran. The type of variable is implicitely declared when the variables is created. The type can change during execution, when a value of a different type is assigned to a variable. Currently, the following data types are known: - Undefined: existing unintialised variable or non-existing variables - Number: no distinction is made between (single precision) reals and integers - Logical: TRUE and FALSE, written without dots - String: character strings - Histogram: ordinary and autorange histograms - Matrix: matrices of numbers Certain kinds of mixed arithmetic are permitted, for instance between numbers and histograms and between numbers and matrices. Mixed arithmetic of logicals and numbers is not permitted, but could easily be added if useful. Evaluation is not as quick as true Fortran but thanks to a translation into a very simple internal code before evaluation starts, the losses for repeated evaluations are small to what would otherwise be needed in terms of human time. The internal code is referred to here as "instruction lists". The translation of the formula into an instruction list, is done independent of the data type. It may also be possible that the resulting instruction list can be executed for several data types. Instruction lists can be editted in the algebra editor which is entered by typing a @ instead of a formula. The editor behaves like a subsection. On exit of the editor, the function is used by the calling routine to perform its task.
Additional Information on:
Control keys can be used to interrupt the program.
Additional Information on: