Help 

Garfield help pages

These pages contain detailed descriptions of the commands that Heed, Garfield and Magboltz accept. Information about the command format is given in the introduction. Most commands are illustrated with a short example. More elaborate examples have been contributed by various users. These programs can be run, without need for compilation, on most of the central CERN computers.

Garfield input is subdivided in sections:

Garfield input can also contain rudimentary scripting:

Occasionally, you may wish to use the various utilities:


introduction

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

Additional information on:


&MAIN

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 is the normal environment to execute procedure Calls which use cell or gas data, e.g. in order to calculate drift-lines.

&MAIN can also be used as final statement in jobs that run Magboltz to produce electron transport plots. &MAIN is in this context approximately equivalent to &STOP.

The cell and gas sections produce plots, write data sets and make their data available to the procedures when the section is left. Leaving the section can be done in 3\ ways:

A section is not left when an end-of-file condition is raised on input.

Example:

Global emin=100
Global emax=10000
&MAGNETIC
components 0 0 0.4 T

&GAS options gas-plot write "p10.gas" "b4000" magboltz argon 90 methane 10 coll 2 n-e 4 n-angle 2 ... e-range {emin,emax}

&MAIN Global n=100 Global e=emin*(emax/emin)^((row(n)-1)/(n-1)) Call transverse_diffusion(e, 0, 0, 0, 0, 0.4, dt) Call longitudinal_diffusion(e, 0, 0, 0, 0, 0.4, dl) Call plot_graph(e,(dt^2+dl^2),`E [V/cm]`, ... `sqrt(&sigma;<SUB>T</SUB><SUP>2</SUP>+&sigma;<SUB>L</SUB><SUP>2</SUP>)`, ... `Diffusion`) Call plot_end

Without the &MAIN statement, the GAS-PLOT option would have no effect, the WRITE statement would not be executed and the various procedure calls would be rejected.

&CELL

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:

 

&MAGNETIC

A magnetic field, if present, can be set in two ways: You may use the COMPONENTS command to set a constant magnetic field for use together with an electric field map, but you can not have a magnetic field map for use with an electric field generated by wires and planes.

The cell and gas descriptions are not touched when you enter a magnetic field, but commands like MAGBOLTZ will try and calculate a sensible default B-field range and range of E-B angles if a magnetic field is entered beforehand.

[Initially, the magnetic field is off.]

Additional information on:

 

&GAS

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.

Format:

&GAS

Additional information on:


&OPTIMISE

This section contains a heterogeneous set of commands which assist in finding optimal potential settings, which compute the forces acting on the wire, which add space charge and which modify the chamber layout.

Format:

&OPTIMISE

Additional information on:

 

&FIELD

The field section is used to inspect the electrostatic aspects of your chamber. The main command of the section, PLOT-FIELD, enables plots contours, 3D views, vector fields and histograms of almost any field-related quantity.

Format:

&FIELD

Additional information on:


&DRIFT

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:


&SIGNAL

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 hopefully build a detailed simulation. A series of procedure calls, listed at the end of the overview, form an integral part of this section.

Additional information on:

 

&STOP

Terminates program execution decently. &EXIT and &QUIT are synonymous.

&STOP has an advantage over an end-of-file condition in that &STOP closes the current section before ending program execution. This does not happen with end-of-file. Data that is output when the section is closed, such as gas files and gas plots, are therefore lost when end-of-file is used instead of &STOP.

A section can be closed without stopping Garfield by means of the &MAIN command.

Program execution can also terminate because errors are encountered while the ON-ERROR-TERMINATE option is in effect. Such termination is equivalent to issuing a &STOP command.


OPTIONS

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.

Some options can also be set from the command line.

Format:

