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

input_format

  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.

syntax

  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.

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

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

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

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

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

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 1998 the main
  program (excluding Magboltz and Heed) counts 105000 lines (4 Mb).

units

  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.

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