OPTIONS [NODEBUG | DEBUG] ...
        [NOIDENTIFY | IDENTIFICATION] ...
        [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:


Call

Do not use curly brackets in Call statements.

Call gives access to a wide variety of routines and data inside Garfield. Although originally intended as a debugging aid, procedure calls are now widely used whenever the commands do not provide sufficient flexibility.

Input arguments can be Global variables, constants or expressions in terms of global variables and/or constants. Output variables are simple global variables - not constants nor expressions. An output variables which does not exist at the time of the procedure call, will be declared automatically. An existing global variable will be overwritten by the procedure.

Procedure arguments which are used as input, must have (one of) the types shown in the description. Some procedures can accept arguments of several types. Fits, for instance, can usually be done on matrices and on histograms. The descriptions of such procedures show two or more formats - one of which must be chosen, the formats should not be mixed.

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.

Format:

CALL procedure(arg1, arg2, ... )

Examples are given in the descriptions of most procedures.

Additional information on:


Do

Do not use curly brackets in Do statements.

Do loops are used to repeatedly execute a set of lines.

There are 3 types of loops in Garfield:

Do not attempt to input a file with < while in a Do loop.

Format of a "From-Step-To" loop:

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 !"

Format of an "In" loop:

For var In in [While while] [Until until] Do
   [statement | Leave [var] | Iterate [var]]
   ...
Enddo

Example:

Vector angles
0 1 2 5 10 30 60 90

For angle In angles Do &SIGNAL (various signal settings required here) track 0.2 2 0.2 {2+0.4*tan(pi*angle/180)} pion energy 5 GeV signal Enddo

Signals are computed for tracks at various inclinations.

Format for a "Leave" loop:

[While while] [Until until] Do
   [statement | Leave [var] | Iterate [var]]
   ...
Enddo

Example:

Do
   Say "Please enter a number"
   Parse Terminal x
   If type(x)=`Number` Then Leave
   Say "{x} is not a number, try again"
Enddo
Say "You entered {x}"

This fragment will keep asking for a value to be given to x until what the user types can be identified as being numeric.

Additional information on:

 

Global

Do not use curly brackets in Global statements.

Assigns a value to a global variable, declares a global variable or lists the currently known global variables, depending on the number of arguments.

Global variables are used for the substitution of an expression in input statements and they play a key role in Do loops, procedure Calls and in conditionally executed If_lines and If_blocks.

This statement has up to 2 arguments:

If there are no arguments: All currently defined globals are listed with their type and value. You will see that the list includes a few predefined globals. Occasionally, you will find globals with names that do not comply with the naming conventions for variables. These are copies of globals which must be kept even if you modify the original. If you wish to see the value of only a single variable, then use Say. To list all currently known strings, matrices and histograms, use the LIST_STRINGS, LIST_MATRICES, and LIST_HISTOGRAMS procedures.

When the value is omitted:

When both a variable name and a value are supplied:

If you wish to use the type of a global variable in a formula, then use either the TYPE function or the INQUIRE_TYPE procedure.

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.

Additional information on:


If_block

Do not use curly brackets in If, Elseif, Iterate and Leave statements.

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 condition Then
   statements
[Elseif condition Then
    statements]
[Else
    statements]
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.

Additional information on:


If_line

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

Additional information on:


Parse

Do not use curly brackets in Parse statements.

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, even if the REXX syntax is far richer than what is offered here.

By default, the values found on input are assigned Literally to the Global. You can also request evaluation of the input prior to assignment by using the Evaluate option.

Format:

Parse [Literal | Evaluate] ...
      {Argument | Global var | Input | Terminal | Value expression} ...
      template

Example 1: Get the piece before and after the decimal dot of pi&sup2;.

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 Evaluate 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-field surface

The usual initialisation files set the global variables YES and NO to respectively True and False. Since we use the Evaluate option, one can simply reply with "yes" or "no" (without typing the quotes), but one may also answer with any expression that evaluates to a Logical such as 3>4. If the default Literal mode were used, only True and False would be accepted.

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 e.g. DC1)
get cell.lib {cell}

Here we use the default Literal mode - the response, DC1, will be classified as string and there is no need for quotes. We could also use the Evaluate mode but then reverse quotes would be required around the user response since we do not want DC1 to be evaluated as if it were a global.

Example 4: An argument to an input file

Assume we have the following input file called "plot_gas":

Parse Arg gas
Call inquire_file(gas/`.gas`,exist)
If ~exist Then
   Say "{gas}.gas does not exist."
Else
   &GAS
   get "{gas}.gas"
   opt gas-plot
   &MAIN
Endif

and a set of gas files with such names as "p10.gas", then we could plot the gas data with a command like:

< plot_gas p10

Additional information on:


Say

The Say command outputs the string that follows it, performing substitution of expressions in terms of Global variables.

Format:

SAY string

Example:

Say "Only {time_left} seconds left !"
Prints the value of a predefined global variable.

Vector

Creates a new 1-dimensional Matrix, also called vector, or reads new data into an already existing Matrix. Matrices contain exclusively numeric data.

Newly created Matrices are 1-dimensional and have a length that is equal to the number of elements entered. Matrices can be given another shape with the RESHAPE_MATRIX procedure.

For existing 1-dimensional Matrices, the new elements replace the existing elements, keeping existing elements if the number of new elements is smaller than the size of the vector, and skipping new elements if there are more than the size of the matrix.

For higher dimensional already existing Matrices, 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).

Use the DELETE_MATRIX procedure to delete the matrix if this way of re-using existing matrices is not as desired.

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.

Fields which are to be ignored, for instance because they do not contain numeric data, are to be identified as DUMMY.

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 1:

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 2\&times;4 matrix. This matrix has one element more than the original vector, which is filled with the value PI, which is one of the pre-defined constants.

We could have written the Vector statement using the concatenation operator & and the ROW function:

Global zzz = 0 & row(6)

Example 2:

Vector Z  dummy  wK     wL1      wL2     wL3     f12  f13   f23
       48 Cd     0.842  0.018    0.056   0.056   0.10 0.59  0.155
       49 In     0.851  0.020    0.061   0.060   0.10 0.59  0.157
       50 Sn     0.860  0.037    0.065   0.064   0.17 0.27  0.157
       51 Sb     0.868  0.039    0.069   0.069   0.17 0.28  0.156
       52 Te     0.875  0.041    0.074   0.074   0.18 0.28  0.155
       53 I      0.882  0.044    0.079   0.079   0.18 0.28  0.154
       54 Xe     0.888  0.046    0.083   0.085   0.19 0.28  0.154
       55 Cs     0.894  0.049    0.090   0.091   0.19 0.28  0.154
       56 Ba     0.900  0.052    0.096   0.097   0.19 0.28  0.153
       57 La     0.905  0.055    0.103   0.104   0.19 0.29  0.153

// Note the empty line

Here, we enter a table (an extract from the Krause fluorescence and Coster-Kronig yields tables) copied from a paper, without having to manually remove the names of the elements. This is done by declaring the field of the element name as "dummy".

Additional information on:

 

algebra

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 or C, with some exceptions:

Evaluation is not as quick as compiled routines but since the formulae are preprocessed and translated into an instruction_list, the losses for repeated evaluations are small compared to what would otherwise be needed in terms of human time.

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 edited 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:


comment

Garfield recognises in-line comments in C++ style as well as Fortran style comment lines.

The program ignores the portion of a physical input line that follows a double slash (//). If the line has a continuation mark (...) preceding the //, then the following physical input line will be concatenated with what preceded the ellipsis.

Format:

statement // comment

Examples:

Global a=5 // initialise A

box centre -1.3 1.39 0 ... // Centre of strip 1 half-lengths 0.01 0.65 0.1 ... // Dimensions conductors-2 // Material

Garfield ignores an entire input line that begins with an asterisk (*). Also all continuation lines, as signalled with an ellipsis (...), are considered as comment.

Format:

* comment

Example:

* this is a comment ...
  that spans several ...
  lines

control_keys

Control keys can be used to interrupt the program.

Additional information on:


dataset

The dataset commands manipulate Garfield datasets.

Although Garfield datasets are sequential files for the operating system, they have for Garfield purposes the structure of libraries composed of one or more members. A member can for instance be a compact cell description, a piece of program output or a signal in Spice readable format.

Garfield datasets can be moved between machines, you may also operate on such datasets on other computers if the OS allows.

Garfield libraries are things you would not normally wish to edit except to extract an x(t)-relation or a piece of output. Instead, the program provides a set of instructions that make directory listings, list individual members and delete members.

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:


error_handling

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 occurrence of the error.

For further details, see short writeup N001: http://consult.cern.ch/shortwrups/n001/top.html


graphics

Most of the graphics settings can be changed during the run. For instance, one can:

Settings that are common for most of your runs can be placed more conveniently in your initialisation file. This is for instance the case of the colours and the representations.

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:

 

input

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 to be read by Garfield.

To prepare such a file,

Reading a file that contains input statements, is achieved with the "<" command. The file will be read until its end, unless a label is specified and seen. While the file is being read, the global variable INPUT contains the name of the new input file. Items that follow the label, if present, are made available to the Parse Argument statement and can thus be used as arguments of the input file.

Format:

< file [<< label] [arguments]

Example:

< rpc

To read the file called "rpc" until the end of the file.

Additional information on:

 

output

Re-routs most of the output to a file. To revert to terminal output, enter the ">" command without dataset name.

Output to datasets is buffered on some systems. The output file is therefore complete only when the buffer is emptied, i.e. when the file is closed. The file is closed when you type > without file name and also when you end program execution with the &STOP command.

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. You can find out whether output is being re-routing by examining the OUTPUT global variable.

Format to start re-routing:

> file [member [remark]]

Format to stop re-routing:

>

Example:

> field.map
print ex,ey,e,v
>

This example works in the field section. First the output is re-routed to the dataset FIELD.MAP, this file captures the long printout from the PRINT command and then output is sent to the terminal again.

Additional information on:

 

recording

Garfield will at your request record your terminal input.

On systems which permit multiple versions of a file (e.g. VMS and OpenVMS), a separate copy of the recording file will be generated for each run. On other systems, the previous recording file (if any) is renamed with extension .bak, and the one-but-last recording file is deleted.

The recorded input is commonly used as input for subsequent runs.

The command to start recording is:

>> file

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:

 

shell

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.

The case of the command following the $ is preserved, hence there is normally no need to use quotes. One may perform substitution of expressions using curly brackets.

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            LOGOUT          exit             RETURN

Examples:

$ emacs layout &

Global gas_file `Ar_DME.gas` $ ls -l {gas_file}

Starts an emacs editing session and list the characteristics of the gas file.

Additional information on:


translation

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:


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

Formatted on 21/01/18 at 16:55.