CERN home page CERN home page Consult pages Consult pages Writeups at CERN Writeups at CERN Garfield pages Garfield pages Help pages Help pages This page This page Table of contents Keyword index

Overview

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.

These pages have a tree structure with the sections as main branches:

Garfield has a limited set of control structures that can be used at any level of program input: Occasionally, you may also wish to use the various utilities: The command to leave Garfield is &STOP.

Chapter 1: 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).

Section 1.1: 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 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.

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

Text strings, such as formulae, that should not be broken up but which contain a word separator, should be enclosed with single or double quotes. The string is converted to upper case when single quotes are used, while the case is preserved with 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:

    PLANE V=1000 X=10

without affecting the meaning of the command. This is true in general (except where explicitly stated otherwise). 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.

Section 1.2: 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 item from the list between brackets, but this is optional. A default value will be used if you omit this item. The square brackets are not part of the command, they 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).

Section 1.3: 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 following sybols: blanc, comma, colon or equal sign.
quotes
Like with quotes, the 3 types of quotes used in Garfield input can not be interchanged.

Section 1.4: 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 ...
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

Section 1.5: brackets

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

Section 1.6: quotes

Three kinds of quotes are used in Garfield. Please use them correctly !!!

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

Section 1.8: 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).

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

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

Section 1.10: 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
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.

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

Chapter 2: &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 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.


Chapter 3: &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

Section 3.1: overview

Cell sections come in 2 formats:

Creating a new cell:

Command Short description
CELL-IDENTIFIER Provides a short description to the cell
DEFINE Sets local parameters for use with ROWS
DIELECTRICUM Enters a dielectric slab (do not use !)
FIELD-MAP Reads a finite element field map
OPTIONS Plotting of a layout etc
PERIODICITY Makes the cell periodic
PLANE Enters a plane
RESET Cancels part of the cell description
ROWS Header for the list of wires
SAVE-FIELD-MAP Writes a field map in binary format
SOLIDS Enters solid volumes for use with field maps
TUBE Enters a tube surrounding the wires
WRITE Writes a compact format dataset

Retrieving a cell from a dataset:

Command Short description
GET Retrieves a compact cell description
READ-FIELD-MAP Reads a binary field map

Section 3.2: methods

3.2.1: potential_function

Garfield classifies chambers according to the number and orientation of planes, the presence of periodicities and the location of the wires as one of the following types:

Potential Use
A Non-periodic cells with at most 1 x- and 1 y-plane
B1X x-Periodic cells without x-planes and at most 1 y-plane
B1Y y-Periodic cells without y-planes and at most 1 x-plane
B2X Cells with 2 x-planes and at at most 1 y-plane
B2Y Cells with 2 y-planes and at at most 1 x-plane
C1 Doubly periodic cells without planes
C2X Doubly periodic cells with x-planes
C2Y Doubly periodic cells with y-planes
C3 Doubly periodic cells with x- and y-planes
D1 Round tubes without axial periodicity
D2 Round tubes with axial periodicity
D3 Polygonal tubes without axial periodicity
D4 Polygonal tubes with axial periodicity
MAP Field maps

Each chamber type has its own potential function. For numerical purposes, nearly all potential functions are further subdivided into a set of domains according to the aspect ratio of the periodicties, the distance between wires and planes etc.

Furthermore, versions of most potential functions exist which have been written so as to take advantage of vector hardware.

One can use the GET_CELL_DATA to find out which potential function is in use. The cell type is also displayed in response to the CELL-PRINT option.

3.2.2: coordinate_system

Currently, 3 coordinate systems are available:

Coordinate system Use
Cartesian Cells described in (x,y) coordinates, field maps
Polar Cells described in (r,phi) coordinates
Tube Cells which contain a TUBE

One can use the GET_CELL_DATA to find out which system is in use.

3.2.2.1: Cartesian

In Garfield, the fundamental coordinate system is Cartesian.

Potentials for chambers made of wires and planes are computed using a variety of potential_functions.

Cartesian coordinates are also used for field maps, even if the map is of the axially symmetric (r,z) type. The potentials for field maps are polynomially interpolated in triangular, tetrahedric or rectangular coordinates, as appropriate.

3.2.2.2: Polar

Polar coordinates are dealt with by the conformal mapping:
(x,y) = exp(rho,phi)

Most of the commands translate the internal coordinates to polar coordinates, but procedures as a rule don't do this. A set of procedures has been provided for these transformations: CARTESIAN_TO_POLAR, CARTESIAN_TO_INTERNAL, INTERNAL_TO_CARTESIAN, INTERNAL_TO_POLAR, POLAR_TO_CARTESIAN and POLAR_TO_INTERNAL.

3.2.2.3: Tube

The tube coordinates are special in the sense that the wire locations are listed in Cartesian coordinates, while the tube is an object with a polar shape. Garfield internally uses Cartesian coordinates for cells of this type.

Potentials in round tubes are computed using the conformal mapping:

    z - z0
z = -----------
    1 - z0bar z
which maps z0 to 0 and which maps the unit circle onto itself.

Potentials in polygonal tubes are computed by mapping the centre of the tube to a round tube, while the edges are

3.2.3: shape_function

For information on shape functions, see:

A. R. Mitchel and R. Wait, The finite element method in partial differential equations, Wiley (1977).

Section 3.3: CELL-IDENTIFIER

Assigns an identification string to the cell description. The string is used in the plots when the information is relevant. It is advisable to enclose the identifying string by double quotes: this will preserve the case and you may have blanks inside the string.

Format:

CELL-IDENTIFIER string

Example:

CELL-ID "DC1 central cell"

Section 3.4: DEFINE

Defines a variable to be used in the listing of the ROWS of wires.

As usual, the current value of a variable is displayed if no new value is provided. All variables are displayed if arguments are absent altogether.

Do not confuse DEFINE with Global: DEFINE defines local variables for the cell section. Global defines variables that you can use anywhere. Expressions using local variables and the loop-variable are evaluated automatically. Expressions in terms of global variables have to be enclosed by curly brackets to obtain substitution.

Format:

DEFINE variable value

Example:

DEF VP_1=1000
DEF VP_2=2000
DEF R_1=5000
DEF R_2=5000
DEF VP_BETWEEN=(VP_1*R_2+VP_2*R_1)/(R_1+R_2)
DEF VP_BETWEEN

A simple resistor chain, the last line displays the value. You could in principle also enter the whole formula in the ROWS lines.

global resistor=5000
define r_1 {resistor}
define r_2 {resistor}

The global variable RESISTOR is copied to R_1 and R_2, which are local variables.

3.4.1: variable

The variable should be a string of at most 10 characters, the first of which should be alphabetic. Special characters may be used, unless they coincide with any of the arithmetic operators.

The naming conventions for variable names should be observed.

The total number of variable names that can be stored is usually set to 100. If you need more, you'll have to recompile the program with a suitable value for MXVAR.

The variable name I is reserved as loop-variable.

3.4.2: value

The value should be a valid algebraic expression.

Each variable may be defined in terms of previously defined variables and redefinition of variables is permitted at any time.

Section 3.5: DIELECTRICUM

+-----------------------------------------------------------------+
| The current version of Garfield only takes dielectrics into     |
| account in a small number of configurations. It is much better  |
| to use a finite elements program to generate a field map and to |
| read such a map in with the FIELD-MAP instruction.              |
+-----------------------------------------------------------------+

Adds a slab of dielectric material to your cell. The slab extends from -infinity to +infinity in one direction and has a range you choose in the other.

x-Slabs and y-slabs of dielectric material are allowed to overlap provided they have the same dielectric constant. Slabs in one direction are not allowed to overlap, even if they have the same dielectric constant.

Dielectrica may be located amidst the wires but the must be inside the equipotential planes, if there are any in your cell.

Dielectrica slow the program down by a significant amount.

Format:

DIELECTRICUM {X-RANGE|Y-RANGE} min max EPSILON eps

Example:

DIELECTRICUM X -10 10 EPS 5

This slab of dielectric material covers the -10 < x < 10 part in x and the whole of y. The dielectric constant for the material is chosen to be 5.

3.5.1: min_max

The range along the specified coordinate axis the slab should cover. No default provided.

3.5.2: eps

The dielectric constant of the material relative to vacuum. The constant has to be larger than 0. There is no default for this parameter.

Section 3.6: FIELD-MAP

The electrostatics part of the Garfield program does not deal with dielectrics and 3-dimensional structures. However, Garfield can read field maps generated by an (external) finite program.

Currently, field maps in the format generated by Maxwell Parameter Extractor 2D and 3D as well as by Tosca and Maxwell Field Simulator 2D and 3D can be read. Interfaces for files produced by other such programs can be added (please contact the author).

When you read a field map, any wire, plane, periodicity, dielectric medium and magnetic field that you entered sofar is deleted.

Reading large field maps is time consuming. To save time, you can after having read a set of external field maps with FIELD-MAP, write a binary field map with SAVE-FIELD-MAP and read it in with READ-FIELD-MAP. Such field maps are much smaller and much faster to read in, but are not portable between computer systems.

Also the optimisation section has a FIELD-MAP command. The field maps entered in the cell section serve as main field, i.e. the field map replaces the field due to wires and planes, while the field maps entered in the optimisation section are used for the computation of the background field. The two field maps share (for the moment) the same storage and can therefore not be used at the same time.

The FIELD-MAP command can also read magnetic fields computed by finite element programs. For the moment, there is no experience with such fields.

Format:

FIELD-MAP [FILES [contents_1] file_1 [LABEL solid_1] ...
                 [contents_2] file_2 [LABEL solid_2] ...
                 ...
                 [contents_n] file_n [LABEL solid_n] ...
                 format ] ...
          [DRIFT-MEDIUM {SMALLEST-EPSILON | ...
                         SECOND-SMALLEST-EPSILON | ...
                         n | ...
                         SECOND-LARGEST-EPSILON | ...
                         LARGEST-EPSILON | ...
                         epsilon}] ...
          [NOT-X-PERIODIC | X-PERIODIC | ...
               X-MIRROR-PERIODIC | X-AXIALLY-PERIODIC] ...
          [NOT-Y-PERIODIC | Y-PERIODIC | ...
               Y-MIRROR-PERIODIC | Y-AXIALLY-PERIODIC] ...
          [NOT-Z-PERIODIC | Z-PERIODIC | ...
               Z-MIRROR-PERIODIC | Z-AXIALLY-PERIODIC] ...
          [LINEAR | QUADRATIC | CUBIC] ...
          [DELETE-BACKGROUND | KEEP-BACKGROUND] ...
          [WINDOW xmin ymin [zmin] xmax ymax zmax] ...
          [Z-RANGE zmin zmax] ...
          [PLOT-MAP | NOPLOT-MAP] ...
          [NOHISTOGRAM-MAP | HISTOGRAM-MAP] ...
          [RESET]

Example:

&CELL
field-map files "e_field.arg" "potential.arg" "epsilon.arg" ...
          drift-medium second-smallest ...
          x-periodic

(Maxwell Parameter Extractor 2D has been used to generate maps of the electric field, the potential and the dielectric constant. These maps are read in and the medium with the 2nd smallest dielectric constant is declared to be the drift medium. The map is also declared to be periodic in the x direction.)

3.6.1: FILES

The set of files to be read in. The files can contain the mesh or maps of:

Notes:

  1. All maps must share the same grid.
  2. The weighting field of an electrode is the electric field that results from placing that electrode at 1 V and earthing all others. This field is used to compute the signals induced on an electrode by moving charges.
  3. The D field is only used to compute the dielectric constants by comparison with E.

3.6.2: contents

One may specify the contents of the file before the name. This is mandatory in the following cases:

In case Maxwell Field Simulator has been used to generate the maps, identifying the mesh directory is recommended. The contents is optional for all other types of data written by Maxwell programs.

A warning is issued if the file contains other data than the declared contents.

Currently, the following contents types are recognised:

Name Used to compute
B-FIELD (=MAGNETIC-FIELD) Drift lines
ELECTRIC-FIELD Drift lines, various other plots
D-FIELD Epsilon by comparing E and D
MATERIAL (=D-FIELD) Drift line termination
MESH Always needed with Maxwell Field Simulator
POTENTIAL (=VOLTAGE) Contour maps
WEIGHTING-FIELD Induced signals

3.6.3: label

Serves two purposes:
  1. The label links a weighting field with solids. For this association, the weighting field label should match one or more labels used in the SOLIDS listing. A solid label should not match more than one weighting field label, unless the signals for these weighting fields are summed. In the absence of a match, all signals on the weighting field map are classified as cross induced. Such signals are only computed if the CROSS-INDUCED option is active.
  2. The label identifies the weighting field to the SELECT statement, a prerequisite for the computation of signals in the electrodes for which the weighting field has been computed.

The label is a single character.

No label should be assigned to other fields than the weighting fields.

[By default, the label "S" is assigned to weighting field maps, which makes these maps are part of the initial, default, selection.]

3.6.4: format

Specifies the program that has been used to generate the field maps. Currently, the following formats are accepted:

With the exception of Tosca, all formats are automatically recognised, and a format doesn't have to be specified therefore.

Recipes for creating field maps with these programs are given in the sub-topics.

3.6.4.1: PARAMETER-EXTRACTOR-2D

Specifies that the field map has been generated by the Ansoft program called "Maxwell 2D Parameter Extractor". The format of these files is identified automatically, and the format doesn't have to be specified therefore.

To generate your field maps with Maxwell Parameter Extractor 2D, you may wish to follow this recipe:

  1. Go through the various steps until "Solve Parameters", taking care (before drawing anything) to adjust in "Draw Cross Section" the "Model Drawing Size" such that it fits exactly the area of your detector - do not leave any empty space around it. Then enter "View Fields" from where you perform the following steps:
  2. Click on "calc", select "plane", if the upper area is not empty then click on "clear". Do also a "smooth" and a "push" to ensure the mesh is the same for all maps. Then click on "voltage" and do an ASCII "write" to a file ("write" is in the second set of commands to which you access via "next", to get back to the first set click on "prev"). Maxwell appends the string ".arg" to the file name you enter. This creates a map of the potential.
  3. Repeat step 2 with "E_vector" instead of "voltage", choose a file name different from the one used in step 2. This creates a file that contains both Ex and Ey.
  4. Depending on the Solver that you use:
  5. If you do not wish to compute signals, you are ready at this point. Otherwise, go back to the "Parameter Extractor" main menu, click on "Setup Boundaries/Sources", and select "Define", confirm that you wish to "Modify" and then adjust the voltages of all electrodes such that the electrode that you wish to read out is at 1 V and all other electrodes at 0 V. Then "Exit", confirming that you wish to save the modifications.
  6. Go to the "Setup Solution Parameters" in the Parameter Extractor, click on "Capacitance", select "Current" as Starting Mesh, suppress "Adaptive Analysis". This ensures that the field is calculated on the same mesh as the field calculated in point 1.
  7. Write out the electric field as described in step 2, choosing a file name different from the names chosen in steps 2, 3 and 4. This generates the weighting field. Repeat from step 5, if you intend to read out more than one electrode.

These steps should lead to a set files with names that end on .arg and that are located in the es.pjt subdirectory of your project.

Be sure to create the E, V, epsilon/sigma and weighting field maps with identical meshes and the E, V and epsilon/sigma maps with identical boundary conditions.

The names of these 4 files should be placed after the FILES keyword of the FIELD-MAP command, the name of the weighting field maps should be preceded by the keyword "WEIGHTING-FIELD" to distinguish it from the regular electric field map. The order is not important. There is no need to specify that the files come from Maxwell Parameter Extractor 2D.

Information about using Maxwell at CERN can be found in http://wwwcae.cern.ch/Maxwell/Maxwell.html The Maxwell 2D Parameter Extractor User's Reference manual is available at CERN via http://wwwinfo.cern.ch/ce/cern_only/ae/tl2d.ps

(Instructions from Pawel Majewski)

3.6.4.2: FIELD-SIMULATOR-2D

Specifies that the field map has been generated by the Ansoft program called "Maxwell 2D Field Simulator". The format of these files is identified automatically, and the format doesn't have to be specified therefore.

To generate your field maps with Maxwell 2D Field Simulator, you may wish to follow this recipe:

  1. Go through the various steps until "Solve". Then enter "Post Process" for the "nominal problem", from where you perform the following steps:
  2. Click on "calc", select "Plane", if the upper area is not empty then click on "clear". Then click on "voltage" and do an ASCII "write" to a file ("write" is in the second set of commands to which you access via "next", to get back to the first set click on "prev"). Choose a file name like "V", Maxwell appends the string ".arg" to the file name you enter. This creates a map of the potential.
  3. Repeat step 2 with "E_Vector" instead of "voltage", choose a file name different from the one used in step 2. This creates a file that contains both Ex and Ey.
  4. If you wish Garfield to know about the materials present in the chamber, then either:
  5. If you do not wish to perform signal calculations, you're ready at this point. Otherwise go back to the "2D Field Simulator" main menu, enter "Setup Boundaries/Sources", confirm that you wish to "Modify" and then adjust the voltages of all electrodes such that the electrode that you wish to read out is at 1 V and all other electrodes at 0 V. Then "Exit", confirming that you wish to save the modifications.
  6. Go to the "Setup Solution" in the main menu, select "Options", select "Current" as Starting Mesh, suppress "Adaptive Analysis" and click "OK". Next go to "Solve" in the main menu and select "Nominal Problem". These steps compute the weighting field on the same mesh as the field calculated in point 1.
  7. Write out the electric field as described in step 2, choosing a file name different from the names chosen in steps 2, 3 and 4. This generates the weighting field map. Repeat from step 5 if you intend to read more than one electrode.

These steps should lead to a set of files with names that end on .arg and that are located in your project directory.

Be sure to create the E, V, epsilon/sigma and weighting field maps with identical meshes and the E, V and epsilon/sigma maps with identical boundary conditions.

The names of these 4 files should be placed after the FILES keyword of the FIELD-MAP command, the name of the weighting field maps should be preceded by the keyword "WEIGHTING-FIELD" to distinguish it from the regular electric field map. The order is not important. There is no need to specify that the files come from Maxwell 2D Field Simulator.

Information about using Maxwell at CERN can be found in http://wwwcae.cern.ch/Maxwell/Maxwell.html

3.6.4.3: PARAMETER-EXTRACTOR-3D

Specifies that the field map has been generated by the Ansoft program called "Maxwell 3D Parameter Extractor", version 1.1 (Feb 1993). The format of these files is identified automatically, and the format doesn't have to be specified therefore.

When generating your field maps with this program, you may wish to follow this recipe:

  1. Go through the various steps until "Solve Parameters", taking care (before drawing anything) to adjust in "Draw Cross Section" the "Model Drawing Size" such that it fits exactly the area of your detector - do not leave any empty space around it. Then enter "View Fields" from where you perform the following steps:
  2. Click on "calc", select "space", if the upper area is not empty then click on "clear". Click on "phi", do a "push" to ensure the mesh is the same for all maps and then "smooth" the potential map. Do an ASCII "write" to a file. Maxwell appends the string ".arg" to the file name you enter, it is therefore sufficient to enter for instance just "V". This creates a map of the potential.
  3. Repeat step 2. for "E_vector" and "D_vector", without doing a "push", and writing to files with different names. Creating the D field map is optional.
  4. You may also wish to create weighting field maps as described for Maxwell Parameter Extractor 2D.

This procedure should create maps of the electrostatic potential, the E field, the D field and perhaps of a weighting field. The dielectric constants are computed by comparing E and D. These files will be located in the efs3d.pjt subdirectory of your project.

Be sure to create the E, V, D and weighting field maps with identical meshes and the E, V and D maps with identical boundary conditions.

Information about using Maxwell at CERN can be found in http://wwwcae.cern.ch/Maxwell/Maxwell.html The Maxwell 3D Parameter Extractor User's Reference manual is available at CERN via http://wwwinfo.cern.ch/ce/cern_only/ae/3duref.ps

3.6.4.4: FIELD-SIMULATOR-3D

Specifies that the field map has been generated by the Ansoft program called "Maxwell 3D Field Simulator", version 4.0. The format of these files is identified automatically, and the format doesn't have to be specified therefore.

When you use this program to create your field maps, you have to provide the following to Garfield:

  1. The mesh: The mesh is contained in a .hyd and a .pnt file stored in the project directory (and not in an "efs3d.pjt" subdirectory of the project directory). The files have names like "fileset2", "fileset1", "current", "efs3d", "previous" and "initial".

  2. The field maps of V, D and E written out in .reg format. With Maxwell 3D Field Simulator, there is no need to smooth the field maps, as opposed to Maxwell 3D Parameter Extractor.

    The field maps can be created as follows: After having gone through the various steps, in the "Post Process" menu, select "Nominal Problem". From the "Data" menu, select "Calculator". In the "Input" column select the "Qty" menu where you pick "phi". In the "Output" column select "Write ..." and write out the field to a file called, for instance, "V.reg". Repeat the same steps replacing "phi" by "E" and "D".

  3. Optionally, you may also provide weighting fields. Weighting fields are electric fields that are obtained by setting the potential of all conductors to 0 V except the read-out conductor which is set to 1 V.

Be sure to create the E, V, D and weighting field maps with identical meshes and the E, V and D maps with identical boundary conditions.

Information about using Maxwell at CERN can be found in http://wwwcae.cern.ch/Maxwell/Maxwell.html

3.6.4.5: TOSCA

To generate your field maps with Tosca on a Unix system, you have to:
  1. use OPERA version 7.0.

  2. Generate the geometrical mesh with the 3d Opera preprocessor.

  3. Click on "MESH" and then choose the "quadrilaters" option.

  4. Click again on "MESH" and choose the "Volume mesh ... Mesh *" option.

  5. Click on "FILE" and choose the "write node table" option in order to create the "username.table" file that contains the mesh node coordinates.

  6. Generate, clicking again on "FILE", the usual username.OP3 file ready to be analysed by TOSCA.

  7. Run the Fortran program "util" with the command: $VFDIR/opera/3d/util > "username1.table" and, after pushing the "return" buttom, typing "username.op3" on the keyboard and pushing "return" again. The file "username1.table" includes now a table that describes each element of the mesh, specifying the nodes that make it up.

  8. Run TOSCA.

  9. Run the 3d Opera postprocessor. Load the TOSCA result. Click on "FIELDS" and choose the "table of field points" sub-menu. In this sub-menu:
    1. Select "input from file" and give "username.table" (see item 6 above) as input.
    2. Choose an "username2.table" as output according to your taste
    3. Click on "output components options" and define:
      • Component 1 = X
      • Component 2 = Y
      • Component 3 = Z
      • Component 4 = Ex
      • Component 5 = Ey
      • Component 6 = Ez
      • Component 7 = Dx
      • Component 8 = Dy
      • Component 9 = Dz
      • Component 10 = V
    4. Click the "process table" option that will describe, for each mesh node, the value of the electric field and potential.

The files "username1.table" and "username2.table" (see item 6 and 10 above) are now ready for Garfield.

A Garfield input file that uses "username.table" and "username1.table" can be found in http://consult.cern.ch/writeup/garfield/examples/tosca/example

A single Tosca generated map can contain various kinds of data, such as the potential, the electric field and the D field. Since the file contains a description of the data, the contents field should only make clear that the file is not a mesh file. One can therefore set the contents field on the FIELD-MAP command to be any of the contained items.

(Recipe from Guido Maria Urciuoli, INFN Gruppo Collegata Sanitá, Viale Regina Elena 299, 00161 Roma, Italia.)

3.6.5: DRIFT-MEDIUM

If you provide a map of the dielectric constants, of the conductivity, or both a map of D and a map of E, you have the possibility to specify which of the materials is the drift medium.

There are 3 ways to select the drift medium:

Beware: DRIFT-MEDIUM 3 is not the same as DRIFT-MEDIUM 3.0 ! In the first case, the medium with the 3rd dielectric constant or the 3rd conductivity will be selected. In the second case, the medium with the dielectric constant or the conductivity closest to 3 will be taken.

When using the DC conduction mode, it may be more natural to use the keywords SMALLEST-SIGMA, SECOND-SMALLEST-SIGMA, SECOND-LARGEST-SIGMA and LARGEST-SIGMA which are treated as synonyms of the keywords listed in the command description.

[By default, the medium with the lowest dielectric constant or the lowest conductivity is assumed to be the drift medium.]

3.6.6: RESET

Resets the field map, has the same effect as RESET FIELD-MAP.

3.6.7: NOT-X-PERIODIC

Specifically states that the field map is not periodic in x.

[This is the default.]

3.6.8: X-PERIODIC

States that the field map has an x-periodicity.

The length of one period is taken to be the maximum extent in x of the field map.

A cell can not be both X-PERIODIC and X-MIRROR-PERIODIC, but can be X-AXIALLY-PERIODIC in addition to being translation periodic in the x-direction.

[By default, a field map is not assumed to be periodic.]

3.6.9: X-MIRROR-PERIODIC

States that only half of the cell has been entered and that there is a mirror image on both sides. In addition, the cell has a periodicity, equal to twice the maximum extent in x of the field map.

A cell can not be both X-PERIODIC and X-MIRROR-PERIODIC, but can be X-AXIALLY-PERIODIC in addition to being translation periodic in the x-direction.

[By default, a field map is not assumed to be periodic.]

3.6.10: X-AXIALLY-PERIODIC

States that the cell has an axial periodicity around the x-axis and that only one period is represented in the field map.

The length of one period is deduced from the field map, and is therefore not specified on the FIELD-MAP statement.

The symmetry axis must pass through y=z=0.

A cell can not be both X-PERIODIC and X-MIRROR-PERIODIC, but can be X-AXIALLY-PERIODIC in addition to being translation periodic in the x-direction.

[By default, a field map is not assumed to be periodic.]

3.6.11: NOT-Y-PERIODIC

Specifically states that the field map is not periodic in y.

[This is the default.]

3.6.12: Y-PERIODIC

States that the field map has an y-periodicity.

The length of one period is taken to be the maximum extent in y of the field map.

A cell can not be both Y-PERIODIC and Y-MIRROR-PERIODIC, but can be Y-AXIALLY-PERIODIC in addition to being translation periodic in the y-direction.

[By default, a field map is not assumed to be periodic.]

3.6.13: Y-MIRROR-PERIODIC

States that only half of the cell has been entered and that there is a mirror image on both sides. In addition, the cell has a periodicity, equal to twice the maximum extent in y of the field map.

A cell can not be both Y-PERIODIC and Y-MIRROR-PERIODIC, but can be Y-AXIALLY-PERIODIC in addition to being translation periodic in the y-direction.

[By default, a field map is not assumed to be periodic.]

3.6.14: Y-AXIALLY-PERIODIC

States that the cell has an axial periodicity around the y-axis and that only one period is represented in the field map.

The length of one period is deduced from the field map, and is therefore not specified on the FIELD-MAP statement.

The symmetry axis must pass through x=z=0.

A cell can not be both Y-PERIODIC and Y-MIRROR-PERIODIC, but can be Y-AXIALLY-PERIODIC in addition to being translation periodic in the y-direction.

[By default, a field map is not assumed to be periodic.]

3.6.15: NOT-Z-PERIODIC

Specifically states that the field map is not periodic in z.

[This is the default.]

3.6.16: Z-PERIODIC

States that the field map has a z-periodicity.

The length of one period is taken to be the maximum extent in z of the field map.

A cell can not be both Z-PERIODIC and Z-MIRROR-PERIODIC, but can be Z-AXIALLY-PERIODIC in addition to being translation periodic in the z-direction.

[By default, a field map is not assumed to be periodic.]

3.6.17: Z-MIRROR-PERIODIC

States that only half of the cell has been entered and that there is a mirror image on both sides. In addition, the cell has a periodicity, equal to twice the maximum extent in z of the field map.

A cell can not be both Z-PERIODIC and Z-MIRROR-PERIODIC, but can be Z-AXIALLY-PERIODIC in addition to being translation periodic in the z-direction.

[By default, a field map is not assumed to be periodic.]

3.6.18: Z-AXIALLY-PERIODIC

States that the cell has an axial periodicity around the z-axis and that only one period is represented in the field map.

The length of one period is deduced from the field map, and is therefore not specified on the FIELD-MAP statement.

The symmetry axis must pass through x=y=0.

A cell can not be both Z-PERIODIC and Z-MIRROR-PERIODIC, but can be Z-AXIALLY-PERIODIC in addition to being translation periodic in the z-direction.

[By default, a field map is not assumed to be periodic.]

3.6.19: LINEAR

Requests linear interpolation of all fields within each triangle or each tetrahedron. This leads to interpolated fields that are continuous, but have a discontinuous first derivatives at the boundaries between the triangles/tetrahedrons.

This method can be applied to all field maps.

[By default, the highest order method permitted by the field map will be used.]

3.6.20: QUADRATIC

Requests quadratic interpolation of the fields within each triangle or each tetrahedron. The interpolation is done using normalised Lagrange polynomials in terms of the triangular coordinates. This ensures that the field on triangle/tetrahedron boundaries depends only on the field values of the nodes located on the boundary. Therefore, the interpolated fields are continuous, but the first derivative is in general not continuous across boundaries between adjacent triangles/tetrahedrons.

This method can only be applied to field maps with additional nodes halfway the vertices. This information is present in for instance all Maxwell field maps.

[By default, the highest order method permitted by the field map will be used.]

3.6.21: CUBIC

Requests cubic interpolation of the fields within each triangle or each tetrahedron. The interpolation is done using normalised Lagrange polynomials in terms of the triangular coordinates. This ensures that the field on triangle/tetrahedron boundaries depends only on the field values of the nodes located on the boundary. Therefore, the interpolated fields are continuous, but the first derivative is in general not continuous across boundaries between adjacent triangles/tetrahedrons.

This method can only be applied to field maps with additional nodes at 1 third and at 2 thirds between the vertices. There are currently no field map formats with which this interpolation order can be used.

[By default, the highest order method permitted by the field map will be used.]

3.6.22: DELETE-BACKGROUND

Option only active with Maxwell Field Simulator 3D.

Removes the excluded parts of the background from the field map.

[This option is on by default.]

3.6.23: WINDOW

The WINDOW keyword is used to eliminate triangles or tetrahedrons from the mesh.

A triangle or a tetrahedron is eliminated whenever one of its vertices is located outside the window.

3.6.24: Z-RANGE

Every cell needs, for Garfield, to have a default extent in all 3 dimensions. When the cell contains only wires and planes, then the extent in z is derived from the length of the wires. When instead, a 2-dimensional field map is used, there is no way to know the z-extent of the cell.

This argument is ignored if the field map is 3-dimensional.

[By default, the cell is assumed to go from -50 cm to +50 cm in the z-direction.]

3.6.25: PLOT-MAP

Requests the materials to be shown in plots of the chamber.

The option has effect only if material properties have been entered, either as a map of dielectric constants or as maps of both D and E.

The materials are distinguished by their dielectric constant, which must therefore have been entered with the FIELD-MAP command. This can be done with an explicit map of dielectric constants, but also by a comparison of maps of E and D.

The material with the smallest dielectric constant is shown with representation MATERIAL-1. The medium with the next highest dielectric constant with MATERIAL-2 etc. The drift medium is never shown.

Elements of a 2D field map are only shown in X-Y views and in CUT views at a constant z. The cross sections of the viewing plane with the elements of a 3D field map are shown in X-Y, X-Z, Y-Z and CUT views, but not in 3D views.

Field maps do not usually cover areas filled with conducting material since there is no field inside these. To visualise these, one has to enter them manually with the SOLIDS command. SOLIDS doesn't interfere with PLOT-MAP.

This option can also be switched on and off with the PLOT-MAP option of the AREA command.

[By default, the map is shown.]

3.6.26: HISTOGRAM-MAP

Requests histograms to be plotted of the aspect ratio (i.e. the ratio of the largest and the smallest vertex separation within a tetrahedron or triangle) and of the surface or volume of the tetrahedrons or triangles in the mesh that is read.

Tetrahedrons and triangles with large aspect ratios can be a sign that the mesh is of poor quality. When using Maxwell, one should consider adding dummy volumes which constrain the mesh elements (contact CERN Maxwell support or Ansoft for further information).

Tetrahedrons with a very large volume and triangles with a very large surface are likely to cause problems while drifting particles since the E field inside is linear, without guaranteed match with neighbouring elements.

[These histograms are not made by default.]

Section 3.7: GET

Retrieves a compact format cell dataset written by WRITE. Any cell information you may already have entered, is cleared.

This command is executed immediately and you may - with caution - replace some of the elements of the description after issuing the command.

Format:

GET dsname [member]

Examples:

GET 'disk$zp:[veenhof.garfield]cell.dat'
GET lib

(The last example will presumably take the first member of type CELL from the library with file name LIB. Such libraries may contain members also of other types - only members of type CELL will be considered by GET. On Vax, the file name of the last example would be expanded to LIB.DAT.)

3.7.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

3.7.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

Section 3.8: GRAVITY

Orients the chamber in space. This orientation matters when one computes the sag of the wires due to gravitational forces.

The 3 arguments form a vector that indicates the direction in which gravity pulls on the wire. Only the direction of the vector is used, not its normalisation.

The default setting is (0,0,1) i.e. gravity works along the wires.

Format:

GRAVITY  x y z

Example:

gravity  0 0 1

This makes the wires run vertical, the default. In this situation, gravity does not produce a wire sag.

Section 3.9: OPTIONS

Selects both global and local options. Only the local options are not listed here. For global options, see the top level OPTIONS command.

Format:

OPTIONS [NOLAYOUT | LAYOUT] ...
        [NOCELL-PRINT | CELL-PRINT] ...
        [NOTISOMETRIC | ISOMETRIC] ...
        [NOWIRE-MARKERS | WIRE-MARKERS] ...
        [NOCHARGE-CHECK | CHARGE-CHECK]

Example:

OPT C-PR

Requests a summary of the elements present in the cell.

3.9.1: CELL-PRINT

Switching on this option, will cause a detailed description of the cell to be printed at the time the cell section is left. The table contains amongst others the wire numbers which may be useful later on with SELECT.

The same listing can be obtained in the optimisation section using the PRINT-CELL command.

[This option is initially off but its setting is remembered from one cell section to the next.]

3.9.2: LAYOUT

Switching on this option, will cause a layout of the cell to be plotted when the cell section is left. The wire labels are shown. Mainly used to check typing mistakes visually.

[This option is initially off but its setting is remembered from one cell section to the next.]

3.9.3: ISOMETRIC

If the cell has a substantially bigger length in one direction than in the other, the layout plot will be distorted. If you specify the ISOMETRIC option, the x and y range of the layout plot are the same and the chamber will have a normal appearance.

This option has only effect on the layout plot, not on plots made in for instance the field and drift sections - where the aspect ratio is determined by projection method specified in the AREA statements. For instance, the 3D projection gives isometric plots, while CUT does not.

[This option is initially off, but its setting is remembered from one cell section to the next.]

3.9.4: WIRE-MARKERS

If active, wires will be plotted as markers and not as circles with the size of the wire.

This option, is shared between with the field, optionisation, drift and signal sections.

The type of marker used for a wire depends on the label that you have assigned to the wire in the ROWS listing. Each marker can be adjusted individually via the representations mechanism.

When the option is switched on, the correspodance between labels and REPRESENTATION is as follows:

Label Representation
S S-WIRES
P P-WIRES
C C-WIRES
other OTHER-WIRES

All wires are shown with the representation WIRES when the option is off.

[This option is initially off, but its setting is remembered from one cell section to the next.]

3.9.5: CHARGE-CHECK

Checks the quality of the capacitance matrix inversion.

Only meaningful if the capacitance matrix has indeed been inverted - in the vectorised executables, this is as a rule not done: the numerical quality of the charge calculation is higher if the capacitance equations are solved by other means than matrix inversion.

This option is initially off but its setting is remembered from one cell section to the next.

Section 3.10: PERIODICITY

States that the chamber has infinite periodicity in some direction. Use two of these lines if your chamber is doubly periodic.

Format:

PERIODICITY {X|Y|PHI} = length_of_one_period

Example:

PERIOD X=1

3.10.1: direction

The direction in which the cell is infinitely repeated. Repetition in r is not permitted because of the method used to calculate the potentials in cylindrical geometry.

Cylindrical geometries are handled via a conformal mapping onto a Cartesian coordinate system. An r-periodicity would becomes an x-periodicity with non-constant intervals, which is technically difficult to deal with. Contact the author if there is a need for such a periodicity.

3.10.2: length

The length of one full period in cm for x and y periodicities and in degrees for periodicity in phi.

Section 3.11: PLANE

Specifies an infinite equipotential plane in at constant x, y or phi or a circular plane with constant r.

Note that one is not allowed to put a wire at the centre of a circular plane. In general, wires inside a circular plane, whether at the centre or not, are better dealt with by TUBE geometries.

Format:

PLANE {X|Y|R|PHI} = coordinate ...
      [V = potential] ...
      [LABEL = label]

Examples:

PL X=-1, V=1000
PLANE PHI 30

3.11.1: coordinate

The coordinate at which the plane is located, in cm for X, Y and R and in degrees for PHI.

The r coordinate must be strictly positive (non-zero).

[No default, the coordinate is mandatory.]

3.11.2: potential

Optional indication of the potential in Volt of the plane.

[Default: an earthed plane, at 0 V.]

3.11.3: label

A label by which the plane can be referenced in SELECT statements, for instance when computing signals induced in the plane by moving charges.

The label is a single alphabetic upper case character. You may type a longer string, but only the first character will be stored.

A label is not mandatory, but signals induced in a plane are only computed if the plane can be selected, and this can only be done if the plane has a label.

[By default, no label is assigned to a plane.]

Section 3.12: READ-FIELD-MAP

Reads a binary field map file, written with SAVE-FIELD-MAP.

This command is executed immediately. Once the command has completed, you can use the FIELD-MAP command to modify for instance the selection of drift medium,

READ-FIELD-MAP has the same side effects as FIELD-MAP, i.e. the command deletes any wires, planes, periodicities, dielectric medium and magnetic field that may have been entered before the command is issued.

Reading binary field maps is, for most field map formats, much faster than reading the original files - but binary field maps are not portable. Files to be read with READ-FIELD-MAP must have been written on the same computer system.

Format:

READ-FIELD-MAP   file

Example:

&CELL
cell-id "Micromegas"
Global path=`/afs/cern.ch/exp/compass/scratch/d02/megas/Maxwell/mic3.pjt/`
Call inquire_file(path/`1000_400_0.1.bin`,exist)
If exist Then
   read-field-map {path/`1000_400_0.1.bin`}
Else
   field-map files potential "{path}/V_1000_400_0.1.arg" ...
                   e-field   "{path}/E_1000_400_0.1.arg" ...
             x-periodic y-mirror-periodic
Endif

If a binary field map exists, the map is read. Otherwise the field maps are read in their original format.

Section 3.13: RESET

Resets either fully or selectively the cell data entered so far. A full reset is performed in the absence of arguments.

Format:

RESET [COORDINATES] ...
      [DIELECTRICA] ...
      [DEFINITIONS] ...
      [FIELD-MAP] ...
      [SOLIDS] ...
      [PERIODICITIES] ...
      [PLANES] ...
      [ROWS or WIRES]

Example:

RESET

3.13.1: COORDINATES

Resets the type of coordinate system being used. This should only be needed when switching between Cartesian, polar and tube coordinates.

3.13.2: DEFINITIONS

Resets the definitions entered so far. No mechanism is provided for a selective reset of definitions; consider increasing the global parameter MXVAR in the source if you run out of storage space.

3.13.3: DIELECTRICA

Removes all dielectrica from the cell.

3.13.4: FIELD-MAP

Deletes the field maps. The effect of RESET FIELD-MAP is the same as FIELD-MAP RESET.

3.13.5: SOLIDS

Deletes the solids.

3.13.6: PERIODICITIES

Resets the periodicities entered so far. You have to reset the coordinate system as well if you plan to switch between Cartesian, polar and tube coordinates.

3.13.7: PLANES

Resets the planes entered so far. You have to reset the coordinate system as well if you switch between Cartesian, polar and tube coordinates.

3.13.8: ROWS

Resets the rows of wires entered so far. You have to reset the coordinate system as well if you switch between Cartesian, polar and tube coordinates.

3.13.9: WIRES

Synonym of ROWS, see ROWS.

Section 3.14: ROWS

ROWS is used to enter the wires. The following properties of the wires can be entered at this stage:

The coordinate system in which the wire position is specified can either be Cartesian or polar. The wires in a cell that has a tube, are listed in Cartesian coordinates. Polar coordinates will be assumed if you put the keyword POLAR after ROWS, if you have already entered a plane in polar coordinates and if you have already entered a phi periodicity. Otherwise Cartesian coordinates are assumed. Once a coordinate system has been selected in the cell section, it has to be used throughout the section.

ROWS is a multi-line command because chambers sometimes contain many wires. You may enter one wire per line, but if your cell contains regularly spaced series of wires, you may prefer to enter these as a single "row" in which at least the position, but possibly also the other properties, depends on the so-called loop-variable I which automatically assumes a series of values.

One may use control structures (If_block, If_line, Do_loop, Call) in the listing of wires. Please keep in mind that a blank line must be present to signal the end of the list, whether typed by hand or generated with a loop.

Format of the whole command:

ROWS [CARTESIAN | POLAR | TUBE]
row
...
row
(blank line)

Format of the rows:

label n diameter x_wire y_wire [V_wire [w_wire [l_wire [density]]]]

Examples:

ROWS
s * * 0 0 1000
p * * 0 1 -2000
p * * 0 -1 -2000

This is a very simple example in which 3 wires are entered at (0,0), (0,1) and (0,-1). Defaults are used for the number of wires and the diameter.

ROWS
S * * 0 0 1000
P 2 * -1+i*2 -1+i*2 -2000

This examples shows how the same cell can be entered using the loop variable.

ROWS
Global n=100
For i From 1 To n Do
   Global r=1+2*(i/n)
   Global phi=4*pi*i/n
   If 'i=2*entier(i/2)' Then
       P * * {r*cos(phi), r*sin(phi), -i*10}
   Else
       S * * {r*cos(phi), r*sin(phi), +i*10}
   Endif
Enddo

This, artificial, example illustrates the use of Global variables, the Do_loop and an If_block to generate a spiral. Do not forget the blank line to mark the end of the list of rows !

3.14.1: CARTESIAN

States that the wires will be entered in Cartesian coordinates, (x,y).

This keyword need not be specified if the cell is already established to be in Cartesian coordinates, for instance if a plane at constant x has already been entered. This keyword is not valid if the cell is already established to be in polar or in tube coordinates.

When Cartesian coordinates are used, you may enter planes at constant x and at constant y. Also both x and y periodicities are permitted.

[If no coordinate system has yet been established when ROWS is entered, then Cartesian coordinates are assumed by default.]

3.14.2: POLAR

States that the wires will be entered in polar coordinates (r,phi) with r in cm and phi in degrees. When using polar coordinates, you must ensure that no wire is located at r=0. If you need to describe a cell which has a wire at the centre of a round plane, then TUBE should be used.

When the wires are listed in polar coordinates, the planes have to be entered in polar coordinates too. That is, the planes can be at constant r or at constant phi.

Periodicity in phi is permitted, but radial periodicity isn't.

These coordinates are transformed to an internal coordinates system which is a conformal map of a Cartesian system - but all frequently used instructions transform these internal coordinates back to polar coordinates when outputting the results.

This keyword need not be specified if the cell is already established to be in polar coordinates, for instance if a phi periodicity has already been entered. This keyword is not valid if the cell is already established to be in Cartesian coordinates or in tube coordinates.

[If no coordinate system has been established yet when the ROWS command is entered, then Cartesian coordinates will be assumed by default.]

3.14.3: TUBE

TUBE is a special coordinate system, halfway in between Cartesian and polar. Tubes are used to describe for instance a wire running in the middle of a round plane.

The tube itself and the phi periodicity, if any, is specified in polar coordinates, but the wires are listed in Cartesian coordinates.

Like for polar coordinates, a coordinate transformation is applied to the wire location but the internal coordinates never appear on output.

This keyword need not be specified if the cell is already established to be in tube coordinates because a TUBE statement has already been entered. This keyword is not valid if the cell is already established to be in Cartesian or polar coordinates.

[If no coordinate system has been established yet when the ROWS command is entered, then Cartesian coordinates will be assumed by default.]

3.14.4: label

A single character identifying the wires in the row. You may give more characters but only the first character will be stored.

These labels are used by the SELECT statements to single out (groups of) wires from which particles should drift, for which arrival time distributions are to be computed, on which signals can be recorded, etc.

[Initially, all wires with a label of S are selected for such treatment.]

3.14.5: n

The number of wires in the row, this may be a symbolic expression in terms of DEFINEd variables.

[Default: 1, i.e. a single wire].

3.14.6: diameter

The diameter of the wires in the row.

Since the eletric fields are currently computed in the thin wire approximation, i.e. neglecting dipole and other higher order terms, care has to be taken that the wire diameters are small compared to the inter-wire distances.

One can use the MULTIPOLE-MOMENTS instruction to investigate the need for dipole terms to describe the field around the wire properly,

This may be a symbolic expression in terms of DEFINEd variables and you may use the loop-variable I in the expression if you wish.

[Default: 0.01 cm, i.e. 100 micron].

3.14.7: x_wire

The x- or r-position of the wires in the row, this may be a symbolic expression in terms of DEFINEd variables.

If the cell is described in Cartesian or tube coordinates, then (x,y) coordinates should be used for the wire location. The wire coordinates should be given in (r,phi) format for polar cells.

The loop-variable I can be used to construct symbolic expressions for the locations of the wires in the row. For instance, for a series of wires with coordinates 1, 2, 3 and 4 you could enter the expression 1+I.

[Default: 0 cm.]

3.14.8: y_wire

The y- or phi-position of the wires in the row, this may be a symbolic expression in terms of DEFINEd variables.

If the cell is described in Cartesian or tube coordinates, then (x,y) coordinates should be used for the wire location. The wire coordinates should be given in (r,phi) format for polar cells.

The loop-variable I can be used to construct symbolic expressions for the locations of the wires in the row. For instance, for a series of wires with coordinates 1, 4, 9 and 16 you could enter the expression (I+1)**2.

[Default: 0 cm, phi should be in degrees.]

3.14.9: V_wire

The potential of the wires in the row, this may be a symbolic expression in terms of DEFINEd variables.

The loop-variable I can be used to construct symbolic expressions for the potentials of the wires in the row. For instance, for a series of wires with potentials 1000, 1000, 2000 and 2000, you could enter the expression 1000+entier(i/2)*1000

[Default: 0 cm.]

3.14.10: w_wire

The weight used to stretch the wires.

Used by the FORCES command to estimate the wire displacement under gravitational and electrostatic forces.

[Default: 50 grams.]

3.14.11: l_wire

The length of the wires.

Used by the FORCES command to estimate the wire displacement under gravitational and electrostatic forces.

[Default: 100 cm.]

3.14.12: density

The density of the material of which these wires are made.

Used by the FORCES command to estimate the wire displacement under gravitational and electrostatic forces. Not relevant if the wires are vertical.

For copper-Beryllium wires, one can also enter CU-BE and for gold plated Tungsten one can type TUNGSTEN or W.

[Default: 19.3 g/cm**3, i.e. 20 micron gold plated Tungsten wire]

3.14.13: increments

In earlier versions of the program, rows with a constant spacing in the coordinates and the potential could be constructed using increments (the 7th, 8th and 9th word).

This feature is much less powerful than the alternative method using the loop variable and the increments have therefore been suppressed as of version 5.

3.14.14: loop-variable

The loop-variable is a variable, named I, the program defines for you and that takes on the value 0 for the first wire in the row, 1 for the second and so forth.

This variable may be used for the diameter, the position, the potential, the stretching weight and the length of the wire.

The loop-variables can be used to construct non-standard electrode shapes using wires. Some examples are shown in the description of the wire position and voltage.

Note that the loop variable is not a Global variable: while substitution of expressions in terms of global variables has to be requested explicitely by means of curly brackets, expressions in terms of DEFINEd variables and the loop variable are automatically evaluated. Curly brackets should not be used with such variables.

Section 3.15: SAVE-FIELD-MAP

Performs a binary write of the current field map. Files written by this command can be read by the READ-FIELD-MAP command.

This command is executed immediately, unlike the WRITE command which is only executed when the section is left. The field map must therefore be present (via a FIELD-MAP or a READ-FIELD-MAP) when you issue the SAVE-FIELD-MAP command.

Binary field maps tend to be much smaller than field maps in the original format, and also restoring field maps from binary files is usually much faster. However, binary files are not portable between computer systems.

Format:

SAVE-FIELD-MAP   file

Example:

See READ-FIELD-MAP

Section 3.16: SOLIDS

The SOLIDS command is used to enter solid volumes which are present in the chamber.

Entering these volumes is not mandatory because their presence can in most cases be detected from the dielectric constant in the field map. Entering the solids is useful for the following reasons:

SOLIDS is a multi-line command. Each line after SOLIDS describes one volume. The end of the list is signalled by a blank line.

Only a few shapes are currently provided, other shapes can be added on request - contact the author.

Format:

SOLIDS
{CYLINDER | BOX | SPHERE | HOLE} parameters
...
(blank line)

Example:

solids
For x From -0.02 Step 0.02 To 0.02 Do
   For y From -0.02 Step 0.02 To 0.02 Do
      hole centre {x,y} +0.0110 dir 0 0 1 ...
         half-lengths 0.0100 0.0100 0.0010 ...
         upper-radius 0.0050 lower-radius 0.0050 ...
         conductor
      hole centre {x,y} +0.0050 dir 0 0 1 ...
         half-lengths 0.0100 0.0100 0.0050 ...
         upper-radius 0.0040 lower-radius 0.0020 ...
         dielectric
      hole centre {x,y} -0.0050 dir 0 0 1 ...
         half-lengths 0.0100 0.0100 0.0050 ...
         upper-radius 0.0020 lower-radius 0.0040 ...
         dielectric
      hole centre {x,y} -0.0110 dir 0 0 1 ...
         half-lengths 0.0100 0.0100 0.0010 ...
         upper-radius 0.0050 lower-radius 0.0050 ...
         conductor
   Enddo
Enddo

This represents an array of 9 double-tapered cylindrical holes in a copper clad foil of dielectric material - similar to a GEM foil.

Two holes, on the left with N=2, on the right with N=20. Both are drawn with outlining.

A set of cylinders, partially hiding each other. Each cylinder is drawn with 50 panels, and 20 colour shades are used.

A set of boxes that are intersecting each other. Shown using the default colour density table, with outlining.

A sphere with 50 by 50 panels, shown with a colour table of 50 elements.

3.16.1: CYLINDER

Enters a cylinder. Mandatory parameters are the location of the centre, the radius and the length. The direction defaults to the z-axis.

Format:

CYLINDER  CENTRE cx cy cz ...
          RADIUS r ...
          HALF-LENGTH lz ...
          [DIRECTION dx dy dz] ...
          [material] ...
          [LABEL label] ...
          [ROTATE angle] ...
          [N n]

3.16.1.1: CENTRE

The location of the centre of gravity of the cylinder.

[No default.]

3.16.1.2: RADIUS

The radius of the cylinder.

[No default.]

3.16.1.3: HALF-LENGTH

Half the overall length of the cylinder, as measured along the central axis.

[No default.]

3.16.1.4: DIRECTION

The direction vector of the central axis of the cylinder.

The normalisation of the vector is not used. Zero-norm vectors are not acceptable.

[By default, the central axis is aligned with the z-axis.]

3.16.1.5: material

Specifies whether the cylinder is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations:

Type Representation Notes
CONDUCTOR CONDUCTORS-1 Equivalent to CONDUCTOR-1
CONDUCTOR-1 CONDUCTORS-1 -
CONDUCTOR-2 CONDUCTORS-2 -
CONDUCTOR-3 CONDUCTORS-3 -
DIELECTRICUM DIELECTRICA-1 Equivalent to DIELECTRICUM-1
DIELECTRICUM-1 DIELECTRICA-1 -
DIELECTRICUM-2 DIELECTRICA-2 -
DIELECTRICUM-3 DIELECTRICA-3 -

[Default: CONDUCTOR]

3.16.1.6: label

A one character identification of the solid.

This label serves the same purpose as the wire label for wires, namely the selection of the solid as a place where signals can be measured, around which isochrones are drawn etc.

[Default: C]

3.16.1.7: N

The cylinder is drawn as a polygon with a finite number of panels. N specifies the number of panels on the cylinders outer wall.

N has only an optical effect. The algorithm which determines whether a point is inside or outside a cylinder, assumes a perfect cylinde, and does not take the value of N into account.

[By default, N is chosen in function of the size occupied by the cylinder in the drawing. If you decide to specify N manually, then the same number will be used no matter how large or small the cylinder appears in the drawing.]

3.16.1.8: ROTATE

Specifies a rotation angle of the cylinder in degrees.

Such a rotation is meaningful only if N has been chosen small.

Rotations have only an optical effeft. The algorithm which determines whether a point is inside or outside a cylinder, assumes a perfect cylinder and thus does not take rotations into account.

[Default: 0 degrees]

3.16.2: BOX

Enters a box with right angles. Mandatory parameters are the location of the centre and the dimensions. The direction defaults to the z-axis.

Format:

BOX  CENTRE cx cy cz ...
     HALF-LENGTHS lx ly lz ...
     [DIRECTION dx dy dz] ...
     [material] ...
     [LABEL label]

3.16.2.1: CENTRE

The location of the centre of gravity of the box.

[No default.]

3.16.2.2: HALF-LENGTHS

Half the overall dimensions of the box.

[No default.]

3.16.2.3: DIRECTION

A direction vector that specifies the orientation of the box in space.

The normalisation of the vector is not used. Zero-norm vectors are not acceptable.

[By default, the box is not rotated i.e. the half lengths are assumed to have been measured along x, y and z.]

3.16.2.4: material

Specifies whether the box is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations:

Type Representation Notes
CONDUCTOR CONDUCTORS-1 Equivalent to CONDUCTOR-1
CONDUCTOR-1 CONDUCTORS-1 -
CONDUCTOR-2 CONDUCTORS-2 -
CONDUCTOR-3 CONDUCTORS-3 -
DIELECTRICUM DIELECTRICA-1 Equivalent to DIELECTRICUM-1
DIELECTRICUM-1 DIELECTRICA-1 -
DIELECTRICUM-2 DIELECTRICA-2 -
DIELECTRICUM-3 DIELECTRICA-3 -

[Default: CONDUCTOR]

3.16.2.5: label

A one character identification of the solid.

This label serves the same purpose as the wire label for wires, namely the selection of the solid as a place where signals can be measured, around which isochrones are drawn etc.

[Default: B]

3.16.3: SPHERE

Enters a sphere. Mandatory parameters are the location of the centre and the dimensions. The direction defaults to the z-axis.

Format:

SPHERE  CENTRE cx cy cz ...
        RADIUS r ...
        [material] ...
        [LABEL label] ...
        [N n]

3.16.3.1: CENTRE

The location of the centre of gravity of the sphere.

[No default.]

3.16.3.2: RADIUS

The radius of the sphere.

[No default.]

3.16.3.3: material

Specifies whether the sphere is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations:

Type Representation Notes
CONDUCTOR CONDUCTORS-1 Equivalent to CONDUCTOR-1
CONDUCTOR-1 CONDUCTORS-1 -
CONDUCTOR-2 CONDUCTORS-2 -
CONDUCTOR-3 CONDUCTORS-3 -
DIELECTRICUM DIELECTRICA-1 Equivalent to DIELECTRICUM-1
DIELECTRICUM-1 DIELECTRICA-1 -
DIELECTRICUM-2 DIELECTRICA-2 -
DIELECTRICUM-3 DIELECTRICA-3 -

[Default: CONDUCTOR]

3.16.3.4: N

The sphere is drawn as a a set of parallelograms, much the same way maps are drawn. N specifies the number of meridians and also the number of parallels.

[By default, N is chosen in function of the size occupied by the sphere in the drawing. If you decide to specify N manually, then the same number will be used no matter how large or small the sphere appears in the drawing.]

3.16.3.5: label

A one character identification of the solid.

This label serves the same purpose as the wire label for wires, namely the selection of the solid as a place where signals can be measured, around which isochrones are drawn etc.

[Default: S]

3.16.4: HOLE

Enters an, optionally tapered, cylinderical hole in a box. Mandatory parameters are the location of the centre, the radius or radii and the dimensions of the box. The direction defaults to the z-axis.

Format:

HOLE  CENTRE cx cy cz ...
      RADIUS r | UPPER-RADIUS r_up LOWER-RADIUS r_low ...
      HALF-LENGTHS lx ly lz ...
      [DIRECTION dx dy dz] ...
      [material] ...
      [LABEL label] ...
      [N n]

3.16.4.1: CENTRE

The location of the point that is on the central axis of the hole, half-way between the 2 planes of the box perpendicular to the central axis of the hole.

[No default.]

3.16.4.2: radii

The radius of the hole as measured at the "lower" and at the "upper" surface of the box. If these radii are the same, then only one of them needs to be entered.

[No default.]

3.16.4.3: HALF-LENGTHS

Half the overall dimensions of the box.

[No default.]

3.16.4.4: DIRECTION

The direction vector of the central axis of the hole.

The normalisation of the vector is not used. Zero-norm vectors are not acceptable.

[By default, the central axis is aligned with the z-axis.]

3.16.4.5: material

Specifies whether the box is made of conducting or from dielectric material. To differentiate the solids in drawings, one has the option to choose between various representations:

Type Representation Notes
CONDUCTOR CONDUCTORS-1 Equivalent to CONDUCTOR-1
CONDUCTOR-1 CONDUCTORS-1 -
CONDUCTOR-2 CONDUCTORS-2 -
CONDUCTOR-3 CONDUCTORS-3 -
DIELECTRICUM DIELECTRICA-1 Equivalent to DIELECTRICUM-1
DIELECTRICUM-1 DIELECTRICA-1 -
DIELECTRICUM-2 DIELECTRICA-2 -
DIELECTRICUM-3 DIELECTRICA-3 -

[Default: CONDUCTOR]

3.16.4.6: N

The hole is drawn as a polygon with a finite number of panels. N specifies the number of panels on the hole wall.

By default, N is chosen in function of the size occupied by the box and hole in the drawing. If you decide to specify N manually, then the same number will be used no matter how large or small the box and hole appear in the drawing.

3.16.4.7: label

A one character identification of the solid.

This label serves the same purpose as the wire label for wires, namely the selection of the solid as a place where signals can be measured, around which isochrones are drawn etc.

[Default: H]

Section 3.17: TUBE

A tube is a pipe that surrounds wires. A tube can be round, but can also be triangular, hexagonal etc.

The main difference between a cell described in polar coordinates with a plane at constant r and a tube with radius r, is that one can put a wire at the centre of a tube, but not at the centre of a cell with a circular plane.

The potential for a square tubes is expensive compared to the potential used for a cell with 4 planes.

The coordinate system used when you have a tube is Cartesian.

A tube can be combined with a phi periodicity, but not with other periodicities nor with planes.

Format:

TUBE  [RADIUS r]   [VOLTAGE v]   [EDGES n]   [LABEL label]

Examples:

tube r=2, v=2000
tube hexagonal r=5

In the first example, a circular tube (EDGES is not specified, one could also have added CIRCLE or EDGES=0) is defined with a radius of 2 cm and at a potential of 2000 V. In the second example, the tube is hexagonal and with radius 5 cm. This tube is grounded.

3.17.1: RADIUS

The radius of a circular tube, or the distance between any of the edges and the origin in the case of non-circular tubes.

[No default is provided.]

3.17.2: VOLTAGE

The potential of the tube.

[By default 0 V.]

3.17.3: EDGES

The number of edges, according to the following table:

Shape EDGES Synonyms
Cylinder 0 CIRCLE, CIRCULAR, CYLINDER, CYLINDRICAL
Triangle 3 TRIANGLE, TRIANGULAR
Square 4 SQUARE
Pentagon 5 PENTAGON, PENTAGONAL
Hexagon 6 HEXAGON, HEXAGONAL
Heptagon 7 HEPTAGON, HEPTAGONAL
Octagon 8 OCTAGON, OCTAGONAL

Polygons with a larger number of edges can be made available on request.

3.17.4: label

Serves to identify the tube to SELECT statements.

A label is not mandatory, but signals induced in the tube are only computed if the tube can be selected, and this can only be done if the tube has a label.

[By default, no label is assigned.]

Section 3.18: WRITE

Writes a compact format cell dataset that can be retrieved using GET.

This kind of dataset is not meant ot be human-readable and should not be edited. The format is chosen to enable a fast restore of the data. Also the capacitance matrix and the chargees do not have to be computed anew, thus saving significant computation time if the cell contains a large number of wires.

The writing operation takes place when the section is left, not when the WRITE command is issued. The statement can appear at any place in the cell section.

Compact format cell datasets are written in a machine independent format - files written on one type of computer can be read on other computers.

Field maps are, because of their large size, not saved by the WRITE statement. If reading them with the FIELD-MAP command takes too much time, and if the size of the full field maps is a point of concern, then consider using SAVE-FIELD-MAP and READ-FIELD-MAP, which perform a binary (i.e. non-portable) save and retrieve.

Format:

WRITE DATASET dsname [member] [REMARK remark]

Examples:

WR DATA cell.dat cell1 REM "Some cell"
WR cell.dat cell1 "Some cell"

(These two examples are equivalent, they show that the keywords DATA and REMARK are not needed if the parameters are in the right order.)

3.18.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

3.18.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

3.18.3: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset.

Chapter 4: &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 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. You must therefore enter the magnetic field before entering the gas description.

[Initially, the magnetic field is off.]

Section 4.1: COMPONENTS

Sets the x, y and z components of the magnetic field. The default unit is the rather unconventional 100 Gauss which does however fit in the overall system of units used by Garfield. You may also use Gauss or Tesla if you prefer.

If your cell has been entered in polar coordinates, you should ensure that both the x and the y components are zero. Only the z component may be non-zero in this case.

Format:

COMPONENTS  Bx By Bz  [GAUSS | TESLA]

Examples:

COMP 0 0 50
COMP 0 0 5000 G
COMP 0 0 0.5 T

(All three are equivalent.)

Section 4.2: OPTIONS

There are no local options in this section, but the OPTIONS command can be used for global options, see the top level OPTIONS command.

Section 4.3: SUSCEPTIBILITY

Sets the susceptibility of the gas and the wires. The unit system is irrelevant: only the ratio matters. The default settings are 1 for the wires and 0 for the gas. The magnetic field has no effect if the two susceptibilities are equal.

Format:

SUSCEPTIBILITY susc_wire susc_gas

Example:

SUSC 1 0

Chapter 5: &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 or the magnetic field section since the transport properties of gasses depend on the magnetic field.

Format:

&GAS

Section 5.1: overview

The set of useful instructions in the gas section depends of the origin of the gas data:

A couple of instructions can be used regardless of the origin.

Gas mixture prepared during the run:

Command Short description
ADD Adds/replaces elements of the transport table
CLUSTER Enters the cluster size distribution
EXTRAPOLATIONS Extrapolation of the gas tables
HEED Prepares cluster generation by Heed
INTERPOLATIONS Interpolation method in the gas tables
MAGBOLTZ Magboltz gas mixture (accurate)
MIX Schultz-Gresser gas mixing (approximate)
PARAMETERS Molecular parameters of the gas mixture
PRESSURE Sets the pressure
TEMPERATURE Sets the temperature
WRITE Stores the gas description

User specified gas mixture:

Command Short description
ADD Adds/replaces elements of the transport table
CLUSTER Enters the cluster size distribution
EXTRAPOLATIONS Extrapolation of the gas tables
GAS-IDENTIFIER Adds a label to the gas description
INTERPOLATIONS Interpolation method in the gas tables
PARAMETERS Molecular parameters of the gas mixture
PRESSURE Sets the pressure
RESET Erases gas data entered sofar
TABLE Enters the gas tables
TEMPERATURE Sets the temperature
WRITE Stores the gas description

Built-in gas mixtures with fixed proportions:

Command Short description
ARGON-20-ETHANE-80 Loads the mixture Argon 20 %, ethane 80 %
ARGON-50-ETHANE-50 Loads the mixture Argon 50 %, ethane 50 %
ARGON-80-ETHANE-20 Loads the mixture Argon 80 %, ethane 20 %
ARGON-73-METH-20-PROP-7 Loads Argon 73 %, CH4 20 %, propanol 7 %
CO2 Loads data for almost pure CO2
CO2-80-ETHANE-20 Loads the mixture CO2 80 %, ethane 20 %
CO2-90-ETHANE-10 Loads the mixture CO2 90 %, ethane 10 %
CO2-90-ISOBUTANE-10 Loads the mixture CO2 90 %, isobutane 10 %
ETHANE Loads data for pure ethane
ISOBUTANE Loads data for pure isobutane
METHANE Loads data for pure methane
PRESSURE Sets the pressure

Retrieval of a gas description previously stored:

Command Short description
GET Retrieves gas data from a dataset

General purpose instructions:

Command Short description
OPTIONS Plotting and printing of the gas tables
PLOT-OPTIONS Selects plots, sets ranges and log/lin axes

Section 5.2: built_in

A set of gasses ready for use, supplied by users of the program, usually based on private or published measurements. These descriptions are provided mainly for rapid studies that do not require high accuracy.

Please ensure, with the GAS-PRINT and GAS-PLOT options, that the tables agree with what you think is reasonable.

These mixtures have fixed proportions, use MAGBOLTZ or MIX to obtain tables for arbitrary proportions.

Example:

ARG-50-ETH-50

(Until further notice, the program will use 50 % Argon, 50 % Ethane.)

5.2.1: ARGON-20-ETHANE-80

Loads a mixture of 20 % argon and 80 & ethane.

Source: Drift velocities taken from Jean-Marie et. al. (1979), diffusion from Ramanantsizehena (1979). Mobilitiy and most probable energy loss are questionable. Supplied by Matthias Grosse Perdekamp (Freiburg, Germany)

5.2.2: ARGON-50-ETHANE-50

A mixture of 50 % argon with 50 % ethane.

Source: Supplied by Manfred Guckes (transport properties) and Giorgio Sartori and Michela Giavedoni (Padova, parameters part).

5.2.3: ARGON-80-ETHANE-20

A mixture of 80 % argon with 20 % ethane.

Source: Drift velocities taken from Jean-Marie et al. (1979), diffusion from Ramanantsizehena (1979). Mobility and most probable energy loss are questionable. Supplied by Matthias Grosse Perdekamp (Freiburg, Germany)

5.2.4: ARGON-73-METHANE-20-PROPANOL-7

Loads a mixture of 73 % argon, 20 % methane and 7 % propanol.

Source: Drift velocities and diffusion from F. Piuz Cern-EF 82-11 and Fehlmann et. al. (1983). Clustering parameters with large, unknown errors. Supplied by Matthias Grosse Perdekamp (Freiburg).

5.2.5: CO2

Pure CO2.

Source: Karl Dederichs and Francois Piuz (drift velocity and diffusion) and Francois Rohrbach (multiplication).

5.2.6: CO2-80-ETHANE-20

A mixture of 80 % CO2 with 20 % ethane.

Source: Data supplied by Diego Bettoni.

5.2.7: CO2-90-ETHANE-10

A mixture of 90 % CO2 with 10 % ethane.

Source: Data supplied by Diego Bettoni and Reyad Sawafti.

5.2.8: CO2-90-ISOBUTANE-10

A mixture of 90 % CO2 with 10 % isobutane.

Source: Data supplied Manfred Guckes (transport properties) and Helmut Boettcher (clustering properties).

5.2.9: ETHANE

Pure ethane.

Source: Supplied by Ingo Herbst.

5.2.10: ISOBUTANE

Pure isobutane.

Source: Supplied by Emile Schmoetter. Clustering properties from Helmut Boettcher.

5.2.11: METHANE

Pure methane.

Source: Ingo Herbst, for the drift velocity and the diffusion and from "Basic data of plasma physics, 1966", Sanborn C. Brown.

Section 5.3: ADD

Adds/replaces one or more elements to/of the gas table. This instruction can be used to add for instance the ion mobility to transport tables that have been prepared by Magboltz, but can also be used to override the computed parameters with measured parameters.

The ADD command has 2 formats:

Beware that the WRITE command executes only when the section is left. Therefore, if you modify Magboltz computed gas tables with the ADD command, the modified tables will be written - not the original Magboltz data, no matter where you place the WRITE and ADD statements,

REPLACE is a synonym for ADD.

Format:

ADD  item_1 { function_1 | value_1 VS ep_1 [ORDER order] } ...

Example:

Global pbar = 3
magboltz argon 91 nitrogen 4 methane 5 ...
   e/p-range 0.05 135
Read-vector E_Ar_Ar K_Ar_Ar
   0  1.53
   8  1.53
  10  1.53
  12  1.53
  15  1.52
  20  1.51
  25  1.49
  30  1.47
  40  1.44
  50  1.41
  60  1.38
  80  1.32
 100  1.27
 120  1.22
 150  1.16
 200  1.06
 250  0.99
 300  0.95
 400  0.85
 500  0.78
 600  0.72
 800  0.63
1000  0.56
1200  0.51
1500  0.46
2000  0.40

Global E_Ar_Ar = E_Ar_Ar/(0.010354*300) Global K_Ar_Ar = K_Ar_Ar*1e-6/pbar add ion-mobility K_Ar_Ar vs E_Ar_Ar extrapolation low-ion-mobility constant high-ion-mobility linear

Magboltz is used to generate an electron transport table. This also sets the E/p scale.

Next, a file is read in that contains mobilities as function of E/N for Ar+ ions in Ar at a pressure of 1 atm. The data is taken from the literature, in this case Hornbeck '51 and Beaty '68 (for an extensive compilation consult the H. W. Ellis et al. papers). The E/N values are stored in the matrix E_Ar_Ar, while the mobilities are kept in K_Ar_Ar.

The E/N vector is transformed to E/p. The mobility is divided by the pressure, and its units is changed from cm2/sec.V to cm2/microsec.V.

Finally, the mobility is added to the gas tables using the ADD statement.

References:

[1]
H. W. Ellis, R. Y. Pal and E. W. McDaniel, Transport properties of gaseous ions over a wide energy range, At. Data and Nucl. Data Tables 17 (1976) 177-210.
[2]
H. W. Ellis et al., Transport properties of gaseous ions over a wide energy range, part II, At. Data and Nucl. Data Tables 22 (1978) 179-217.
[3]
H. W. Ellis et al., Transport properties of gaseous ions over a wide energy range, part III, At. Data and Nucl. Data Tables 31 (1984) 113-151.
[4]
J. A. Hornbeck, The drift velocities of molecular and atomic ions in Helium, Neon and Argon, Phys. Rev. 84 (1951) 615-620.
[5]
E. C. Beaty, Proc 5th International conference on ionisation phenomena in gasses, München (1961), Vol 1, p 183, North Holland. Phys. Rev. 170 (1968) 116.

5.3.1: item

Can be any of the following:

Item Explanation Unit
ATTACHMENT-COEFFICIENT Attachment coefficient/pressure 1/cm.Torr
DRIFT-VELOCITY Drift velocity cm/microsec
ION-MOBILITY Ion mobility cm2/microsec.V
LONGITUDINAL-DIFFUSION Longitudinal diffusion * sqrt(p) cm*sqrt(Torr) for 1 cm
LORENTZ-ANGLE Lorentz angle degrees
TOWNSEND-COEFFICIENT Townsend coefficient/pressure 1/cm.Torr
TRANSVERSE-DIFFUSION Transverse diffusion * sqrt(p) cm*sqrt(Torr) for 1 cm

Note that the same scalings have to be applied as for the TABLE.

5.3.2: function

The function may depend on the following variables:

Variable Meaning Unit
ATTACHMENT Attachment coefficient / p 1/cm.Torr
COS_EB Cosine of angle between E and B -
EP Electric field / p V/cm.Torr
LORENTZ Lorentz angle degrees
MOBILITY Ion mobility cm2/microsec.V
SIGMA_L Longitudinal diffusion * sqrt(p) cm*sqrt(Torr) for 1 cm
SIGMA_T Transverse diffusion * sqrt(p) cm*sqrt(Torr) for 1 cm
TOWNSEND Townsend coefficient / p 1/cm.Torr
VELOCITY Electron drift velocity cm/microsec

The variable EP can always be used, COS_EB should only be used in 2-dimensional tables i.e. when Magboltz has prepared the transport tables in the presence of a a magnetic field. The transport properties should be used only insofar as they have been entered already.

5.3.3: VS

If you wish to add experimental data to a table, you should prepare

The E/p vector should in principle cover the entire range of the table. If it doesn't, and if the selected item already exists, then values outside the range of the E/p vector are kept. If the E/p range is too short while the selected item doesn't yet exist, then the replacement is refused. No attempt is made to extrapolate the table.

The E/p values in your measurements do not have to coincide with the E/p values present in the table - your measurements will be interpolated at the values of the table and these interpolations are stored instead of the actual measurements.

5.3.4: ORDER

Selects the degree of polynomial interpolation in the pair of vectors.

When the data is smooth, a value of 2 (quadratic interpolation) is a good choice. This may however lead to intermediate points with a negative value in for instance Townsend coefficient tables that usually start at 0. For such tables, linear interpolation is advised.

Instead of ORDER 1, you may also type LINEAR. QUADRATIC is a synonym for ORDER 2, CUBIC for ORDER 3.

Section 5.4: CLUSTER

Enters the cluster-size distribution. You may choose between entering a parametrisation, listing of all probabilities and a mixture of the two formats.

The cluster size distribution is not by itself enough to generate clusters along a track. The clustering model based on the distribution entered here, also need to know the cluster spacing, which can be set with the MEAN keyword of the PARAMETERS command.

If you use the HEED interface, then you probably neither need to enter a cluster size distribution nor the cluster spacing. Entering a cluster size distribution and initialising Heed is however allowed. It is only at the TRACK level that you decide which clustering model you are going to use.

5.4.1: Parametrisation

Format:

CLUSTER FUNCTION cluster_function [N nmax]

Where the cluster_function is a function of the symbolic parameter N which should return the probability that any given cluster is of size N. This function will be evaluated from N=0 to N=nmax [default is 20]. You don't have to worry about the normalisation.

Example:

CLUSTER function exp(-((n-10)/5)**2) N 15

5.4.2: Listing

Format:

CLUSTER
prob_size0 prob_size1
...
(blank line)

The probabilities for having the various sizes are to be listed over one or more lines following the CLUSTER statement. Note the blank line which delimits the list. You don't have to worry about the normalisation.

Example:

CLUSTER
0 0 0.1 0.2 0.5
0.2 0.1 0

(Note the blank line)

5.4.3: Mixed

Format:

CLUSTER FUNCTION cluster_function [N nmax] OVERLAP-TABLE-AND-FUNCTION
prob_size0 prob_size1
...
(blank line)

This format is to be used if you wish to enter, for small values of n, a measured cluster size distribution and for the larger values of n an asympototic expression.

Example:

CLUSTER FUNCTION 21.6/N**2 N=200 OVERLAP
0 86 20 10

There has to be a blank line after the cluster sizes. One can also simulate this format by using a Do_loop:

cluster
0 86 20 10
For i From 4 To 200 Do
{21.6/i**2}
Enddo

But this would be less efficient since the formula inside the loop (21.6/i**2) is translated each iteration of the loop. Note that there has to be a blank line after Enddo.

Section 5.5: EXTRAPOLATIONS

Indicates how the gas-tables have to be extrapolated to E/p values smaller and larger than those present in the table.

The EXTRAPOLATIONS command has no effect on extrapolation in 2-dimensional tables, such as those produced by Magboltz when the B field is non-zero. For such tables, polynomial extrapolation is performed with the order set with the INTERPOLATIONS command.

Format:

EXTRAPOLATIONS item1 method1 item2 method2 ...

Examples:

EXTR DRIFT: LINEAR, DIFF: CONST, TOWN: CONST
EXTR DRIFT EXP

5.5.1: item

The table item to be extrapolated, the following are known:

Item Description
[HIGH-]DRIFT-VELOCITY Drift velocity beyond the highest E/p
LOW-DRIFT-VELOCITY Drift velocity below the first E/p
[HIGH-]ION-MOBILITY Ion mobility beyond the highest E/p
LOW-ION-MOBILITY Ion mobility below the first E/p
[HIGH-]LORENTZ-ANGLE Lorentz angle beyond the highest E/p
LOW-LORENTZ-ANGLE Lorentz angle below the first E/p
[HIGH-]LONGITUDINAL-DIFFUSION Long. diffusion beyond the highest E/p
LOW-LONGITUDINAL-DIFFUSION Long. diffusion below the first E/p
[HIGH-]TRANSVERSE-DIFFUSION Transv. diffusion beyond the highest E/p
LOW-TRANSVERSE-DIFFUSION Transv. diffusion below the first E/p
[HIGH-]TOWNSEND-COEFFICIENT Townsend coefficient beyond highest E/p
LOW-TOWNSEND-COEFFICIENT Townsend coefficient below first E/p
[HIGH-]ATTACHMENT-COEFFICIENT Attachment coefficient beyond highest E/p
LOW-ATTACHMENT-COEFFICIENT Attachment coefficient below first E/p

The prefix HIGH- is optional for backwards compatibility. DIFFUSION can be used instead of LONGITUDINAL-DIFFUSION.

5.5.2: method

The extrapolation method to be used: CONSTANT, EXPONENTIAL or LINEAR.

Constant extrapolation means values for any E/p outside the range of the table are set to the value for the first or last E/p in the table, as appropriate.

In the case of linear and exponential extrapolation the first or last two table points are used as basis for the extrapolation.

Section 5.6: GAS-IDENTIFIER

Assigns an identification string to the gas. This string is placed on plots when gas data has been used to make the plot.

Format:

GAS-IDENTIFIER string

Example:

GAS-ID "Some gas"

Section 5.7: GET

Retrieves a compact format gas description written by WRITE. This command clears gas information you may have entered already. It is executed immediately and you may, with caution, replace some of the elements of the description after issuing the command.

The compact gas description contains electron transport property tables, the ion mobility, cluster size and cluster spacing data, Heed initialisation information, the pressure and the temperature. GET overwrites all of these.

Format:

GET dsname [member]

Example:

GET gas_data.dat gas2

5.7.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

5.7.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

Section 5.8: HEED

Invokes the gas definition part of the Heed program, which simulates the energy loss through ionisation of a particle that traverses the gas. This initialisation, which is very fast, is mandatory if you intend to use the HEED clustering model of the TRACK command. Heed initialisation is performed automatically when reloading (GET) a gas for which an Heed initialisation has been performed.

The temperature and the pressure should be specified before issuing the HEED command. See TEMPERATURE and PRESSURE for default settings.

Neither temperature nor pressure scaling is applied to the cluster information provided by HEED.

The author of Heed, Igor Smirnov, should be contacted for further information about this program.

Format:

HEED  [ ARGON  fraction ]      [ HELIUM-4  fraction ] ...
      [ NEON  fraction ]       [ XENON  fraction ] ...
      [ KRYPTON  fraction ]    [ METHANE   fraction ] ...
      [ ETHANE  fraction ]     [ ETHENE  fraction ] ...
      [ ACETYLENE  fraction ]  [ ISOBUTANE  fraction ] ...
      [ PROPANE  fraction ]    [ NEOPENTANE  fraction ] ...
      [ HYDROGEN  fraction ]   [ NITROGEN  fraction ] ...
      [ WATER  fraction ]      [ CO2  fraction ] ...
      [ CF4  fraction ]        [ OXYGEN  fraction ] ...
      [ DME  fraction ]        [ NITROUS-OXIDE  fraction ] ...
      [ AMMONIA  fraction ]

Example:

pressure {3*760}
Heed argon 50 ethane 50

(If you have a 3 atm 50/50 Argon-ethane mixture in your chamber.)

Section 5.9: INTERPOLATIONS

The gas tables are usually interpolated with cubic splines. Sometimes splines oscillate too much and then you may prefer to use polynomial interpolation instead.

Format:

INTERPOLATIONS item1 method1 item2 method2 ...

Examples:

INTERP DRIFT-VELOCITY NEWTON 2,  LONG-DIFFUSION NEWTON 1
INT TOWNSEND SPLINE

5.9.1: item

The table item for which you wish to alter the interpolation method.

Keyword Meaning
ATTACHMENT-COEFFICIENT Attachment coefficient of electrons
DRIFT-VELOCITY Electron drift velocity
ION-MOBILITY Mobility of ions
LONGITUDINAL-DIFFUSION Longitudinal diffusion of electrons
LORENTZ-ANGLE Lorentz angle of electrons
TOWNSEND-COEFFICIENT Townsend coefficient of electrons
TRANSVERSE-DIFFUSION Transverse diffusion of electrons

5.9.2: method

The interpolation method to be used. The basic choice is between cubic splines and polynomial Newton interpolation.

Spline interpolation leads to smooth looking graphs, but tends to oscillate making the method less suited for numerical calculations. Spline interpolation can not be used on the 2-dimensional gas tables that are produced by programs like Magboltz when a magnetic field is present.

The order of polynomial interpolation must be between 1 and the smallest of the two numbers: 10 and number of table entries - 1. Orders larger than 2 are not recommended.

Formats:

INTERPOLATIONS item SPLINES
INTERPOLATIONS item NEWTON order

Method Effect Use
SPLINES Cubic spline interpolation only 1-D
NEWTON n Polynomial interpolation of order n 1-D or 2-D
LINEAR Linear interpolation (= NEWTON 1) 1-D or 2-D
QUADRATIC Parabolic interpolation (=NEWTON 2) 1-D or 2-D
CUBIC Cubic interpolation (=NEWTON 3) 1-D or 2-D

Section 5.10: MAGBOLTZ

Invokes the Magboltz program to compute for electrons, the drift velocity, the longitudinal and transverse diffusion coefficients, the Townsend and attachment coefficients and the Lorentz angles if there is a magnetic field.

Since Magboltz takes the magnetic field into account to compute the transport properties, the &MAGNETIC section should precede the gas section.

Likewise, TEMPERATURE and PRESSURE statements should be issued before invoking Magboltz. If the temperature has not been specified when Magboltz runs, then a default temperature of 300 K will be assumed. No scaling will be applied if the temperature is changed later on. The default pressure is 760 Torr. The transport properties will be scaled according to simple scaling laws if the pressure is modified after the transport properties have been computed. It is not recommended, however, to rely on these scaling laws since these are very approximate.

The author of Magboltz, Steve Biagi, should be contacted for further information about this program.

Format:

MAGBOLTZ [ ARGON  frac ]            [ HELIUM-3  frac ] ...
         [ HELIUM-4  frac ]         [ NEON  frac ] ...
         [ XENON  frac ]            [ KRYPTON  frac ] ...
         [ METHANE  frac ]          [ ETHANE  frac ] ...
         [ ETHENE  frac ]           [ ACETYLENE  frac ] ...
         [ NITROGEN-A  frac ]       [ NITROGEN-B  frac ] ...
         [ AMMONIA  frac ]          [ OXYGEN  frac ] ...
         [ ISOBUTANE  frac ]        [ WATER  frac ] ...
         [ CO2  frac ]              [ METHYLAL-HOT  frac ] ...
         [ METHYLAL-COLD  frac ]    [ PROPANE  frac ] ...
         [ NEOPENTANE frac ]        [ CF4  frac ] ...
         [ DME  frac ]              [ NITRIC-OXIDE  frac ] ...
         [ NITROUS-OXIDE  frac ] ...

[ E/P-RANGE epmin epmax ] [ N-E/P nep ] ... [ LINEAR-E/P-SCALE | LOGARITHMIC-E/P-SCALE ] ... [ ANGLE-RANGE amin amax ] [ N-ANGLE nangle ] ... [ NOPLOT-DISTRIBUTION-FUNCTIONS | ... PLOT-DISTRIBUTION-FUNCTIONS ] ...

[ SECOND-ORDER-TERMS | FIRST-ORDER-TERMS | ORDERS n ] ... [ NOITERATE-ALPHA | ITERATE-ALPHA ] ... [ SWITCH [alpha/pressure] | NOSWITCH ] ... [ F0-TRANSVERSE-DIFFUSION | H1-TRANSVERSE-DIFFUSION | ... MEAN-ENERGY-TRANSVERSE-DIFFUSION ] ... [ F0-LONGITUDINAL-DIFFUSION | H1-LONGITUDINAL-DIFFUSION | ... G0-LONGITUDINAL-DIFFUSION ] ...

[ MOBILITY mob ]

Example:

magboltz argon 50 ethane 50

(The gas in your chamber will be 50 % Argon and 50 % Ethane.)

5.10.1: frac

The fraction of the gas mixture taken up by a component.

The sum of the fractions is normalised - in the examples, fractions usually add up to 1 or to 100, but this is not mandatory.

[Each fraction is 0 by default.]

5.10.2: E/P-RANGE

The range in E/p for which gas tables should be prepared.

The electric field E is expressed in V/cm, p in Torr.

[By default 10/p to 100000/p.]

5.10.3: N-E/P

Number of E/p points in the gas tables.

[By default 20.]

5.10.4: scale

Selects whether the spacing of the E/p points should be linear or logarithmical.

[Logarithmic by default.]

5.10.5: ANGLE-RANGE

Electron transport properties in the presence of a magnetic field depend not only on the magnetic field strength but also on the angle between the electric and the magnetic field.

Magboltz will, if B is non-zero, by default be asked to compute tables of the transport properties for a 2-dimensional grid of E/p vs the angle between E and B. The density and range of the grid along the E/p axis is set with N-E/P and E/P-RANGE, while the density and range along the angles is set with N-ANGLE and ANGLE-RANGE.

If your chamber is such that E is always perpendicular to B, then it is advisable to centre the ANGLE-RANGE on 90 degrees, e.g. [80,100], and set N-ANGLE to 1. This will generate a 1-dimensional table for which you have greater control over the INTERPOLATIONS and EXTRAPOLATIONS methods.

If E is not perpendicular to B, then it may in rare cases be sufficient to compute the transport parameters for a limited range of the angle between E and B. Since the dependence on the angle tends to be smooth, this practice is not recommended.

This parameter is meaningful only if there is a magnetic field.

[The default range is 0 to 180 degrees.]

5.10.6: N-ANGLE

See ANGLE-RANGE for further information.

Sets the number of angles between the E and B field for which Magboltz will compute an electron transport table.

A setting of 1 forces the table to be 1-dimensional even if there is a magnetic field. This is useful if E and B are perpendicular everywhere in the chamber. Settings other than 1 and the default are not recommended.

[By default: 7.]

5.10.7: PLOT-DISTRIBUTION-FUNCTIONS

Requests for each E, and if applicable each B and E-B orientation, of the electron distribution functions F0, F1, F2 and F3. Such plots are useful to understand the behaviour of the drift velocity, which is dominated by the first anisotropic term F1 and the diffusion, which depends mostly on the isotropic term F0.

Keep in mind that Magboltz only computes F2 and F3 on request: to get F2 and F3 you need to request SECOND-ORDER-TERMS (or ORDERS 2) and for a reasonably accurate F3 you should specify ORDERS 3. Both are incompatible with the option ITERATE-ALPHA which enables a more precise computation of the Townsend coefficient.

F0 is plotted with representation FUNCTION-1, F1 as FUNCTION-2, F2 as FUNCTION-3 and F3 as FUNCTION-4.

This option potentially generates a lot of output.

The option is off by default.

5.10.8: ORDERS

Can be used to set the number of terms to be included in energy distribution function, to ensure higher accuracy for the transport properties.

Values larger than 1 are not compatible with ITERATE-ALPHA, this setting is overruled by the SWITCH option.

[Default: n=2, equivalent to SECOND-ORDER-TERMS.]

5.10.9: SECOND-ORDER-TERMS

Requests inclusion of zeroth, first and second order terms in the calculation of the energy distribution function. Selecting this option ensures a higher accuracy for the transport properties, but is not compatible with the ITERATE-ALPHA option which improves the accuracy of the Townsend coefficients.

SWITCH overrules this selection.

HIGH-PRECISION is synonymous to SECOND-ORDER-TERMS.

[This is the default order, but is overruled by SWITCH.]

5.10.10: FIRST-ORDER-TERMS

Only the zeroth and first order terms will be included in the energy distribution function. This setting guarantees a reasonable accuracy and is compatible with the ITERATE-ALPHA option which improves the accuracy of the Townsend coefficients.

LOW-PRECISION is synonymous to FIRST-ORDER-TERMS.

[The default is SECOND-ORDER-TERMS.]

5.10.11: ITERATE-ALPHA

This option enables a refinement of the calculation of the Townsend coefficient. This is particularly useful if the Townsend coefficients are large (larger than say 50). But the option is not compatible with inclusion of higher order terms.

[This is not default.]

5.10.12: SWITCH

The SWITCH option combines ITERATE-ALPHA and SECOND-ORDER-TERMS in the following way:

If alpha/pressure is smaller than the threshold, the quantities are computed with SECOND-ORDER-TERMS, NOITERATE-ALPHA

Otherwise, they are computed with FIRST-ORDER-TERMS, ITERATE-ALPHA.

This guarantees that the drift velocity, diffusion and Lorentz angle are accurate at low field values, which is where they matter most, whereas the Townsend coefficient is accurate at higher field values, at the price of a somewhat reduced accuracy for the other quantities.

[This option is default, alpha/pressure is set to 50/pressure.]

5.10.13: DIFFUSION

Magboltz offers several ways of computing the diffusion:

5.10.14: MOBILITY

Magboltz only computes the electron transport properties in gasses. This keyword enables adding an ion mobility to the tables.

This format only allows for mobilities that are constant or depend in a simple way on E/p. In the latter case, the argument of MOBILITY should be a function with EP as variable.

ADD provides a similar functionality, and can in addition be used if the mobility is available in tabular form.

The unit of mobility in Garfield is cm2/microsec.V.

[By default: no mobility.]

Section 5.11: MIX

Computes the drift velocity and diffusion for a mixture of gasses. The calculations are based on the work of G. Schultz and J. Gresser NIM 151 (1978) 413-431 and use parametrised cross section and energy loss data provided by Fabio Sauli and Anna Peisert.

The main limitation of this method is that it neglects ionisation effects and that it treats excitation inaccurately. This implies that the results are not valid for large E/p values, i.e. close to the wires.

Another limitation is that these calculations neglect the magnetic field - this is not an inherent limitation of the method, but there is no intention to invest further effort in this instruction. Garfield nowadays has an interface to the Magboltz program of Steve Biagi which is superior in accuracy to this instruction. See MAGBOLTZ.

Format:

MIX [ ARGON  frac ]          [ HELIUM  frac ] ...
    [ METHANE  frac ]        [ ETHANE  frac ] ...
    [ NEON  frac ]           [ NITROGEN  frac ] ...
    [ ISOBUTANE  frac ]      [ XENON  frac ] ...
    [ CO2  frac ]            [ METHYLAL  frac ] ...
    [ KRYPTON  frac ]        [ AMMONIA  frac ] ...

[ MINIMUM-ENERGY emin ] ... [ MAXIMUM-ENERGY emax ] ... [ STEPSIZE-ENERGY estep ] ...

[ CRITICAL-F0-FRACTION frcrit ] ...

[ E/P-RANGE epmin epmax ] ... [ N-E/P n ] ... [ LINEAR-E/P-SCALE | LOGARITHMIC-E/P-SCALE ] ...

[ PLOT-F0 | NOPLOT-F0 ] ... [ PLOT-ENERGY-LOSS | NOPLOT-ENERGY-LOSS ] ... [ PLOT-CROSS-SECTION | NOPLOT-CROSS-SECTION ] ... [ PLOT-PATH | NOPLOT-PATH ] ...

[ PRINT-TABLES | NOPRINT-TABLES ] ...

[ MOBILITY mob ] ... [ TOWNSEND-COEFFICIENT alpha/p ] ... [ ATTACHMENT-COEFFICIENT beta/p ]

Example:

mix argon 50 ethane 50

The gas in your chamber will be 50 % Argon and 50 % Ethane.

5.11.1: frac

The fraction of the mixture taken up by the gas.

The fractions do not necessarily have to add up to 1.

[Each fraction is 0 by default.]

5.11.2: emin

The lowest electron energy in the cross section, energy loss, mean free path and F0 plots. This parameter has no impact on the drift velocity and diffusion calculations.

[By default 0.01 eV.]

5.11.3: emax

The largest electron energy which is considered during the computations of F0, the drift velocity and the diffusion. This is also the largest electron energy shown in the cross section, energy loss, mean free path and F0 plots.

This parameter should be chosen sufficiently large, otherwise the program might not be able to detect ionisation. The adverse effect of choosing this parameter too large is an increased CPU time consumption.

[By default 25 eV.]

5.11.4: estep

The largest step size allowed during integration. One should keep in mind that integration in each step is done using a 6-point Gauss technique and that the steps never bridge a change-over between two parametrisations.

[By default 0.5 eV.]

5.11.5: frcrit

Garfield warns if the fraction of F0 fraction above the first ionisation potential of any of the gas components exceeds the value of this parameter.

[By default 0.01.]

5.11.6: E/P-RANGE

The range of E/p. There is usually no problem with the computations for small E/p, but at high E/p one may hit the ionisation potential of one of the gas components.

[By default 0.5 to 50.]

5.11.7: N-E/P

Number of points in the drift velocity and diffusion tables.

[By default 20.]

5.11.8: scale

Selects whether the spacing of the E/p points should be linear or logarithmical.

[Logarithmic by default.]

5.11.9: PLOT-F0

Requests a plot of F0 for each E/p. This plot is useful when you wish to see which electron energies play a role.

The curve is plotted using polyline representation FUNCTION-1 if ionisation and excitation are not expected to be a problem, using representation FUNCTION-2 if a significant fraction of the energy distribution exceeds the first ionisation or excitation threshold.

[This plot is made by default.]

5.11.10: PLOT-ENERGY-LOSS

Requests a plot of the fraction of energy lost by an electron during collisions with the gas molecules / atoms.

The curve is plotted using polyline representation FUNCTION-1.

[This plot is by default not made.]

5.11.11: PLOT-CROSS-SECTION

Requests a plot of the elastic electron scattering cross section.

The curve is plotted using polyline representation FUNCTION-1.

[This plot is made by default.]

5.11.12: PLOT-PATH

Requests a plot of the mean free path of electrons in the gas.

The curve is plotted using polyline representation FUNCTION-1.

[This plot is by default not made.]

5.11.13: PRINT-TABLES

Requests that the information contained in the 3 kinds of plots described before (energy loss, cross section, mean free path) be printed.

[This table is by default not printed.]

5.11.14: MOBILITY

MIX only computes the drift velocity and longitudinal diffusion for electrons, not for ions. This keyword enables adding an ion mobility to the tables.

This format only allows for mobilities that are constant or depend in a simple way on E/p. In the latter case, the argument of MOBILITY should be a function with EP as variable.

ADD provides similar functionality, and caters in addition for mobilities that are available in tabular form.

The Garfield unit for mobility is cm2/V.microsec.

[By default: no mobility.]

5.11.15: TOWNSEND-COEFFICIENT

MIX only computes only drift velocity and the longitudinal diffusion for electrons in the gas mixture. It does not compute the Townsend or attachment coefficient. This keyword enables adding the Townsend coefficient to the tables.

This format only allows for Townsend coefficients that depend in a simple way on E/p. The argument of TOWNSEND-COEFFICIENT should be a function with EP as variable. ADD is more flexible in that it provides similar functionality, but it caters in addition for Townsend coefficients that are available in tabular form.

Note that MAGBOLTZ can be used to compute Townsend coefficients.

The Townsend coefficient should be entered as alpha/pressure, with alpha in units 1/cm and the pressure in Torr.

[By default: no Townsend coefficient.]

5.11.16: ATTACHMENT-COEFFICIENT

MIX only computes only drift velocity and the longitudinal diffusion for electrons in the gas mixture. It does not compute the Townsend or attachment coefficient. This keyword enables adding the attachment coefficient to the tables.

This format only allows for attachment coefficients that depend in a simple way on E/p. The argument of ATTACHMENT-COEFFICIENT should be a function with EP as variable. ADD is more flexible in that it provides similar functionality, but it caters in addition for attachment coefficients that are available in tabular form.

Note that MAGBOLTZ can be used to compute attachment coefficients.

The attachment coefficient should be entered as eta/pressure, with eta in units 1/cm and the pressure in Torr.

[By default: no attachment coefficient.]

Section 5.12: OPTIONS

Enters global and local options. Only the local options are listed here. For global options, see the top level OPTIONS command.

Format:

OPTIONS [NOGAS-PLOT | GAS-PLOT] ...
        [NOGAS-PRINT | GAS-PRINT]

Example:

OPT NOG-PL G-PR

5.12.1: GAS-PRINT

This option is responsible for making a printout of all available data about the gas. This enables you for instance to get a listing of the predefined gasses like Argon-Ethane or CO2.

The output can not be used directly as input to the program, use the WRITE instruction for that purpose.

The tables are only printed when the gas section is being left.

[This option is off initially, its setting is remembered from one gas section to the next.]

5.12.2: GAS-PLOT

Switching on this option causes plots of the drift velocity, the diffusion coefficients, the ion mobility, the Lorentz angle, the Townsend coefficient and the attachment coefficient to be produced when the gas section is left.

With the PLOT-OPTIONS command, you have further control over the axes (linear or logarithmic) and the vertical scale of these plots. This command also enables you to suppress one or more of the plots.

[This option is off initially, its setting is remembered from one gas section to the next.]

Section 5.13: PARAMETERS

Various parameters of the gas, such as the number of clusters per cm, are entered with this command.

The mean number of clusters is used if the clustering model you plan to choose with the TRACK command, is based on the cluster size distribution entered with CLUSTER.

The rest of the data is only used for a simple backup estimate of the cluster size distribution if neither a CLUSTER nor a HEED statement has been issued.

Format:

PARAMETERS [A a] [Z z] [RHO density] [E-PAIR epair] ...
           [E-MOST-PROBABLE emprob] ...
           [MEAN mean_number_of_clusters] ...
           [TRANSVERSE-ION-DIFFUSION sigma_T] ...
           [LONGITUDINAL-ION-DIFFUSION sigma_L]

As shown in the format description, several lines may be used although a single line is perfectly acceptable as well.

Example:

PARA MEAN 20

This format could be used if you wish to compute arrival time spectra and enter the cluster size distribution with CLUSTER.

5.13.1: A

The number of nucleons per molecule.

This parameter is used only to compute the cluster size distribution if you didn't enter such a distribution yourself with CLUSTER nor asked HEED to simulate the ionisation process.

5.13.2: E-MOST-PROBABLE

The most probable, not the mean, energy loss in eV per cm.

This parameter is used only to compute the cluster size distribution if you didn't enter such a distribution yourself with CLUSTER nor asked HEED to simulate the ionisation process.

You may also type MOST-PROBABLE-ENERGY-LOSS.

5.13.3: E-PAIR

The energy in eV needed to ionise a molecule.

This parameter is used only to compute the cluster size distribution if you didn't enter such a distribution yourself with CLUSTER nor asked HEED to simulate the ionisation process.

You may also type PAIR-CREATION-ENERGY.

5.13.4: MEAN

The average number of clusters per cm.

This parameter is not used when clustering is performed by HEED, but is otherwise required for numerous calculations, such as arrival time distributions and signal simulations.

This parameter is required even if a cluster size distribution has been entered with a CLUSTER statement.

You may also type N-MEAN.

5.13.5: RHO

The density of the gas in g/cm**3.

This parameter is used only to compute the cluster size distribution if you didn't enter such a distribution yourself with CLUSTER nor asked HEED to simulate the ionisation process.

5.13.6: Z

The nuclear charge of the molecule.

This parameter is used only to compute the cluster size distribution if you didn't enter such a distribution yourself with CLUSTER nor asked HEED to simulate the ionisation process.

5.13.7: sigma

The transverse and longitudinal diffusion coefficients for ions of the type expected to be produced in your chamber, filled with the gas being entered.

These coefficients are used for Monte Carlo drift line integration of ion trajectories.

The diffusion coefficients should be expressed in cm of diffusion over 1 cm of drift.

[Both diffusion coefficients default to 0.]

Section 5.14: PLOT-OPTIONS

Selects the plots to be made in response to the GAS-PLOT option, when leaving the gas section. The PLOT-OPTIONS command also controls the range of the vertical axes of these plots and lets you choose linear or logarithmic scales for both axes.

Several plots may be modified in a single statement.

Use DRIFT_VELOCITY and related procedures to have full control over the presentation of the plot.

Format:

PLOT-OPTIONS [plot [options]] ...

Example:

plot-options drift lin-x log-y nodiff nocluster

(Requests a linear E/p axis and a logarithmic drift velocity axis, the opposite of the default. The diffusion coefficients and the cluster size distribution are not plotted.)

5.14.1: plot

Selects the plot of which you wish to modify the options.

The following are known, all of which can be negated to suppress the plot:

Plot Contains
CLUSTER-SIZE-PLOT Cluster size distribution
DIFFUSION-COEFFICIENTS-PLOT Transverse + longitudinal diffusion
DRIFT-VELOCITY-PLOT Drift velocity of electrons
ION-MOBILITY-PLOT Ion mobility
LORENTZ-ANGLES-PLOT Lorentz angles for electrons
TOWNSEND-COEFFICIENT-PLOT Townsend and attachment coefficients

Notes:

  1. The transverse longitudinal diffusion are shown in a single graph. To suppress one of them but not the other requires a RESET of the item that is not desired. The same applies to the Townsend and attachment coefficients.
  2. One may use ATTACHMENT-COEFFICIENT-PLOT as synonym for TOWNSEND-COEFFICIENT-PLOT.

5.14.2: options

The plot can be followed by one or more of the following options:

Option Effect
LINEAR-X Linear scale for the horizontal axes
LINEAR-Y Linear scale for the vertical axes
LOGARITHMIC-X Log scale for the horizontal axes
LOGARITHMIC-Y Log scale for the vertical axes
RANGE ymin ymax y Will range from ymin to ymax

Notes:

  1. The transverse and longitudinal diffusion coefficients, as well as the Townsend and attachment coefficients are plotted in the same graph and have therefore a common set of axes.
  2. RANGE does not apply to the cluster size distribution.

Section 5.15: PRESSURE

Sets the pressure of the gas.

The pressure is used by the gas mixing instructions (MIX and MAGBOLTZ) and also by HEED. Please be sure to specify the pressure before issuing these commands.

If you specify the pressure after a mixing command, then the tables will be prepared for standard atmospheric pressure and the conversion to the pressure you specify will be done by relying on the simple scaling laws.

Format:

PRESSURE pressure [unit]

Example:

pressure 2 bar

5.15.1: pressure

The pressure of the gas.

[Initially set to 760 Torr.]

5.15.2: unit

Various common pressure units and their abbreviations are accepted:

Unit Equivalent of 1 atm Notations
atmosphere 1 atm ATMOSPHERE
mm Hg 760 mm Hg MM-HG
Torricelli 760 Torr TORRICELLI
inch Hg 29.9213 inch Hg INCH-HG
Pa 101325 Pa PASCAL, HECTO-PASCAL, HPA
N/m2 101325 N/m2 N/M2
bar 1.01325 bar BAR
mbar 1013.25 hPa MBAR, MILLI-BAR

The default pressure input unit is the Torr. Pressures are shown either in Torr or in atmosphere. The choice of output unit is not influenced by the unit used for input.

Section 5.16: REPLACE

REPLACE is a synomym of ADD.

Section 5.17: RESET

Performs a reset of all gas-data entered so far. This instruction is only available in interactive mode.

Format:

RESET

Section 5.18: TABLE

Enters the tables of electron transport properties and of the ion mobility, as function of E/p.

Each of the table entries (drift velocity, ion mobility, Lorentz angle, diffusion coefficients, Townsend and attachment coefficients) can either be tabulated after the TABLE line, or be given as a parametrisation on the TABLE line.

All tabulated entries must be specified at a common set of E/p values, which must itself be listed in the table if at least one transport property is tabulated. Use ADD if the data that you wish to use for one or more entries, is tabulated at a different set of E/p values.

The order of the tabulated entries, is indicated on the TABLE line by listing the names of the entries (such as DRIFT-VELOCITY) in the same sequence as in the table. The entry names should not be followed by parametrisations. The place of the E/p values should be indicated by 'E/P'. There is no prefered order of the entries.

The entries are interpolated, and if necessary extrapolated, using methods that can be set with the INTERPOLATIONS and EXTRAPOLATIONS statements.

Parametrisations should be functions of the symbolic parameter EP, which equals E/p. They should be entered by placing the name of the entry (e.g. LORENTZ-ANGLE) before the function.

The parametrisations that you enter are not stored as functions, rather they are evaluated at the E/p values in the table and the list thus obtained will be interpolated when transport properties are required, like for tabulated entries.

If all entries are entered in parametrised form, then you can either establish the list of E/p values by tabulating them after the TABLE statement, or use the RANGE and N keywords. These keywords are ignored if at least one entry is tabulated.

Quantities that obey simple pressure scaling laws, have to be entered multiplied by the appropriate power of the pressure.

Format:

TABLE [E/P] ...
      [DRIFT-VELOCITY [drift]] ...
      [ION-MOBILITY [mobility]] ...
      [LORENTZ-ANGLE [angle]] ...
      [LONGITUDINAL-DIFFUSION-COEFFICIENT [diff]] ...
      [TRANSVERSE-DIFFUSION-COEFFICIENT [diff]] ...
      [TOWNSEND-COEFFICIENT [townsend]] ...
      [ATTACHMENT-COEFFICIENT [attach]] ...
      [DUMMY [dummy]] ...
      [RANGE epmin epmax] [N nmax]

This line is followed by tables for those items that are not functions. The end of the table is signalled by a blank line.

Example:

TABLE  DRIFT=100*EP, DIFF, E/P
0.3 0.1
0.1 0.2
0.1 0.5
0.2 1.0
0.3 2.0

(The drift velocity is entered as the function 100*E/p which is evaluated at the E/p values listed in the second column. The longitudinal diffusion is listed in the first column. The ion mobility, the Lorentz angle and the Townsend and attachment coefficients are not specified. Note the blank line at the end of the table.)

5.18.1: units

The units to be used for the various quantities are:

Item Unit
Attachment coefficient 1/cm
Drift velocity cm/microsec
Ion mobility cm2/microsec.V
Longitudinal diffusion cm for 1 cm of drift
Lorentz angle degrees
Townsend coefficient 1/cm
Transverse diffusion cm for 1 cm of drift

5.18.2: scaling

The simple scaling laws used by Garfield to extrapolate to a different pressure are listed in the table below. When using MAGBOLTZ or MIX to compute the transport properties, you are strongly advised to have the transport properties computed at the relevant pressure and temperature, instead of relying on the scaling laws.

quantity scaling enter
drift velocity v vs E/p v
ion mobility mu vs E/p mu
diffusion coefficients sigma.sqrt(p) vs E/p sigma.sqrt(p)
Townsend coefficient alpha/p vs E/p alpha/p
Attachment coefficient beta/p vs E/p beta/p
Lorentz angles - angle

Example: the diffusion coefficient varies approximately with pressure according to the formula:

   sigma(p=p1)=sigma(p=p0)*sqrt(p0)/sqrt(p1)

hence sigma.sqrt(p) is approximately constant.

5.18.3: dummy

The dummy keyword can be used to comment out a column of the gas tables. For instance, if you have prepared a table in which both the transverse and longitudinal diffusion are present and wish to assess the effect of transverse diffusion, then you could do as in this example:

Assigning the transverse diffusion:

table e/p trans-diff long-diff
      1   0.1        0.1
      2   0.1        0.2
      3   0.1        0.3

Not assigning the transverse diffusion:

table e/p dummy long-diff
      1   0.1   0.1
      2   0.1   0.2
      3   0.1   0.3

Alternatively, you could have kept the original table followed by a RESET TRANS-DIFF command.

5.18.4: RANGE

The range in E/p to be covered by the table. This parameter is relevant only if E/p is not tabulated i.e. if there is no E/P keyword on the TABLE instruction line.

[By default: 0.1 to 100 V/cm.Torr in 20 logarithmic steps.]

5.18.5: N

The number of points in the table, relevant only in the case that E/p is not present in the table, i.e. if E/P is absent from the command line.

[By default: 20 points covering E/p from 0.1 to 100 V/cm.Torr]

Section 5.19: TEMPERATURE

Sets the temperature of the gas.

The temperature is used by the gas mixing instructions (MIX and MAGBOLTZ) and also by HEED. Please be sure to specify the temperature before issuing these commands.

The temperature is not needed if both the transport properties and the clustering properties have been entered via tables.

Garfield applies, if required, pressure scaling of the transport properties but does not apply temperature scaling laws.

Format:

TEMPERATURE temp [unit]

Example:

TEMPERATURE 300 K

For room temperature.

5.19.1: temp

The temperature of the gas.

[Initially set to 300 K.]

5.19.2: unit

Various temperature units are recognised, as listed in the table:

Unit Conversion from Kelvin Notation, shortest
degree Celsius T-273.15 CELSIUS, C
degree Fahrenheit (T-273.15)*9/5+32 FAHRENHEIT, F
Kelvin T KELVIN, K
degree Rankine (T-273.15)*9/5+32-459.67 RANKINE, RA
degree Reaumur (T-273.15)*4/5 REAUMUR, RE

Default input unit is Kelvin, temperatures are output in K or in C, the unit which is chosen for output doesn't depend on the unit used for input.

Section 5.20: WRITE

Writes a compact format gas dataset to be read by the GET instruction.

The use of this instruction is strongly recommended when you compute the electron transport properties with MAGBOLTZ or with MIX, both of which consume a lot of CPU time. WRITE is not of interest if you enter the transport parameters of your gas description with a TABLE statement.

The dataset contains initialisation information for Heed, which will automatically be performed when re-reading the file with GET.

The format of the compact dataset is subject to modification and backwards compatibility is not guaranteed. Compact datasets that can no longer be read and that are of value, can however be sent to the author of Garfield for recovery.

Files written with WRITE should in principle not be edited. These files are also not meant to be easily readable, use the GAS-PRINT option or procedures like DRIFT_VELOCITY to obtain legible tables.

Writing takes place while the section is being left, not when the WRITE command is issued. The statement can appear at any place in the gas section.

Format:

WRITE   DATASET dsname [member]   [REMARK remark]

Examples:

WR DATA 'vaxgarf"garfield lasagna"::[garfield]gas.dat' REM "Test gas"

(The keywords DATASET and REMARK are required in this example since the member is omitted. The single quotes are needed because of the double quotes in the remote login string and also because of the two colons.)

5.20.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

5.20.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

5.20.3: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset.

Chapter 6: &OPTIMISE

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

Section 6.1: overview

The optimisation section contains the instructions which fall in the following categories:

Optimisation of potential settings

Command Short description
DISPLAY Displays potential settings
FACTOR Factorises the potential
FORCES Computes the forces on the wires
PRINT-CELL Prints the cell data
RESTORE Restores the original settings after a SET
SAVE Saves the potential settings
SET Optimises potential settings

Modification of the cell structure:

Command Short description
ADD Adds elements to the cell
CHANGE-VOLTAGES Modifies the wire, plane and tube potentials
DELETE Deletes elements from the cell

Three dimensional charges:

Command Short description
CHARGES Adds three dimensional charges to the cell
DELETE-CHARGES Removes three dimensional charges from the cell
LIST-CHARGES Lists the three dimensional charges

Adding a background field:

Command Short description
BACKGROUND-FIELD Adds a background field to the cell
DELETE-FIELD-MAP Deletes a background field map
DELETE-BACKGROUND-FIELD Removes the background field
FIELD-MAP Reads a field map for use as background field
READ-FIELD-MAP Reads a binary field map as background field

General purpose instructions:

Command Short description
AREA Changes the part of the cell that is considered
DRIFT-AREA Sets the part of the cell where electrons drift
GRID Changes the grid density
OPTIONS Switches options off and on
POINTS Sets the number of points on the track
SELECT Selects active wires
TRACK Sets the track

Section 6.2: ADD

This instruction adds one or more elements to the cell. You may in one go both add more than one wire, a wire and a plane etc.

The coordinate system can not be changed by this instruction.

The symbolic variables from the cell section can not be used.

After each ADD instruction, the cell is checked, a new cell type is determined and the capacitance matrix is calculated. If you have several elements to add, it is advisable to group them in a single instruction. If you only wish to modify a wire voltage, use CHANGE-VOLTAGES instead.

Format:

ADD [PERIODICITY {X|Y|PHI} length] ...
    [PLANE {X|Y|R|PHI} coordinate ...
           [VOLTAGE voltage]] ...
           [LABEL label]
    [WIRE LABEL label ...
          AT position ...
          [VOLTAGE voltage] ...
          [DIAMETER diam]]

6.2.1: length

The length of the periodicity, in cm for x and y, in degrees for phi. Periodicities in phi must divide 360 degrees, they are rounded if that is not the case.

Periodicities in r are not permitted.

6.2.2: coordinate

The position of the plane, in cm for x, y and r, in degrees for phi. The r coordinate of a circular plane must be > 0.

6.2.3: voltage

The potential of the wire or the plane in Volt [default 0 V].

6.2.4: label

A single character by which you can identify the wire or the plane in SELECT statements.

The label 'S' has a special meaning in that these wires are by default selected.

Planes are by default not given a label, a label is mandatory for wires.

6.2.5: position

The location of the new wire.

This is a set of two numbers (x,y) or (r,phi) depending on whether the cell is entered in polar or Cartesian coordinates.

The units of x, y and r is cm, phi is in degrees.

[No default, these are mandatory parameters.]

6.2.6: diameter

The diameter of the new wire.

[Default: 0.01 cm.]

Section 6.3: AREA

Changes the plane over which the optimisation is carried out. Only relevant if optimisation by GRID has been selected.

Please note that the AREA affected by this instruction is not the area in which electrons and ions are allowed to drift. The latter area, which is relevant when optimising the drift time, is set with the DRIFT-AREA command.

Format:

See the AREA command in the field section.

Section 6.4: BACKGROUND-FIELD

Adds a background field to the field that results from the wires, the planes, dielectrics, 3-dimensional charges and field map.

The background field is not checked for consistency between the field and potential, nor for compatibility with the boundary conditions. Such checks can be done in the field section using the CHECK instruction.

You have to supply at least 3 formulae: potential, x- component and y-component of the electric field. You may in addition supply the z-component of the electric field. The latter defaults to 0.

If the background field is to be derived from a field map, then the FIELD-MAP statement should precede the BACKGROUND-FIELD statement. The background field map is kept across optimisation and cell sections, as long as the storage occupied by this field is not claimed by a main field map in the cell section. It is therefore not necessary to read a field map again to modify the dependence of the background field map on the field map.

Format:

BACKGROUND-FIELD ...
     VOLTAGE formula  EX formula  EY formula  [EZ formula]

Example:

background-field voltage=cos(2*x)*sin(2*y) ...
               ex=     2*sin(2*x)*sin(2*y) ...
               ey=    -2*cos(2*x)*cos(2*y)

6.4.1: formula

The background field should be entered as formulae in terms of the following variables:

Variable Meaning
X (or R) x- or r-coordinate
Y (or PHI) y- or phi-coordinate
Z z-coordinate
EXMAP x-component of the background electric field map
EYMAP y-component of the background electric field map
EZMAP z-component of the background electric field map
VMAP background potential field map

Section 6.5: CHANGE-VOLTAGES

Changes the voltages on a group of wires, a group of planes and on the tube.

This instruction does not recompute the capacitance matrix, and is therefore considerably faster than ADD for large cells. You should however use the latter if you need to modify other parameters than the potential, such as the location of a wire or a plane, the radius of the tube or the diameter of a wire.

Format:

CHANGE-VOLTAGES {WIRE wire | PLANE plane | TUBE} VOLTAGE voltage ...

Example:

CH-V     W 1 V 1000      W 2 V 3000

Changes the voltage on wire 1 to 1000 V and on wire 2 to 3000 V.

6.5.1: wire

The wires of which the voltage is to be changed can either be selected by wire number (this number can be found in the listing that is produced if you set CELL-PRINT in the cell section) or by the wire label that you used when entering the wires with the ROWS statement.

[No default, this is a mandatory parameter.]

6.5.2: plane

The planes of which the voltage is to be changed can either be selected by name (LEFT, RIGHT, UP, DOWN) or by the label that you can have entered with the PLANE statement.

[No default, this is a mandatory parameter.]

6.5.3: voltage

The new voltage to be assigned to the wire, plane or tube.

[To be specified in Volt.]

Section 6.6: CHARGES

+-----------------------------------------------------------------+
| The current version of Garfield only takes point charges into   |
| account in a small number of configurations.                    |
+-----------------------------------------------------------------+

Adds three dimensional point charges to the cell. These charges are not taken into account for the charge calculation on the wires, they therefore should be seen as, temporary, space charges.

Format:

CHARGES
x y z q
x y z q
...
(blank line)

Example:

CHARGES
0 0 0 100
1 1 1 200

Places one space charge at (0,0,0) and one at (1,1,1). The first has a charge of 100 and the second a charge of 200.

6.6.1: position

The position should be given as 3-dimensional coordinates (x,y,z) and in cm.

6.6.2: charge

As for wires, Garfield does not apply conversion factors. The potential function used for three dimensional charges is simply q/r, where r is the distance between the charge and the point where the potential is to be calculated.

Section 6.7: DELETE

Not yet available, see ADD.

Section 6.8: DELETE-BACKGROUND-FIELD

Removes the background field.

Format:

DELETE-BACKGROUND-FIELD

Example:

del-backgr

Section 6.9: DELETE-CHARGES

Removes all three dimensional charges.

Format:

DELETE-CHARGES

Example:

DELETE-CHARGES

Section 6.10: DELETE-FIELD-MAP

Deletes the field map.

Format:

DELETE-FIELD-MAP

Example:

DELETE-FIELD-MAP

Section 6.11: DISPLAY

Prints the current potential settings.

Format:

DISPLAY

Section 6.12: DRIFT-AREA

Changes the area in which electrons and ions are allowed to drift.

Please note that this command does not define the plane over which optimisation is carried out. To change this plane, use AREA.

Format:

See the AREA command in the field section.

Section 6.13: FACTOR

Prints the contributions to the field from each wire-potential separately. The contributions of a set of wires put together in a single group by SELECT, are summed if the GROUP option is selected.

Format:

FACTOR [GRID | WIRE | TRACK] ...
       [NOGROUP | GROUP]

Example:

FACTOR

(All defaults, GRID and NOGROUP, are accepted.)

Section 6.14: FIELD-MAP

In case the background field is too complex to compute analytically, it may still be possible to compute it with the help of finite element programs.

When computing a background field due to additional charges, with finite element programs, all conductors should be set to 0 V. This ensures that the boundary conditions are respected when the basic field and the background field are superimposed.

Also the &CELL section has a FIELD-MAP command. The field maps entered in the &CELL section serve as main field, i.e. the field map replaces the field due to wires and planes, file the field maps entered in the &OPTIMISE section are used for the computation of the background field. The two field maps share (for the moment) the same storage and can therefore not be used at the same time.

Format and examples:

See the FIELD-MAP command in the cell section.

Section 6.15: FORCES

Computes the forces acting on a wire and the wire displacement that results from these forces.

To obtain meaningful results, one should take care to supply, using the ROWS statement of the cell section, the wire length and the wire tension. If one is interested in the gravitational sag, then one should also enter the density of the wire material and the chamber orientation with the GRAVITY.

This instruction offer 2 levels of accuracy, called DETAILED and FAST.

The wires on which this instruction operates are those selected by the SELECT instruction. These wires do not necessarily have to be located within the current AREA. When one uses the ITERATE option to study collective wire motion, then it is crucial to select all wires that are likely to move.

Format:

FORCES [PRINT-SAG | NOPRINT-SAG] ...
       [PLOT-SAG | NOPLOT-SAG] ...
       [NOKEEP-SAG | KEEP-SAG] ...

[PRINT-FORCES | NOPRINT-FORCES] ... [PLOT-FORCES | NOPLOT-FORCES] ... [NOKEEP-FORCES | KEEP-FORCES] ...

[DETAILED | FAST] ... [SCANNING-GRID nx ny] ... [SCANNING-AREA {LARGEST | FIRST-ORDER | ... FIRST-ORDER-ENLARGED-BY fact | ... xmin ymin xmax ymax}] ... [SHOTS nshot] ... [STEPS-PER-SHOT nstep] ... [INTERPOLATION-ORDER order] ... [NOEXTRAPOLATE | EXTRAPOLATE] ...

[ITERATE [n_iter] | NOITERATE] ... [TOLERANCE tolerance] ... [UPDATE-SCALING-FACTOR factor] ... [OFFSET wire x_offset y_offset] ...

[ELECTROSTATICS | NOELECTROSTATICS] ... [GRAVITY | NOGRAVITY]

Example:

select s
forces detailed keep-sag

The forces acting on the S wires will be calculated in detail and the sag profiles will be stored in global variables.

Note:

This computation benefits greatly from vector processors and matrix algebra libraries tuned to the hardware (e.g. ESSL).

6.15.1: FAST

Requests a fast calculation in which only the force acting on the wire in its nominal position is used to compute the sag.

The wire sag that results from such a force is parabolic, since this it results from an elastic elongation. The shape is not a hyperbolic cosine, this would be the case of a freely hanging wire that is longer than the distance between the two (elongation negligible).

This approach is incorrect if the wire is nominally in an almost stable position while there are substantial forces acting on the wire in neighbouring positions.

6.15.2: DETAILED

Requests a calculation of the wire sag profiles, computing the forces at each wire position. The forces are computed by interpolation on a SCANNING-GRID around the wire at the points of which the forces are explicitely calculated.

Computing this grid of forces is potentially time consuming since it involves solving the capacitance equation for each wire position.

6.15.3: SCANNING-GRID

When the DETAILED option is active, the program tries to compute a sag profile for each wire. This calculation needs, as one of the parameters, the force acting on the wire as function of the wire displacement. Since it would not be practically possible to compute this force each time explicitely (i.e. by solving the capacitance matrix), an interpolation is performed on a grid (the interpolation order can be chosen with INTERPOLATION-ORDER).

The boundaries of the grid are automatically computed from both the expected sag in the parabolic approximation and the largest area around each wire that is free of cell elements. One can also set the area manually with SCANNING-AREA.)

The number of grid lines can be controled with the SCANNING-GRID option. Numbers can be specified separately for x and y and should be in the range 2 to MXGRID.

[Default is 11 for both nx and ny.]

6.15.4: SCANNING-AREA

By default, the range of wire shifts for which the forces are computed, is selected automatically by enlarging by a factor 2 the 0th order estimates of the shift, and restricting this to the largest area around the wire which is free of other cell elements. This behaviour can be selected explicitely also by specifying the area as FIRST-ORDER.

If the scaling factor 2 doesn't appear suited, then use the keyword FIRST-ORDER-ENLARGED-BY followed by a scaling factor of your choice.

If the wire movements are expected to be very large, then one may wish to select LARGEST which will set the scanning area to the largest area around each wire which is free from other cell elements.

You may also manually set the scanning area by giving 4 numeric arguments: a lower x, a lower y, an upper x and an upper y which together describe a rectangular area relative to the nominal position of the wire under consideration. Note that a manually set scanning area is not checked to be located within the largest area free of other cell elements. The option is convenient for making plots of the force variations.

6.15.5: nshot

The differential equation that governs the wire sag is numerically solved using a multiple shooting method in which each shot is traced with a Runge-Kutta-Nystroem method, and in which the boundary and matching conditions are minimised with a Newton method with Broyden rank-1 updates of the derivative matrix.

The number of shots can be chosen by the user and must be equal to 0, in which case the method becomes a single shot method.

Also the number of integration steps within each shot can be set by the user. This parameter must be at least equal to 1.

6.15.6: nstep

See nshot.

6.15.7: INTERPOLATION-ORDER

This is the order used to interpolate the electrostatic force table used by the detailed method.

The interpolation is done by interpolating first along the rows of the table, then the interpolation results, in both cases by local polynomial interpolation of the selected order.

The order should be a number larger than or equal to 1, and small than or equal to the scanning grid size.

6.15.8: EXTRAPOLATE

By default, the calculation stops if a point of the wire is found at a position not covered by the SCANNING-AREA, whether set manually or automatically.

If you select EXTRAPOLATE, then the force on the wire at such a point, will be computed by extrapolating the force table.

It is usually a better strategy to pick a SCANNING-AREA that covers all wire positions - if this is not possible, then the wire is probably not in a stable position (i.e. it will move against other electrodes).

6.15.9: ITERATE

Requests iterating over the positions of all SELECTed wires.

The iteration starts from the nominal position for all wires, and a set of wire offsets equal to (0,0) except for those wires for which the user has given an initial offset.

Then, a loop is started in which

  1. for each SELECTed wire, the average sag is computed assuming the nominal position for this wire and the position + its current offset for the other wires
  2. once all average sags are known, the wire offsets are updated.

The iteration is stopped when

ITERATE can be used both with the FAST and with the DETAILED method of calculating wire sags.

Output is only produced from the last iteration provided convergence has been achieved.

Iteration is done by default when the number of SELECTed wires is larger than 1. The default maximum number of iterations is set to 5, which may be insufficient if the TOLERANCE is set to a very small number, and also in case of an oscillatory systems. In the latter case it is preferable to adjust the UPDATE-SCALING-FACTOR.

6.15.10: TOLERANCE

This parameter enters as convergence criterion for iterations over all wires (ITERATE option).

In each iteration, the maximum of the differences between the current and the new wire offsets is computed. When this maximum drops below TOLERANCE, the iteration is declared to have converged.

[The parameter is by default set to 0.0010 cm, 10 micron.]

6.15.11: UPDATE-SCALING-FACTOR

(not yet used)

6.15.12: OFFSET

When performing iterations over all wires (ITERATE option), there are instable equilibrium situations in which no wire would moves in its nominal position, but where all wires move as soon as one wire is slightly displaced.

To deal with such cases, you can manually set the initial offset of one or more wires.

The offsets you specify are applied to all wires except the one of which the sag is being computed.

[By default, all wires have an initial offset of (0,0).]

6.15.13: GRAVITY

The gravitational force on the wire is included in the sag computation.

[This is default.]

6.15.14: ELECTROSTATICS

The electrostatic force on the wire is taken into account when calculating the wire sag.

[This is default.]

6.15.15: PRINT-SAG

Prints depending on the requested level of detail in the calculation, the following is printed:

[This is default.]

6.15.16: PLOT-SAG

Plots the sag profiles if the DETAILED option has been selected.

[This is default.]

6.15.17: KEEP-SAG

When this option is selected, the wire sag is stored in global variables:

The wire elongation is stored in STRETCH_n, a Number, in both cases.

In case these global variables are already in use, then their contents will be lost.

These arrays can be used to obtain the sag at any point on the wire by such statements as:

Parse terminal z
Call interpolate_2(z_1,sag_x_1,z,x)
Call interpolate_2(z_1,sag_y_1,z,y)
Say "Sag at z={z} is (x,y)=({x,y})."

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

The variable OK is set to True if no error was detected during execution of the FORCES command, otherwise it is set to False. This variable can therefore be tested to decide whether further action on the output variables is meaningful.

[The wire sag is not kept by default.]

6.15.18: PRINT-FORCES

Prints, if the DETAILED option has been selected, a table of the forces acting on the wire as function of its shift. This table is used to compute the sag profile.

[This option is off by default.]

6.15.19: PLOT-FORCES

Plots, if the DETAILED option has been selected, the force acting on the wire as function of its shift, both as function of the x-shift for various y-shifts and as function of the y-shift for various x-shifts.

These graphs are meant to convey the absolute values of the forces, they are not meant to be particularly pleasing to the eye. For a more colourful presentation, use the KEEP-FORCES option and plot the forces with the PLOT_SURFACE or PLOT_CONTOURS procedure.

The x-component of the force is plotted with the representation FUNCTION-1 while the y-component is shown with the representation FUNCTION-2.

[This option is off by default.]

6.15.20: KEEP-FORCES

When this option is selected, the table of electrstatic forces acting on the wires is stored as:

Note that only the electrostatic forces are stored - the gravitational force, if present, is assumed constant and can be computed from the wire density and chamber orientation.

In case these global variables are already in use, then their contents will be lost.

This option is probably not very useful - it could for instance be used to make a 3-dimensional graph of the electrostatic forces acting on the wire as function of the wire shift:

Call plot_surface(fx_1,60,30,x_f_1,y_f_1)
Call plot_end
Call plot_surface(fy_1,60,30,x_f_1,y_f_1)
Call plot_end

or to obtain the electrostatic forces acting on the wire in their final position:

* Get position at wire centre
Call interpolate_2(z_1,sag_x_1,0,xc)
Call interpolate_2(z_1,sag_y_1,0,yc)
Say "Position in the wire centre: ({xc,yc})."
* Get forces at wire centre
Call dimensions(x_f_1,ndim,dim)
Global nx=number(dim)
Call dimensions(y_f_1,ndim,dim)
Global ny=number(dim)
Call book_matrix(point,2,1)
Global point[1;1]=xc
Global point[2;1]=yc
Call interpolate(fx_1,x_f_1,y_f_1,point,out)
Global fxc=number(out)
Call interpolate(fy_1,x_f_1,y_f_1,point,out)
Global fyc=number(out)
Call delete_matrix(dim,point,out)
Say "Electrostatic forces in central position: ({fxc,fyc}) N/cm."

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

The variable OK is set to True if no error was detected during execution of the FORCES command, otherwise it is set to False. This variable can therefore be tested to decide whether further action on the output variables is meaningful.

[The force table is not kept by default.]

Section 6.16: GRID

Sets the density of sampling points on the grid. This number is usually chosen of the order of 25 for plots (field section) but 10 is more advisable for executing the SET instruction.

The grid is common to all sections.

Format:

GRID  number_of_steps_in_x  [number_of_steps_in_y]

Example:

GRID 5

6.16.1: number

Number of equal grid divisions.

You may supply either 1 or 2 arguments. If the 2nd argument is omitted the first value will be used for both the x (or r) and the y (or phi) spacing.

[Default is 25 for both.]

Section 6.17: LIST-CHARGES

Produces a list of the currently present three dimensional charges.

Format:

LIST-CHARGES

Example:

LIST-CHARGES

Section 6.18: OPTIONS

No local options in this section, but the OPTIONS command can be used to set global options, see the top level OPTIONS command.

Section 6.19: POINTS

When optimisation by TRACK has been selected, you may wish to vary the number of points on the track.

Contrary to most other commands which take the number of sampling points from the TRACK command, SET uses the number set with POINTS.

This number is used nowhere else.

Format:

POINTS  points_on_track

Example:

POINTS 50

[Default: 20]

Section 6.20: PRINT-CELL

Produces a listing of the cell elements, like the one made at the end of the cell section if the CELL-PRINT option is in effect.

Format:

PRINT-CELL

Example:

PRINT-CELL

Section 6.21: READ-FIELD-MAP

See FIELD-MAP in the &CELL section.

Section 6.22: RESTORE

Restores a previously SAVEd set of potentials. The original potentials are restored if no reference number is given. The program tells you the reference number when you issue the SAVE instruction.

Format:

RESTORE [reference_number]

Example:

SAVE
(program replies with the reference number 5; next you try:)
SET V TO AVERAGE ON GRID
DISPLAY
(You notice you don't like the new settings and therefore ...)
RESTORE 5

Section 6.23: SAVE

Saves the current set of potentials. The program replies with a number you should remember because it's required for retrieval with the RESTORE command:

Format:

SAVE

Section 6.24: SELECT

Selects and groups the electrodes which are to be handled specially. The selection is common to all sections, but the interpretation of the selection is left to the individual instructions.

In this section, the FORCES instruction will try to compute displacements for the wires that have been selected and the SET instruction will vary the voltages on such wires.

Selection of other electrodes than wires has no effect in this section.

Format:

See the SELECT command in the field section.

Example:

SEL (1 S) 2 F

(Put wire 1 together with all S wires in one group, make wire 2 a group of its own and do the same for each of the F wires.)

Section 6.25: SET

SET is a key instruction in the optimisation section. It varies the potential settings in an attempt to satisfy your criteria. The method used is that of repeated Householder steps minimising (in the Euclidean norm) the difference between the target and field function. Several conditions can cause the iteration to be stopped:

Only the potentials on the electrodes that have been subject to a SELECT will be touched during the process. Electrodes that are put together in a group, are shifted collectively.

Format:

SET field_function ...
    TO {AVERAGE | target_function} ...
    [WEIGHT weight_function] ...
    [ON {TRACK | GRID | WIRE}] ...
    [DISTANCE distance] ...
    [EPSILON epsilon] ...
    [ITERATE-LIMIT iterlim] ...
    [PRINT | NOPRINT]

Examples:

SET V TO AVERAGE ON TRACK DIST 100
SET E TO 1000 ON GRID DIST 1

(The first example is an attempt to make V flat over a line, the second could be used to obtain a homogeneous drift field.)

6.25.1: distance

The value of the maximum deviation between the target and the field function at which you will allow the iteration to stop.

[Initial default: 1, remembered from one SET command to the next]

6.25.2: epsilon

A small number used to check relative changes in the improvement and also to compute the numerical derivatives needed for the covariance matrix. Hence, a larger value (say 1) should be chosen when you know you are far from the optimised value and a smaller value (say 1E-4) when your initial guess is quite good.

Values smaller than 1E-4 are harmful on machines with a limited single precision accuracy, like Apollo, IBM and Vax, because the covariance matrix is effectively a set of second derivatives. On Cray one might consider moving to smaller values.

[The initial default setting is 1E-4, the value is remembered from one SET command to the next.]

6.25.3: field_function

A function of the coordinates, the electrostatic field and potential, and some drift related quantities that will be made to resemble the target function as closely as possible.

Variable Meaning Notes
X or R x- or r-Coordinate -
Y or PHI y- or phi-Coordinate -
EX or ER x- or r-component of E -
EY or EPHI y- or phi-component of E -
E norm of E -
V potential -
AVALANCHE integrated Townsend coefficient Not compatible with WIRE
DIFFUSION integrated diffusion Not compatible with WIRE
TIME drift time Not compatible with WIRE

When using drift related quantities (AVALANCHE, DIFFUSION and TIME), one should take care to define a proper drift area via the DRIFT-AREA command. These quantities can not be used when optimising on the surface of one or more WIRES.

More variables can be added on demand.

6.25.4: GRID

Specifies that the grid should be used to compare the target and field functions.

The density of the grid is set with the GRID command, please ensure that the number of grid points is not excessive.

Do not forget to set a proper DRIFT-AREA if you wish to optimise drift related quantities (AVALANCHE, DIFFUSION and TIME).

6.25.5: iterlim

The maximum number of iterations you allow the program to make. [The default setting is 10.]

6.25.6: PRINT

By default, some optimisation information is printed each cycle. This may be switched of by specifying NOPRINT.

6.25.7: target_function

A function of the coordinates that the program will try to reproduce with the field function by playing with the potentials.

The alternative, AVERAGE, implies the field function is evaluated with the initial potential settings and that the resulting number is the target function for all points.

Variable Meaning Notes
X or R x- or r-Coordinate -
Y or PHI y- or phi-Coordinate -

6.25.8: TRACK

Specifies that the track should be used to compare the target and field functions.

The number of track points can be set with POINTS.

Do not forget to set a proper DRIFT-AREA if you wish to optimise drift related quantities (AVALANCHE, DIFFUSION and TIME).

6.25.9: weight_function

By default the minimisation procedure tries to make the field function approach the target function the best it can, working equally hard for all points. If some points matter more than others, you alter this by assigning the important points a larger weight.

The default weight for all points is 1, a weight is allowed to be negative but may not be zero.

The weight function may depend only on the coordinates:

Variable Meaning Notes
X or R x- or r-Coordinate -
Y or PHI y- or phi-Coordinate -

6.25.10: WIRES

Specifies that the surface of the wires with label S should be used to compare the target and field functions.

The number of points near the surface of each wire can be set with the POINTS command.

Drift related quantities (AVALANCHE, DIFFUSION and TIME) can not be used in conjunction with WIRES.

Section 6.26: TRACK

Sets the track which is used by the optimisation of the potentials as performed by the TRACK option of the SET command.

The TRACK command is shared between all sections and has therefore a rich format. In this section, only the geometrical aspects are used. Particle types and clustering models need not be specified.

Format:

See the TRACK command in the drift section.

Example:

TRACK 1 1 2 2

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

Section 7.1: overview

The instructions of the field section fall in 4 categories:

The use of this section is fairly straight-forward since it has only one frequently used instruction: PLOT-FIELD.

Setting parameters:

Command Short description
AREA Sets the view and size of the plotting area
GRID Sets the density of the plotting grid
SELECT Establishes the list of sense wires
TRACK Sets the track used for graphs

Plotting and printing:

Command Short description
PLOT-FIELD General purpose field plotting instruction
PRINT General purpose field printing instruction

Understanding:

Command Short description
CHECK Verifies charges and boundary conditions
MULTIPOLE-MOMENTS Computes the multipole moments for a wire

Service instructions:

Command Short description
SAMPLE Field value (see ELECTRIC_FIELD)
TIME Times the field calculations

Notes:

  1. There are several instructions in the optimisation section that perform related tasks.
  2. There are also procedure calls that perform related tasks: ELECTRIC_FIELD, ELECTRIC_FIELD_3, MAGNETIC_FIELD, MAGNETIC_FIELD_3, INTEGRATE_CHARGE, INTEGRATE_FLUX, MAP_ELEMENT, MAP_INDEX and MAP_MATERIAL.

Section 7.2: AREA

Sets the following things:

AREA commands are found in several sections:

The geometrical extent of the field and the drift area boxes are distinct, but the viewing plane is shared between the two.

Format:

AREA [xmin ymin xmax ymax | xmin ymin zmin xmax ymax zmax] ...
     [VIEW plane] ...
     [ROTATE angle] ...
     [X-Y | R-PHI | X-Z | Y-Z | 3D | CUT] ...
     [LIGHT-ORIGIN phi_light theta_light] ...
     [REFLECTED-FRACTION frac_refl] ...
     [ABSORBED-FRACTION frac_scat] ...
     [COLOURS ncol] ...
     [PARTIAL-BOX-TICKMARKS | FULL-BOX-TICKMARKS] ...
     [PARTIAL-TUBE | FULL-TUBE] ...
     [PARTIAL-PLANES | FULL-PLANES] ...
     [SPLIT-INTERSECTING-PLANES | NOSPLIT-INTERSECTING-PLANES] ...
     [NOSORT-PLANES | SORT-PLANES] ...
     [OUTLINE | NOOUTLINE] ...
     [PLOT-MAP | NOPLOT-MAP] ...
     [NOSTEP | STEP]

Example:

AREA -1 -1 1 1

7.2.1: box

Sets a limiting rectangle or a limiting box. If only 4 numbers are given, then these are interpreted as the range in (x,y) or in (r,phi) and the range in z is left unchanged.

Field plots are made only over the part of the viewing plane that is located inside the box.

Particles are allowed to drift inside the limits of the box.

[The initial default is taken from the cell dimensions.]

7.2.2: plane

The VIEW argument enables you to define the viewing plane, and offers some control over the coordinate system in this plane.

The viewing plane is defined by a formula in terms of the variables X, Y and Z that defines the points located in the plane. The formula should be linear in all 3 variables. No particular format is required, the formula is not looked at token by token, but evaluated at 9 points to extract the parameters of the plane.

In 3-dimensional field plots, plane oriented commands such as PLOT SURFACE, PLOT VECTOR and PLOT HISTOGRAM, compute the quantities that they plot in points of the viewing plane.

In 2-dimensional chambers, the plane would normally be chosen to coincide with the plane in which the chamber is described, i.e. the plane would be z=0 for a chamber in (x,y), but this is not mandatory. It is perfectly permissible, and it can also be meaningful, to define solids and view them in 3D perspective.

If you plan to issue field plotting commands after the AREA statement, then please ensure that the viewing plane crosses the limiting box of the area - points on the viewing plane, but outside the limiting box are not shown.

For drift plots, the viewing plane merely determines the plane onto which the drift lines will be projected. Wires, tubes, planes and other materials are plotted as the cross section with the viewing plane.

[The default setting is Z=0.]

7.2.3: plane_coordinates

The coordinates system in the viewing plane is by default chosen as follows. Assume that a, b and c are not all zero so that a plane is defined by the formula:

a*x + b*y + c*z = d

Then N = (a,b,c) is a vector normal to the plane. The origin of the coordinates in the viewing plane is chosen to be:

Origin = N * d / (a**2 + b**2 + c**2)

If a and c are not both 0, then (c,0,-a) is normal to N and is used, after normalisation, as first coordinate. If a and c are both 0, then b is non-zero and (0,c,-b) is a non-zero vector normal to N which is used as second coordinate axis, also after normalisation. We call the first coordinate vector U, the second V.

The remaining coordinate vector is obtained as the external product of N and the already known coordinate vector. To ensure the system is right-handed, we define in the first case V = N x U and in the second case U = V x N.

These coordinates are chosen such that x is the first coordinate axis for view in the y=0 plane and y the second coordinate axis for the x=0 plane. They can be rotated if desired, see angle.

7.2.4: angle

If the default coordinate axes in the viewing plane (see plane_coordinates) do not suit you, then you can rotate these axes by an amount you specify with this keyword.

This angle has no incidence on the coordinate systems used for X-Y, Y-Z, X-Z and R-PHI projection.

The angle should be specified in degrees.

[Default rotation angle: 0 degrees.]

7.2.5: X-Y

Requests an x-y view, at z=0.

In this kind of view, any solids that may have been entered will not be shown. If the field is derived from a 2D or 3D field map, then the elements or the cross sections of the elements will be shown if the PLOT-MAP option is active.

This type of plot consists of

[This is the initial default for Cartesian cells and cells that have a tube, provided no VIEW is specified.]

7.2.6: X-Z

Requests x-z views, at y=0.

In this kind of view, any solids that may have been entered will not be shown. If the field is derived from a 3D field map, then the cross sections of the elements of the field map will be shown if the PLOT-MAP option is active.

This type of plot consists of

[X-Y is default]

7.2.7: Y-Z

Requests y-z views.

In this kind of view, any solids that may have been entered will not be shown. If the field is derived from a 3D field map, then the cross sections of the elements of the field map will be shown if the PLOT-MAP option is active.

This type of plot consists of

[X-Y is default]

7.2.8: R-PHI

Requests r-phi views, only meaningful with polar cells, for which this is the only available viewing method.

In this kind of view, any solids that may have been entered will not be shown, nor will cross sections of the elements of the field map appear.

This type of plot consists of

[This is the default in polar cells.]

7.2.9: CUT

Asks for a cut through the AREA in the location of the viewing plane. A viewing plane must therefore be defined when using this option - the viewing plane may of course be defined in the same AREA statement, but the formula for this plane need not be repeated if has been entered in a preceding AREA statement.

The display will show the solids through which the viewing plane cuts, but will not show solids that are located fully above or below the viewing plane.

If displaying the solids is not desired, then the faster X-Y, X-Z or Y-Z options should be used. If on the other hand solids should be shown, then the 3D option might be preferable.

If the PLOT-MAP option is on and if the field is derived from a field map, then the elements or the cross sections of the elements with the viewing plane will be shown.

This projection, other than 3D, will usually lead to a view that is not isometric.

This type of plot consists of

[CUT becomes the default if a viewing plane is defined in the same AREA statement, unless 3D was set previously.]

A cut through the same GEM foil that is shown under 3D views. In this example, outlining is absent.

7.2.10: 3D

Asks for a three dimensional impression of the chamber as seen along an axis normal to the viewing plane. An attempt is made to remove partially and fully hidden parts of the solids. Similarly, curves are clipped to show only the parts that are not hidden by a solid.

The various solids present in the cell are coloured in shades of their basic colour, depending on the exposure with respect to the light source and the viewing plane, on the REFLECTED-FRACTION and on the ABSORBED-FRACTION of the light. The various shades of each colour can be examined with the SHADING-MAP graphics command.

Elements of the field map are not shown with this projection, even if the PLOT-MAP option is on.

This is the only projection that guarantees an isometric projection.

This option is highly CPU intensive and makes use of a much large number of colours than usual.

The plots consist of the following elements:

A three dimensional view of a GEM foil with staggered holes.

7.2.11: light

When plotting 3-dimensional impressions, each panel of the solids is shaded in a more or less dark variant of its basic colour. Deliberately, a very simple model, described below, has been chosen for the visualisation of 3-dimensional objects as many excellent programs for this purpose are on the market.

A panel can become visible in two ways:

Garfield does not perform ray tracing - light reflected from one panel does not contribute to the illumination of another.

The shade used for a surface panel is therefore determined by the following factors:

Parts of panels that are hidden behind others are removed, see SPLIT-INTERSECTING-PLANES.

7.2.12: LIGHT-ORIGIN

Specifies where the light source is located relative to the viewing direction.

The light source is assumed to produce a broad beam of parallel light rays, similar to the sun - but unlike a light bulb in the immediate neighbourhood.

The location is expressed in polar angles phi and theta, both in degrees.

[Default is 30 degrees for theta and phi.]

7.2.13: REFLECTED-FRACTION

Specifies the part of the visible light that is reflected from the surface, the remainder is diffusely scattered.

Expressed as a percentage.

[Default: 10 %]

7.2.14: ABSORBED-FRACTION

Specifies how much of the incoming light is lost by absorption at the surface.

Expressed as a percentage.

[Default: 3 %]

7.2.15: COLOURS

Sets the number of shades of every colour that are used.

The shades can be examined with the SHADING-MAP graphics instructions.

[Default: 10]

7.2.16: FULL-BOX-TICKMARKS

Three dimensional impressions have the 3 backmost panels of the AREA as background, with a wire frame to indicate the 3 coordinate axes.

[By default, only the coordinate axes on the periphery of these 3 panels are shown so as to avoid ending up with an overcrowded plot, but you can obtain the 3 remaining axes by specifying the FULL-BOX-TICKMARKS option.]

7.2.17: FULL-PLANES

By default, the planes that are seen from the "inside" of the chamber are fully shown, while those seen from the "back" are merely outlined.

On request, by specifying FULL-PLANES, the planes seen from the back will be shown fully,

This option is meaningful only with 3D impressions.

7.2.18: FULL-TUBE

By default, the parts of the tube that are seen from the "inside" of the chamber are fully shown, while those seen from the "back" are merely outlined.

On request, by specifying FULL-TUBE, the parts seen from the back will be shown fully,

This option is meaningful only with 3D impressions.

7.2.19: SPLIT-INTERSECTING-PLANES

When plotting 3-dimensional impressions, an elaborate attempt is made to remove parts of solids that are hidden by others. Given the highly degenerate nature of some overlaps, this process can be very time consuming, in particular when many solids are present and when the solids intersect.

Unfortunately, plots made with this option switched off are rarely meaningful. In a few rare cases, an acceptable result can be obtained with the SORT-PLANES option.

The cutting procedure is complex and presumably still contains errors. Please contact the author in case of poor results and warnings from the PLASPL procedure.

[This option is meaningful only with 3D impressions, where the option is on by default.]

7.2.20: SORT-PLANES

As a slightly faster alternative to SPLIT-INTERSECTING-PLANES, one may request to attempt a sort of the panels.

A panel that is partially hidden by another panel will be plotted first. There is however no order relation for hiding: if A hides part of B, and B hides part of C, then C can very well hide part of A. Hence, only very simple cases can be treated with this option.

The main use of this option is to remedy cases where the SPLIT-INTERSECTING-PLANES procedure fails partially.

[The option is off by default.]

7.2.21: OUTLINE

Requests the outer edges of the solids to be emphasised with a line.

Meaningful with 3D plots. Can also be used with CUT plots although, in this kind of diagram, the outer lines of the solids and the borders of the cut through the solids do not as a rule match.

The lines are drawn according to the OUTLINE representation.

[Outlines are by default not drawn.]

7.2.22: PLOT-MAP

Requests the materials to be shown in plots of the chamber.

The option has effect only if material properties have been entered, either as a map of dielectric constants or as maps of both D and E.

The materials are distinguished by their dielectric constant, which must therefore have been entered with the FIELD-MAP command. This can be done with an explicit map of dielectric constants, but also by a comparison of maps of E and D.

The material with the smallest dielectric constant is shown with representation MATERIAL-1. The medium with the next highest dielectric constant with MATERIAL-2 etc. The drift medium is never shown.

Elements of a 2D field map are only shown in X-Y views and in CUT views at a constant z. The cross sections of the viewing plane with the elements of a 3D field map are shown in X-Y, X-Z, Y-Z and CUT views, but not in 3D views.

Field maps do not usually cover areas filled with conducting material since there is no field inside these. To visualise these, one has to enter them manually with the SOLIDS command. SOLIDS doesn't interfere with PLOT-MAP.

This option can also be switched on or off with the PLOT-MAP option of the FIELD-MAP command.

[This option is by default on if the dielectric constants are known.]

7.2.23: STEP

Waits for a user response after plotting each panel of which at least part is visible. When the panel has been displayed, one can either simply hit return to proceed with the next panel, or type SHOW to see the coordinates, memory references and colour of the panel.

Only active in 3D views.

This is a debugging option.

[This option is switched off initially.]

Section 7.3: CHECK

Checks the following aspects of the field calculations:

CHECK is mainly a debugging instruction, but the WIRE option is a convenient means to to determine the field at the surface of the wires. This quantity is of interest since it gives a rough feeling for the avalanche amplification.

Format:

CHECK [WIRES] ...
           [EPSILON-WIRE eps_wire] ...
      [CHARGES] ...
      [PLANES] ...
      [TUBE] ...
      [MAXWELL] ...
           [BINS bins] ...
           [EPSILON-MAXWELL eps_Maxwell] ...
           [PRINT | NOPRINT] ...
           [PLOT | NOPLOT] ...
      [FULL] ...
      [NOKEEP-RESULTS | KEEP-RESULTS]

Example:

CH WIRE BINS 50

(This would be used to find the field on the surface of the wires and you'll get a few checks on the wire-charges for free.)

7.3.1: bins

The number of bins in the histograms produced by the MAXWELL option.

By default: 100 bins.

7.3.2: eps_Maxwell

The epsilon used to compute differentials when comparing dV/dx and -Ex.

This parameter is by default set to 1.0E-3.

7.3.3: eps_wire

The spacing parameter for the Neville extrapolation of the points used to get an estimate of the potentials and the field at the wire surface.

This parameter is by default set to 1.0E-5.

7.3.4: FULL

Switches on all four options: MAXWELL, PLANE, TUBE and WIRE.

7.3.5: MAXWELL

When this option is selected, tables showing the divergence of the electric field, the difference between dV/dx and Ex, between dV/dy and Ey and the divergence of the magnetic field are printed. In addition, a set of histograms containing related data is plotted.

The options PRINT and PLOT can be used to reduce the volume of output. The histograms produced via this option can be saved with the KEEP-RESULTS option.

7.3.6: PLANES

Compares the potential given to the planes with the potential calculated near the field.

7.3.7: TUBE

Computes the potential and the field near the surface of the tube and also prints a check-sum of the charges and the field integral around the tube.

7.3.8: WIRES

Compares the potential given to the wires with the potential extrapolated to the wire surface. In addition, the electric field on the wire surface is printed - a quantity sometimes used to estimate the amplification of the wire.

If you wish to store these results in global variables, then use the KEEP-RESULTS option.

7.3.9: CHARGES

Verifies that the net flux of the electric field around the 3-dimensional charges matches the charge of these objects.

7.3.10: KEEP-RESULTS

When this option is selected, the surface field and potential on the selected wires are stored as matrices called EX_n, EY_n, E_n, V_n and PHI_n. Also, the histograms from the MAXWELL option are kept.

In case these global variables are already in use, then their contents will be lost.

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

[The output is not kept by default.]

Section 7.4: GRID

Sets the number of grid points in x (or r) and y (or phi) used to produce the plots and tables.

The grid is common to all sections.

Format:

GRID  number_of_steps_in_x  [number_of_steps_in_y]

Example:

GRID 50

7.4.1: number

Number of equal grid divisions.

You may supply either 1 or 2 arguments. If the 2nd argument is omitted the first value will be used for both the x (or r) and the y (or phi) spacing.

[Default is 25 for both.]

Section 7.5: MULTIPOLE-MOMENTS

Helps in finding wires that have a clear dipole, quadrupole etc moment because of the presence of other wires nearby. Such wires should receive special attention because Garfield assumes that a simple charge is enough to describe the wire.

The absence of dipole, quadrupole etc potentials in Garfield is not a fundamental limitation. Such potentials can be added on request.

Format:

MULTIPOLE-MOMENTS ...
     WIRE wire ...
     [ORDER order] ...
     [RADIUS r] ...
     [NOPLOT | PLOT] ...
     [NOPRINT | PRINT] ...
     [EPSILON eps] ...
     [ITERATE-MAXIMUM iter]

Example:

MULTIPOLE WIRE 1 PLOT

Will plot the multipole moments up to order 4 for wire 1.

7.5.1: wire

Number of the wire for which the multipole decomposition must be done.

[No default.]

7.5.2: order

Order of the highest multipole moment.

[Default: 4.]

7.5.3: r

Distance from the wire at which the decomposition is to be carried out. The parameter r is expressed as a number of wire radii.

[Default: 1, i.e. at the wire surface.]

7.5.4: eps

The 'small number' used by the fitting routine to calculate the covariance matrix.

[Default: 1E-4.]

7.5.5: iter

The maximum number of iterations that the fitting routine may do.

[Default: 20.]

7.5.6: PLOT

Requests a plot of the potential around the wire annd of each of the terms in which it has been decomposed.

[This plot is by default not made.]

7.5.7: PRINT

Requests information about the fitting process to be printed.

[This information is by default not printed.]

Section 7.6: OPTIONS

Enters global and local options. Only the local options are listed here. For global options, see the top level OPTIONS command.

Format:

OPTIONS [NOCHECK-MAP-INDICES | CHECK-MAP-INDICES] ...
        [CONTOUR-ALL-MEDIA | CONTOUR-DRIFT-MEDIUM] ...
        [NOWIRE-MARKERS | WIRE-MARKERS]

Example:

opt check-map contour-drift

7.6.1: CHECK-MAP-INDICES

This option is meaningful only if the electrostatic field is taken from a field map. The option has no effect if the cell consists of wires and planes.

When on, an explicit check is made for every point where a field interpolation is requested, that the point is located in one and only one triangle or tetrahedron.

This option is of interest only for debugging purposes. Switching the option on will usually increase CPU consumption considerably.

[This option is off by default.]

7.6.2: CONTOUR-ALL-MEDIA

Requests that contours be drawn across all non-conducting media.

This option is ignored if the field is computed from wires and planes.

[This is default.]

7.6.3: CONTOUR-DRIFT-MEDIUM

Requests contours be drawn exclusively in the material that has been designated as drift medium.

This option is ignored if the field is computed from wires and planes. The option is honoured only if the dielectric constants are present in the field map.

[Contours are by default drawn in all media.]

7.6.4: WIRE-MARKERS

If active, wires will be plotted as markers and not as circles with the size of the wire.

For further information, see the WIRE-MARKERS option in the cell section.

Section 7.7: PLOT-FIELD

This instruction plots the electrostatic and magnetic field in a variety of ways, such as contours, a surface plot, a graph, an histogram and a vector plot.

Similar instructions exist in the drift and signal sections.

CPU time can be saved if several plots are combined in a single command.

Format:

PLOT-FIELD [CONTOUR [f1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                           [N n] ...
                           [LABELS | NOLABELS] ] ...
           [GRAPH [f2]]    [ON f_curve] ...
                           [N n]] ...
                           [SCALE min max] ...
                           [NOPRINT | PRINT] ...
           [HISTOGRAM [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                           [BINS nbin]] ...
           [SURFACE [f4]   [ANGLES phi theta]] ...
           [VECTOR [f5 f6 [f7]]]

If you don't manage to fit all this on a single line, remember that lines that end on an ellipsis are continued on the next.

Examples:

PLOT HIST VECTOR SURF CONT
PLOT CONTOUR RANGE 500 550
PLOT GRAPH 'SIN X'

(The first example makes most of the plots using default functions and ranges - useful as a first call. The second example makes a more detailed contour plot and the third one shows that you can use this program also to produce graphs of arbitrary functions.)

7.7.1: contour

Produces a plot of the lines of equal function values.

Contours are drawn in the part of the viewing plane that is located within the current AREA box.

The contours are labeled with the function value if the LABEL option is active (which is by default the case).

If you request AUTOMATIC scaling of the range, contours are drawn at round values of the function over a range that covers the function values in the current AREA. The number of contours is used to compute a first estimate of the distance between two contours. This distance is rounded downwards to the first 10-fold multiple of 1, 2 or 5. The number of contours actually drawn is therefore usually larger than the number you requested.

The contours are drawn with the representation CONTOUR-NORMAL and are labeled with CONTOUR-LABELS.

[The default function is V and the contours range by default from the highest to the lowest potential present in the cell. By default, 20 contours are plotted.]

7.7.2: graph

The function is evaluated on the track or on the curve specified with the ON keyword.

The geometric aspects of the track, if used, should be set by means of the TRACK command before calling PLOT-FIELD. Other aspects of the track, such as the clustering model, are not used in the present context.

A curve should be parametrised in terms of T which will run from 0 to 1. All 3 coordinates of the curve should be specified. Note that ON expects only one argument, the parametrisation should therefore be enclosed in quotes, e.g.

   on 'cos(pi*t),sin(pi*t),0'

would produce a graph over a semi-circle in the z=0 plane.

The SCALE option can be used to force a vertical scale in the plot, this can for instance be useful if you intend to overlay various graphs.

If you select the PRINT option, then the values plotted in the graph will also be printed out. Rerouting of the output (> file) can be used to write the values to a file.

The number of sampling points can be set with N, default is 200.

[The default function is V.]

7.7.3: histogram

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are entered in an histogram.

This kind of plot can be useful to estimate the field homogeneity, provided the range has been tuned properly.

The automatic search for proper binning (AUTOMATIC) uses the first few entries to set the range. Since the grid is scanned in a regular sequence, these entries are not necessarily representative for the entire sample, in particular if the number of bins is small compared to the grid size. See AUTOSCALE for details on the automatic binning procedure.

[The default function is E. The number of bins is preset to 100 and the range is by default chosen automatically.]

7.7.4: surface

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are presented as a three dimensional plot.

The plot is first rotated by phi degrees around the z-axis and then tilted by theta degrees from the z-axis.

This plot is decorative but it is generally agreed upon that it is hard to extract any meaningful information from it ...

[The default function is V. The default viewing angles are 30 and 60 degrees. The viewing angles are remembered from one call to the next.]

7.7.5: vector

This plot shows the flow of a 3-vector sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The vectors are projected onto the viewing plane.

The z-component is set to 0, if not explicitely specified. For other than (x,y) views, this may give incorrect impressions.

The vectors are normalised in 3 dimensions when they are plotted - the length of the vectors shown does not contain information on the magnitude of the quantity that is plotted. A vector that appears point like has no component in the viewing plane.

If used for (Ex,Ey,Ez), which is the default, one can pick out the location of the zeroes of the field and hence figure out roughly what the acceptance of a wire is.

It is advisable to have roughly equal ranges in view of the scaling that is performed on the vectors.

The vectors are plotted using the FUNCTION-1 representation. The appearance of the arrow is influence by the ARROW-TIP-ANGLE and ARROW-TIP-LENGTH settings.

[The default functions are EX, EY, EZ.]

7.7.6: functions

All functions (f1, f2 ... f7) should be expressions in terms of the following quantities:

Name Meaning
X or R x- or r-Coordinate of a point
Y or PHI y- or phi-Coordinate of a point
Z z-Coordinate of a point
EX or ER x- or r-Component of the electric field at (x/r,y/phi,z)
EY or EPHI x- or phi-Component of the electric field at (x/r,y/phi,z)
EZ z-Component of the electric field at (x/r,y/phi,z)
E Norm of the electric field at (x/r,y/phi,z)
BX x-Component of the magnetic field at (x/r,y/phi,z)
BY y-Component of the magnetic field at (x/r,y/phi,z)
BZ z-Component of the magnetic field at (x/r,y/phi,z)
B Norm of the magnetic field at (x/r,y/phi,z)
V Electrostatic potential at (x/r,y/phi,z)

Note: The variables BX and BY should not be used with cells that have been described in polar coordinates.

Section 7.8: PRINT

Prints a table of a series of field functions (using X, Y or R, PHI and EX, EY or ER, EPHI plus BX, BY, B> if applicable as symbolic names).

This procedure, contrary to e.g. PLOT-FIELD still operates only in the z=0 plane.

A large number of functions may be given as argument but the tables are always for at most 4 functions at the time. This instruction tends to produce a lot of output: one page per 10x10 block of points on the current GRID.

Format:

PRINT f1 f2 ...

Example:

PR EX, EY, E, V

7.8.1: functions

All functions should be expressions in terms of the following quantities:

Name Meaning
X or R x- or r-Coordinate of a point
Y or PHI y- or phi-Coordinate of a point
EX or ER x- or r-Component of the electric field at (x/r,y/phi)
EY or EPHI x- or phi-Component of the electric field at (x/r,y/phi)
E Norm of the electric field at (x/r,y/phi)
BX x-Component of the magnetic field at (x/r,y/phi)
BY y-Component of the magnetic field at (x/r,y/phi)
BZ z-Component of the magnetic field at (x/r,y/phi)
B Norm of the magnetic field at (x/r,y/phi)
V Electrostatic potential at (x/r,y/phi)

Note: The variables BX and BY should not be used with cells that have been described in polar coordinates.

Section 7.9: SAMPLE

Evaluates and prints the field at a single point.

This instruction was used for debugging, but is now superseded by the procedure calls ELECTRIC_FIELD and ELECTRIC_FIELD_3.

Format:

SAMPLE x y

Example:

SAMPLE 0.5 0.5

Section 7.10: SELECT

Selects and groups the electrodes which are to be handled specially. The selection is common to all sections, but the interpretation of the selection is left to the individual instructions.

The selection determines which wires are checked by CHECK.

The grouping is of no importance in this section, and selection of other electrodes than wires has no effect.

Format:

SELECT selection

Example:

SEL (1 S) 2 F

(Put wire 1 together with all S wires in one group, make wire 2 a group of its own and do the same for each of the F wires.)

7.10.1: selection

The selection string can consist of the following elements:

A wire, a plane, the tube and a weighting field map are selected if their label appears in the selection string.

Solids with a label identical to that of a weighting field map are associated with the weighting field map. When an electron or ion hits one of these solids, the signal is classified as "direct" by the SIGNAL command, otherwise the signal is classified as "cross induced" - and it would not be computed unless the CROSS-INDUCED option has been switched on.

One can also select solids with labels that do not match a weighting field map - such solids are not linked with a read-out group, but they are taken into account by such instructions as ARRIVAL-TIME-DISTRIBUTION and DRIFT SOLIDS.

Separators need to be placed only between numeric identifiers, not between labels.

Brackets are used to group electrodes that need collective treatment. For instance, signals are summed over groups of electrodes.

An electrode may be selected only once, further selections are ignored in order to avoid ambiguities in group assignment.

Wires, planes, the tube and weighting field maps can also be selected by numeric identifications as follows:

Identifier Meaning
> 0 Wires
0 Should not occur
-1 Plane at lower x than the wires
-2 Plane at higher x than the wires
-3 Plane at lower y than the wires
-4 Plane at higher y than the wires
-5 Tube
< -5 Field maps

[An initial selection is made in which all electrodes with an "S" label are assigned to a group of their own.]

Section 7.11: TIME

Performs field evaluation at random locations distributed over the current AREA and times them.

Format:

TIME [n]

Example:

TIME 10000

7.11.1: n

Number of times the field evaluation is to be repeated.

[Default: 1000 times]

Section 7.12: TRACK

Defines the track used for the graph made by the PLOT-FIELD instruction.

The TRACK command is shared between all sections and has therefore a rich format. In this section, only the geometrical aspects are used. Particle types and clustering models need not be specified.

Format:

See the TRACK command in the drift section.

Example:

TR -1 -1 -1 1

Chapter 8: &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.

Section 8.1: overview

The instructions of the drift section fall in 4 categories:

This is probably the most intensively used section of Garfield. Before loops and procedure calls became available, many requests for instructions that are variations on existing instructions were made. This has lead to a fair amount of duplication among the instructions.

Setting parameters:

Command Short description
AREA Sets the size and view of the drift area
GRID Grid density for tables and contour plots
INTEGRATION-PARAMETERS Accuracy of diffusion, Townsend integration
LINES Number of drift lines used by x(t) etc.
OPTIONS Debugging options
SELECT Selection of sense wires
TRACK Sets the particle trajectory

Calibration:

Command Short description
ARRIVAL-TIME-DISTRIBUTION x(t) Relations, detailed calculation
MINIMISE Search for the minimum of a function
TABLE Produces a drift time table
TIMING Arrival time distributions for 2D areas
XT-PLOT x(t) Relations, simple variant

Display drift behaviour:

Command Short description
CLUSTERING-HISTOGRAMS Makes histograms of the cluster statistics
DRIFT Plots drift lines and isochrones
GRAPHICS-INPUT Graphics menu driven drift line plotting
LORENTZ-ANGLE Prints the Lorentz angle at a given point
PLOT-FIELD Plots drift related quantities
SINGLE Graphs for a single drift line
SPEED Prints the drift speed at a given point
TIME Timing of drift line calculation

Service instructions:

Command Short description
GET-TRACK Retrieves a prepared track from a file
PREPARE-TRACK Prepares a track of interpolation
WRITE-ISOCHRONES Writes the set of isochrones to a file
WRITE-TRACK Writes a prepared track to a file

Note: There are procedures that perform drift related tasks: AVALANCHE, DRIFT_ELECTRON, DRIFT_ELECTRON_3, DRIFT_MC_ELECTRON, DRIFT_POSITRON, DRIFT_POSITRON_3, DRIFT_MC_POSITRON, DRIFT_ION, DRIFT_ION_3, DRIFT_MC_ION, DRIFT_MC_NEGATIVE_ION, DRIFT_NEGATIVE_ION, DRIFT_NEGATIVE_ION_3, DRIFT_INFORMATION, GET_CLUSTER, GET_DRIFT_LINE, NEW_TRACK, PLOT_DRIFT_AREA, PLOT_DRIFT_LINE, PLOT_TRACK and RND_MULTIPLICATION.

The FIT_GAUSSIAN procedure can be of use when studying the output of the ARRIVAL-TIME-DISTRIBUTION instruction.

Section 8.2: methods

Garfield currently has 3 different integration techniques:

The difference between Monte Carlo and Runge Kutta Fehlberg drifting. In this symmetric chamber, 20 electrons are drifted, from a point, using the Monte Carlo algorithm in the upper half and using Runge Kutta Fehlberg integration in the lower half.

The plot has been made with the following commands:

area -0.11 -0.11 0.11 0.11
int-par mc-dist-int 0.001
all plot_drift_area
For i From 1 To 20 Do
   Call drift_mc_electron(0.005,0.09,0)
   Call plot_drift_line
Enddo
Call drift_electron(0.005,-0.09)
Call plot_drift_line
Call plot_end

8.2.1: velocity

In the absence of a magnetic field, the drift velocity vector for both electrons and ions is parallel with the electric field.

The magnitude of the drift velocity vector is taken from the gas tables. Mainly for historic reasons, the tables list the velocity for electrons and the velocity divided by the field (usually called mobility) for ions, a difference that is of a merely formal nature.

The magnitude of the drift velocity of electrons and the mobility of ions can be entered with the TABLE and ADD gas section commands. Electron velocities can in addition be computed with MAGBOLTZ and MIX.

In the presence of a magnetic field, both electrons and ions experience a force which is perpendicular to both the E field and the B field. In vacuum, particles will follow in general a spiraling trajectory. In chamber gasses however, both electrons and ions undergo frequent scattering as a result of which they move in a straight line. The angle between the line of motion and the E field vector is called Lorentz angle.

The Lorentz angle for electrons can be manually inserted in the gas tables, and it can also be computed. If the angle is present in the tables, then the drift velocity vector is chosen such that:

If the Lorentz angle for electrons is not present in the gas tables, then the drift velocity vector is computed with the formula:

        Q mu     /                    2        \
v = -----------  | E  +  mu ExB  +  mu B (E.B) |
              2  \                             /
    1 + (mu B)
where mu stands for the mobility and Q for the charge.

Since the Lorentz angle for ions can currently not be entered in the gas tables, the same formula is used for ions.

8.2.2: Runge_Kutta_Fehlberg

Runge Kutta Fehlberg integration is initialised with

The method iterates over the following steps:

  1. Given a starting point, the velocity at the starting point, and a time step, compute 2 estimates of the next point on the drift line: These 2 estimates are based on the drift velocity at the starting point and the velocity at only 3 new locations.
  2. The time step is updated by comparing the 2nd and 3rd order estimates with the requested accuracy:
                            accuracy
           dt' =  dt sqrt -----------
                          |z_2 - z_3|
    
  3. The step is repeated if:
  4. The position is updated with the 2nd order estimate.
  5. The velocity is updated according to the end-point velocity of the step, which is one of the 3 velocity vectors that were computed under 1.

The iteration ends when any of the following conditions is satisfied:

The strength of this algorithm is that it takes very long steps in areas where the field is nearly constant and small steps in areas with a varying field. This saves computation time and improves the overall accuracy of the calculation.

The method is well adapted to fields that are smooth, such as analytic potentials. Field maps in contrast are sometimes not even continuous. This algorithm has difficulties coping with such rough maps - the Monte Carlo method is then a better choice.

8.2.3: Monte_Carlo

The Monte Carlo drift line integration method is initialised by:

The method iterates over the following steps:

  1. From the velocity and the time step, compute a step length, assuming the velocity to be constant over the step.
  2. Compute the transverse and longitudinal diffusion coefficients at the starting location, scale with the square root of the step length. Here too, we assume the diffusion is constant over the step.
  3. Generate a diffusion step, with 1 longitudinal component in the direction of the drift velocity and 2 transverse components according to 3 uncorrelated Gaussian distributions.
  4. Update the location by adding the step due to the velocity and the random step due to diffusion.

The iteration ends when any of the following conditions is satisfied:

The most striking difference between Monte Carlo and Runge Kutta integration is that the latter will, for a given starting point, always compute the same path while Monte Carlo integration will lead to different trajectories (provided lateral diffusion is appreciable).

Monte Carlo integration is intrinsically robust and is therefore well suited when integrating non-smooth fields such as those encountered in field maps.

The Monte Carlo method is also to be prefered for very small scale detectors at the scale of the diffusion.

However, care must be taken to adjust the step size. If the steps are too large, the method is inaccurate. If they are too small, the maximum number of steps will be reached before the particle has reached an electrode.

8.2.4: diffusion

Diffusion is primarily a spatial effect. While a particle drifts, it will on average follow the drift velocity vector, both in direction and in speed. Additionally, it will be scattered transversely, an effect known as transverse diffusion, and it will at times move a bit slower or faster, an effect known as longitudinal diffusion.

The transverse component of diffusion, usually the largest of the two, will make a particle follow a trajectory that differs from the mean. Longitudinal diffusion will only have an effect on the drift time.

If diffusion does not cause the particles starting at one and the same point to reach different electrodes, the dominant effect of diffusion is a fluctuation in arrival time. One should note that this fluctuation is not only due to the longitudinal part of diffusion - also the transverse part plays a role.

Garfield offers several methods to estimate the effect of diffusion:

8.2.4.1: longitudinal

Integration of the longitudinal coefficient alone is normally only performed when the drift line has been computed with the Runge_Kutta_Fehlberg integration method and when in addition the transverse diffusion coefficient is not known.

When the transport properties of a gas have been computed with MAGBOLTZ, then transverse diffusion coefficients are stored - unless they have subsequently been deleted with the RESET command of the gas section.

Such integration can explicitely be requested by calling procedures like DRIFT_ELECTRON after having deleted the transverse diffusion data, if needed. Since the DRIFT command by default uses Runge-Kutta-Fehlberg integration, the diffusion graph made by the DRIFT TRACK command, is computed with this technique if the transverse diffusion is absent.

The computed quantity, the spread in arrival time, is estimated by integrating quadratically the ratio of longitudinal diffusion coefficient and drift velocity over the drift path:

      2                             2
spread   =  integral   (sigma/speed)  dz

The integration is performed using the Newton-Raphson technique over each step of the drift line, repeatedly bisecting a step until either the maximum stack depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction eps of the trapezoidal estimate without bisection of the integral over the entire path.

8.2.4.2: cloud

If a drift line has been computed with the Runge_Kutta_Fehlberg integration method, and provided both the longitudinal and transverse diffusion coefficient are known, then the diffusion spread is computed by propagating a probability distribution along the drift path.

Starting from a delta distribution at the starting point, the cloud is adjusted at each step according to the following phenomena:

The cloud is considered Gaussian at every stage.

When the centre of the cloud comes closer than ncloud wire radii to a wire, the cloud is projected onto the wire using one of several methods.

8.2.4.3: Monte_Carlo

Monte_Carlo integration includes a simulation of the diffusion process.

8.2.5: multiplication

The gas multiplication over a drift path is estimated as the exponentiated integral of the Townsend coefficient over the path:

     integral alpha dz
M = e

The integration is performed using the Newton-Raphson technique over each step of the drift line, repeatedly bisecting a step until either the maximum stack depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction eps of the trapezoidal estimate without bisection of the integral over the entire path.

The integral of the Townsend coefficient over a drift path computed with the Monte_Carlo technique is larger than the integral over a drift path from the same point computed with the Runge_Kutta_Fehlberg method. The reason for this difference is that the path length for Monte Carlo integration is larger than for RKF integration.

Magboltz computes Townsend coefficients for use with an RKF path. The PROJECTED-PATH-INTEGRATION integration parameter can in certain contexts be used to reduce the step size dependence of the integral over Monte Carlo paths.

8.2.6: attachment

The attachment losses over a drift path are estimated as the exponentiated integral of the attachment coefficient over the path:

      - integral eta dz
L = e

The integration is performed using the Newton-Raphson technique over each step of the drift line, repeatedly bisecting a step until either the maximum stack depth has been reached, or until the difference between the trapezoidal and the quadratic estimate over a section becomes less than a fraction eps of the trapezoidal estimate without bisection of the integral over the entire path.

The integral of the attachment coefficient over a drift path computed with the Monte_Carlo technique is larger than the integral over a drift path from the same point computed with the Runge_Kutta_Fehlberg method. The reason for this difference is that the path length for Monte Carlo integration is larger than for RKF integration.

Magboltz computes attachment coefficients for use with an RKF path. The PROJECTED-PATH-INTEGRATION integration parameter can in certain contexts be used to reduce the step size dependence of the integral over Monte Carlo paths.

8.2.7: status

All drift line integration routines return status information which tells what happened to the particle that has been drifting.

When the integration routines are called through commands, the status is, on request, printed as part of the output. If the routines are called via procedures, then the status is usually one of the output arguments.

The status is usually shown or returned as a string, shown in the second column of the table below. Occasionally however, a numeric status code is returned, shown in the third column.

The DRIFT_INFORMATION procedure returns on request the status of the last drift line that has been computed in either of these 2 formats.

Drift line ended because ... Status string Numeric status code
Particle left the drift area Left the drift area -1
More than MXLIST steps Too many steps -2
Various faults Calculations abandoned -3
Hit an equipotential plane Hit a plane -4
Entered a dielectricum Left drift medium -5
Left the finite element mesh Left the mesh -6
Hit the plane on the left Hit the minimum x plane -11
Hit the plane on the right Hit the maximum x plane -12
Hit the plane on the bottom Hit the minimum y plane -13
Hit the plane on the top Hit the maximum y plane -14
Hit the tube wall Hit the tube -15
Hit a wire of type X Hit X wire N 1 ... MXWIRE
Hit a replica of an X-wire Hit a replica of X wire N MXWIRE+1 ... 2*MXWIRE
Ended in a solid of type X Hit X solid N 2*MXWIRE+1 ... 2*MXWIRE+MXSOLI
Other cases (shouldn't occur) Unknown other

The "X" in the status code for wires, replicas of wires and solids is replaced by the corresponding wire label or the corresponding solid label (see SOLIDS). "N" is replaced by the respective sequence number.

Section 8.3: AREA

Changes the area in which electrons and ions are allowed to drift. This is also the part of the chamber that is plotted.

Formats:

See the AREA command in the field section.

Section 8.4: ARRIVAL-TIME-DISTRIBUTION

Computes the arrival time distribution of the n'th electron that reach electrodes from a series of tracks. A by-product of this calculation is the x(t) relation and an estimate of the arrival time spread. See XT-PLOT for a comparison with related commands.

Before issuing this command, you should take care of the following:

By default, this command operates in the x-y plane, but it can also work in the y-z and z-x planes. The choice is controled with the STEP and SCAN keywords.

Another important argument is ELECTRON.

Format:

ARRIVAL-TIME-DISTRIBUTION ...
     [ELECTRON {electron | LAST | ONE-BUT-LAST | ... }] ...
     [THRESHOLD threshold] ...
     [TIME-WINDOW {AUTOMATIC | FULL-RANGE | tmin tmax }] ...
     [STEP {X | Y | Z} ...
           [RANGE umin umax] ...
           [INCREMENT ustep]] ...
     [SCAN {X | Y | Z} ...
           [RANGE vmin vmax] ...
           [ANGLE phi]] ...
     [OFFSET w] ...
     [LINES lines] ...
     [DIFFUSION | NODIFFUSION] ...
     [ATTACHMENT | NOATTACHMENT] ...
     [DATASET dsname [member]] [REMARK remark] ...
     [BINS bins] ...
     [ITERATIONS iterations] ...
     [POLYNOMIAL-ORDER order] ...
     [NOKEEP-HISTOGRAMS | KEEP-HISTOGRAMS] ...
     [NOKEEP-RESULTS | KEEP-RESULTS] ...
     [NOPLOT-ALL-ELECTRONS | PLOT-ALL-ELECTRONS] ...
     [NOPLOT-SELECTED-ELECTRONS | PLOT-SELECTED-ELECTRONS] ...
     [NOPRINT-ALL-ELECTRONS | PRINT-ALL-ELECTRONS] ...
     [NOPRINT-SELECTED-ELECTRONS | PRINT-SELECTED-ELECTRONS] ...
     [PLOT-OVERVIEW | NOPLOT-OVERVIEW]

If you don't manage to fit all this on a single line, remember that an instruction can be split over several lines by putting an ellipsis at the end of each line but the last.

Example:

TRACK EXPONENTIAL
ARRIVAL ELECTRON 5 LAST DATASET "arrival/electron.5" THRESH 0.8

The track type is set to EXPONENTIAL-SPACING, i.e. the mean number of clusters per cm and the cluster size distribution from the gas section are used. One could also ask for HEED, to simulate a particle. The arrival time distribution of the 5th and of the last electron are computed. A file is written that contains the the time by which 80 % of these electrons have reached the electrode.

8.4.1: plane

This command works in either the x-y, the y-z or the z-x plane, optionally with a constant OFFSET in the 3rd direction.

In all 3 cases, one of the 2 axes of the plane, the one that we call here "stepping axis" serves as coordinate in the calibration curve. The tracks cross a line through the centre of the electrode being studied and parallel to the stepping axis at multiples of a user-defined INCREMENT.

The axis which should serve as stepping axis is identified with the STEP keyword. You can set the RANGE of coordinates along the stepping axis for which tracks should be generated.

The other axis in the plane is called "scanning axis". The tracks can be at an ANGLE to this axis, but will usually be parallel to it.

The axis which should serve as stepping axis is identified with the SCAN keyword. Like for the stepping axis, You can limit the RANGE of coordinates along the stepping axis.

8.4.2: electron

The electrons on which you trigger. These are usually small numbers, around 5, but you are free to choose larger values. You may list several electrons, up to a compilation dependent limit (currently set to 10).

In the rest of the descriptions, these electrons are referred to as the 'selected electrons'.

If a value is negative, then the electrons will be counted from the back, the last electron corresponds to a value of 0. For the 4 last electrons, you can also type LAST, ONE-BUT-LAST, TWO-BUT-LAST and THREE-BUT-LAST.

[Default: initially, only the 25th electron is selected. The set of selected is remembered as default for the next call.]

8.4.3: threshold

A probability between 0 and 1 (both excluded). Apart from the mean arrival time of the selected electron, Garfield outputs also the time at which the selected electron has a given probability to have arrived.

[Default: initially 0.5, the median of the distribution. The value set is kept as default for the next call.]

8.4.4: TIME-WINDOW

Whilst the program can compute reasonable bounds for the overall arrival time distribution histogram, it can not do so for the histogram of the selected electron.

You have, for these histograms, the choice between:

If you specify an explicit time window, then this time window is also used for the all-electrons arrival time histogram. Otherwise, these histograms are booked with the full time range of the track.

Setting a time window is most useful in conjunction with the KEEP-HISTOGRAMS option when you wish to study the histograms in more detail by other programs.

[Default: by default the time range of the selected electron histogram is computed from the first 100 entries of this histogram, whereas the range of the all-electron histogram is set to the time range for the track under study.]

8.4.4.1: AUTOMATIC

When requesting AUTOMATIC, Garfield books an histogram for the selected electron arrival distributions with automatic range setting.

Automatic range calculation means that the first entries are used to compute a suitable range.

The number of entries used to set the scale is equal to half the number of bins of the histograms. You should ensure that the number of track iterations is at least equal to half the number of bins.

8.4.4.2: FULL-SCALE

If you wish the selected electron arrival time distribution histogram to have the same range as the histogram with the distribution for all electrons, then you should specify FULL-SCALE.

Keep in mind, if you do so, that the accuracy of the median arrival time of the selected electron can be reduced because the arrival time distribution is likely to cover only a small fraction of the range of the histogram.

8.4.5: STEP

Determines, together with SCAN, the plane in which the tracks will be located.

Tracks are usually perpendicular to the stepping axis and at regularly spaced distances from the centre of the electrode. The distance between 2 successive tracks, measured along the stepping axis, can be set with INCREMENT. The part of the stepping axis for which tracks are to be generated can be set with RANGE.

The stepping axis must be either the x-, the y- or the z-axis and must be distinct from the scanning axis.

[By default: X]

8.4.5.1: RANGE

The part of the stepping axis to be covered by the tracks.

The range is specified in the usual coordinate system, not relative to the electrodes.

[Default: the entire stepping axis as given by AREA.]

8.4.5.2: INCREMENT

The distance, measured along the stepping axis, between 2 tracks.

[Default: approximately 5 % of the stepping range.]

8.4.6: SCAN

Determines, together with STEP, the plane in which the tracks will be located.

Tracks are usually parallel to the scanning axis, or at a small ANGLE to it.

The scanning axis must be either the x-, the y- or the z-axis and must be distinct from the stepping axis.

[By default: Y]

8.4.6.1: RANGE

The extent of the tracks along the scanning axis.

The range is specified in the usual coordinate system, not relative to the electrodes.

If the scanning range does not cover the full acceptance of an electrode, some of the electrons to reach the electrode in the real chamber, will be absent in the simulation.

If the range is chosen too large, the accuracy suffers unless the LINES parameter is set to a high value. Moreover, considerable waste of CPU time occurs.

[Default: the entire scanning range as given by AREA.]

8.4.6.2: ANGLE

The angle of the tracks with respect to the scanning-axis.

[Default: initially 0 degrees. The angle that you set is kept as default for the next call.]

8.4.7: OFFSET

By default, this command works in a plane that contains the origin.

If you wish to compute arrival time distributions in a parallel plane, then specify OFFSET followed by the 3rd coordinate of the plane.

8.4.8: DIFFUSION

By default, diffusion is included in the arrival time calculations. If you wish to study the impact diffusion has on the distributions, then it may be convenient to be able to switch diffusion off. This can be achieved by selecting the NODIFFUSION option.

8.4.9: ATTACHMENT

Depending on the presence of attachment data or not, attachment is or is not included. If attachment data is present, but if you do not want the effect to be taken into account, then you can specify NOATTACHMENT.

8.4.10: LINES

Each track is first 'prepared': from regularly spaced points on the track, electrons are drifted and the drift times and integrated diffusion coefficients are stored for interpolation when doing the Monte-Carlo cycles. Where the drift time changes most between 2 points, additional drift lines are calculated.

The parameter lines is the total amount of drift lines that are calculated this way: 75 % in the first step and 25 % in the second.

[Default: the LINES parameter from the drift section.]

8.4.11: bins

The number of bins in the histograms used to compute the time at which the selected histogram has a given probability to have arrived - the mean arrival time is computed directly without histogram.

[Default: initially half of MXLIST, usually 100-500 bins. The value that you set is kept as default for the next call.]

8.4.12: KEEP-HISTOGRAMS

This option can be used to store the arrival time histograms for later study. The histograms are made accessible via global variable names that are displayed while the command is carried out (SEL_n, and ALL_n with n a counter).

A common application of this option seems to be the Gaussian fit of the arrival time histograms. This can be done using the FIT_GAUSSIAN procedure, or by a user program after writing the histograms out with the WRITE_HISTOGRAM procedure.

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

[Default: histograms are not kept. The setting is kept across calls of ARRIVAL.]

8.4.13: KEEP-RESULTS

If this option is selected, then the x(t) relations that have been obtained by ARRIVAL, will be stored as a set of matrices and numbers:

Global Description Type
[X|Y|Z]_<electrode> Distance from electrode Matrix
MEAN_<electrode> mean time all electrons Matrix
MEDIAN_<electrode> median time all electrons Matrix
RMS_<electrode> RMS time all electrons Matrix
MEAN<electron>_<electrode> mean time selected electron Matrix
MEDIAN<electron_<electrode> median time selected electron Matrix
RMS<electron>_<electrode> RMS time selected electron Matrix
E_<electron> sequence # selected electron Number

The string "<electrode>" in the global variable name is set to 1 for the first selected electrode, 2 for the next etc.

The string "<electron>" is an index that runs from 1 to the number of selected electrons. E_<electron> shows which electron a given index corresponds to. This can be zero or a negative number: 0 means the last electron, -1 the one but last etc.

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

[This option is not on by default, but its setting is remembered from one call to the next.]

8.4.14: iterations

The number of Monte Carlo loops over track generation. These loops consume relatively little CPU time since the drift times, diffusion coefficients etc are all taken from interpolation tables.

It seems therefore tempting to select a large value for this parameter. When saving the distributions (KEEP-HISTOGRAMS) and then using them in a fit, this may indeed be a good approach. However, when extracting information from the MC process with means and RMS, the accuracy tends to degrade for large values of loop, mainly because of single entries with very deviating values.

When specifying SINGLE-CLUSTER, only one cluster is generated per track, as a result the default value will be low and you are advised to choose a larger value in this case.

[Default: initially 1000. Each ARRIVAL statement has as default the value set in the previous invocation.]

8.4.15: order

The time by which the selected electron has a certain probability to have arrived, is obtained by reverse polynomial interpolation in the cumulative timing histogram. Using this keyword, you can change the order of the polynomial.

For the lower orders, you may also specify the keywords LINEAR, QUADRATIC or PARABOLIC and CUBIC.

Although values between 1 and 10 are accepted, orders larger than 2 are not recommended since they tend to lead to oscillation.

[Default: 2, parabolic interpolation. The setting will be remembered from one call to the next.]

8.4.16: DATASET

Requests output of a summary of the calculations to a dataset.

[Dataset output is only done on request.]

8.4.16.1: dsname

The name of the dataset you wish to write your results to. If you don't specify such a dataset name, you will only receive plots and no numeric output.

[Default: By default no dataset is written.]

8.4.16.2: member

The name to be assigned to the member.

[Default: none.]

8.4.16.3: remark

Garfield uses by default a string specifying the electrode as remark for the member header. You may override this.

8.4.17: plot_options

You have control over the volume of the graphics output with the plot options.

The PLOT-SELECTED-ELECTRONS and PLOT-ALL-ELECTRONS options tend to lead to very bulky output, but these plots can be instructive.

8.4.17.1: PLOT-SELECTED-ELECTRONS

Plots, for each track location, and for each selected electron, an histogram of the arrival time and an histogram of the origin of the selected electrons.

The time range of these histograms can be controled with TIME-WINDOW.

You can request printouts of these histograms with PRINT-SELECTED-ELECTRONS or ask the histogram to stay in memory with the KEEP-HISTOGRAMS option.

[These plots are not made by default. The default setting of each call is the setting of the previous call.]

8.4.17.2: PLOT-ALL-ELECTRONS

Plots, for each track location, an histogram of the arrival time and an histogram of the origin of all electrons.

The time range of these histograms can be controled by TIME-WINDOW, provided you set an explicit time window.

You can request printouts of these histograms with PRINT-ALL-ELECTRONS or ask the histogram to stay in memory with the KEEP-HISTOGRAMS option.

[These plots are not made by default. The default setting of each call is the setting of the previous call.]

8.4.17.3: PLOT-OVERVIEW

The PLOT-OVERVIEW option will ensure that the following 3 graphs are made:

  1. The mean drift time of all electrons and the mean drift time of the selected electrons.

    This graph is a more refined version of the x(t) relation as calculated by the XT-PLOT instruction.

  2. The drift time by which any electron has a probability of threshold to have arrived and the drift time by which the selected electrons have this probability to have arrived.

    Since the threshold is usually set to 50 %, this probability is in practice equivalent to the median.

  3. The spread of the arrival time distribution of all electrons, and the spread of the arrival time distributions of the selected electrons.

    The spread in shown in this graph is the standard deviation of the arrival time histogram. This measure is sensitive to outliers, and should not be used for delicate studies of the resolution. The KEEP-HISTOGRAMS option can be used to store the histograms, more robust techniques can then be applied outside Garfield.

In all plots, the all-electron graphs are plotted with the graphics representation FUNCTION-1, while the graphs for the selected electrons are plotted as FUNCTION-2.

The results are kept in memory if you specify the KEEP-RESULTS option.

[These plots are initially made by default. The default setting of each call is the setting of the previous call.]

8.4.18: print_options

These options provide the same output as the plot_options, but the printout contains additional information such as the mean and RMS. These quantities are computed from the entries themselves, not from the accumulated bin contents. The internal arithmetic is done in double precision.

[The setting is remembered from one call to the next.]

8.4.18.1: PRINT-SELECTED-ELECTRONS

Prints, for each track location, and for each selected electron, an histogram of the arrival time and an histogram of the origin of the selected electrons.

The time range of these histograms can be controled with TIME-WINDOW.

You can request plots of these histograms with PLOT-SELECTED-ELECTRONS or ask the histogram to stay in memory with the KEEP-HISTOGRAMS option.

[These printouts are not made by default. The default setting of each call is the setting of the previous call.]

8.4.18.2: PRINT-ALL-ELECTRONS

Prints, for each track location, an histogram of the arrival time and an histogram of the origin of all electrons.

The time range of these histograms can be controled by TIME-WINDOW, provided you set an explicit time window.

You can request plots of these histograms with PLOT-ALL-ELECTRONS or ask the histogram to stay in memory with the KEEP-HISTOGRAMS option.

[These printouts are not made by default. The default setting of each call is the setting of the previous call.]

8.4.18.3: PRINT-OVERVIEW

The option is accepted but has no effect.

To obtain a printout, use DATASET output.

Section 8.5: CLUSTERING-HISTOGRAMS

Makes a set of histograms that show some aspects of the cluster statistics:

These histograms are of use mainly if Heed is used to generate tracks. Keep the following in mind in this respect:

Format:

CLUSTERING-HISTOGRAMS ...
     [ITERATIONS  iter] ...
     [BINS  bins] ...
     [CLUSTER-SIZE-BINS  bins] ...
          [CLUSTER-SIZE-RANGE  {AUTOMATIC | min max}] ...
     [CLUSTER-COUNT-BINS  bins] ...
          [CLUSTER-COUNT-RANGE  {AUTOMATIC | min max}] ...
     [CLUSTER-ENERGY-BINS  bins] ...
          [CLUSTER-ENERGY-RANGE  {AUTOMATIC | min max}] ...
     [DELTA-RANGE-BINS  bins] ...
          [DELTA-RANGE-RANGE  {AUTOMATIC | min max}] ...
     [TRACK-RANGE-BINS  bins] ...
          [TRACK-RANGE-RANGE  {AUTOMATIC | min max}] ...
     [ENERGY-LOSS-BINS  bins] ...
          [ENERGY-LOSS-RANGE  {AUTOMATIC | min max}] ...
     [NOKEEP-HISTOGRAMS | KEEP-HISTOGRAMS] ...
     [PLOT-HISTOGRAMS | NOPLOT-HISTOGRAMS]

8.5.1: iter

The number of tracks to be generated.

[By default 200]

8.5.2: bins

Number of bins in the histograms.

One can either set the same number of bins for all histograms using the BINS keyword, or set a different number for each of the 6 histograms that are produced.

[By default 100]

8.5.3: range

The range of the histograms is by default determined automatically using the first entries of the histogram.

You may, e.g. for comparison purposes, wish to set the same range for all histograms. This can be accomplished with the various RANGE options.

[By default automatic range selection for all histograms.]

8.5.4: KEEP-HISTOGRAMS

Requests the histograms to be kept in storage when the instruction has finished. The histograms will be called as follows:

Name Description
SIZE Number of electrons in a cluster
CLUSTERS Number of clusters on the track
DELTA Distance between track and electrons [cm]
RANGE Distance between track start and last electron [cm]
DE Total energy loss [MeV]
ECLUSTER Energy per cluster [eV]

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

[The histograms are not kept by default, the setting of this option is remembered from one call to the next.]

8.5.5: PLOT-HISTOGRAMS

This command by default plots the histograms it computes. If this is not desirable, e.g. because you only need the histograms as a set of globals, then adding NOPLOT-HISTOGRAMS suppresses the plots.

[The plots are made by default, the setting is remembered from one call to the next.]

Section 8.6: DRIFT

This instruction makes plots of electron and ion drift lines and can also plot isochrones.

The main choice is between the 5 kinds of starting points:

Each has a set of sub-options that should follow the EDGES, SOLIDS, WIRES, TRACK or ZERO keyword. The other options should be placed at the end of the line.

Format:

DRIFT {EDGES  [LEFT | NOTLEFT] ...
              [RIGHT | NOTRIGHT] ...
              [UP | NOTUP] ...
              [DOWN | NOTDOWN] ...
              [LINES lines]                                    | ...
       TRACK  [NOTIME-GRAPH | TIME-GRAPH] ...
              [NOVELOCITY-GRAPH | VELOCITY-GRAPH] ...
              [NODIFFUSION-GRAPH | DIFFUSION-GRAPH] ...
              [NOAVALANCHE-GRAPH | AVALANCHE-GRAPH] ...
              [NOFUNCTION-GRAPH | FUNCTION-GRAPH function] ...
              [MARKER | SOLID]                                 | ...
       SOLIDS [LINES lines]                                    | ...
       WIRES  [LINES lines]                                    | ...
       ZERO                                                    } ...
       [RUNGE-KUTTA-DRIFT | MONTE-CARLO-DRIFT] ...
       [NOISOCHRONES | ISOCHRONESdelta_t] ...
       [LINE-PLOT | NOLINE-PLOT] ...
       [NOLINE-PRINT | LINE-PRINT] ...
       [ELECTRON | ION] ...
       [NEGATIVE | POSITIVE]

If you don't manage to fit all this on one line, remember you are allowed to abbreviate. A line that ends on an ellipsis continues on the next line.

Examples:

DRIFT WIRES LINES=25 ISOCHRONES 0.1 NOL-PL
DRIFT TRACK FUNCTION-GRAPH TIME+5*DIFFUSION NOL-PL L-PR
DRIFT ZERO

(The first example will plot only a set of isochrones computed using 25 drift lines from each of the selected wires. The second example prints a table of drift times etc. and plots the drift time plus five times the diffusion. The last example shows the acceptance boundaries.)

8.6.1: EDGES

Indicates that the drift line calculation will begin at some of the boundaries of the drift area as set by AREA.

You can select the edges from which drift lines should start and you can also set the number of drift lines from each edge with the LINES keyword.

An example of an EDGES drift line plot, made with the following command:

drift edge left right notup notdown isochrone 0.02

8.6.1.1: sides

Specifies from which of the 4 sides particles will be drifted.

You can select the sides with one or more of the keywords listed in the table below. The keywords are processed in sequence, to obtain drift lines only from the top, one could specify NONE DOWN.

Options Negation Meaning
LEFT NOTLEFT From the right to the left
RIGHT NOTRIGHT From the left to the right
UP NOTUP Upwards from the bottom
DOWN NOTDOWN Downwards from the top
HORIZONTAL NOTHORIZONTAL From the left and the right
VERTICAL NOTVERTICAL From the top and bottom
ALL NONE From all 4 borders

[Default: HORIZONTAL.]

8.6.1.2: lines

The number of drift lines from each edge.

A similar option exists for WIRES and SOLIDS, but separate settings are maintained for each type of plot.

Please note that this LINES option has no link anymore with the LINES command in the drift and signal sections.

[Default: initially set to 20, the setting is remembered from one call of DRIFT to the next.]

8.6.2: SOLIDS

Requests that the electrons or ions start to drift from the intersection between the SELECTed solids and the viewing plane.

You can control the number of drift lines from each solid with the LINES keyword.

ELECTRONs are usually not produced near the electrodes and they are therefore drifted by default 'in reverse', i.e. with a positive charge. The resulting plot shows the origin of all electrons that can end up on the electrode.

Since IONs are normally produced near the electrode surface, they are drifted in their usual mode, i.e. with a positive charge. The resulting plot therefore shows where ions go that are produced in an avalanche at the electrode.

To modify this behaviour, i.e. to study electrons drifting away from electrodes that repel electrons and ions drifting away from electrodes that attract ions, use the POSITIVE and NEGATIVE options.

A SOLIDS drift line plot made with a finite element field map of the read-out structure of a TPC.

drift solid lines 50 ion positive contour 10 l-pl nol-pr
Solids have been defined to represent the octagonal cathode, the gating structure (top of the figure) and the avalanche wire, at the origin. The drift lines start from the wire. The plot has been made with the default isochrone settings.

8.6.2.1: lines

The number of drift lines from each wire.

A similar option exists for EDGES and SOLIDS, but separate settings are maintained for each type of plot.

Please note that this LINES option has no link anymore with the LINES command in the drift and signal sections.

[Default: initially set to 20. The setting is remembered from one call to the next.]

8.6.3: WIRES

Requests that the electrons or ions start to drift from the surfaces of the wires that have been SELECTed.

You can control the number of drift lines from each wire with the LINES keyword.

ELECTRONs are usually not produced near the wires and they are therefore drifted by default 'in reverse', i.e. with a positive charge. The resulting plot shows the origin of all electrons that can end up on the wire.

Since IONs are normally produced near the wire surface, they are drifted in their usual mode, i.e. with a positive charge. The resulting plot therefore shows where ions go that are produced in an avalanche at the wire.

To modify this behaviour, i.e. to study electrons drifting away from wires that repel electrons and ions drifting away from wires that attract ions, use the POSITIVE and NEGATIVE options.

An example of a WIRES drift line plot, made with the following command:

int-par iso-connect 0.1
drift wire lines 30 isochrone 0.02
The distance over which isochrone segments are connected has been limited in this example for clarity, See ISOCHRONE-CONNECTION-THRESHOLD for more information on this.

8.6.3.1: lines

The number of drift lines from each wire.

A similar option exists for EDGES and SOLIDS, but separate settings are maintained for each type of plot.

Please note that this LINES option has no link anymore with the LINES command in the drift and signal sections.

[Default: initially set to 20. The setting is remembered from one call to the next.]

8.6.4: TRACK

Indicates that the drift line calculation will begin on the track.

The resulting plot depends to a large extent on the clustering model you have selected with the TRACK command:

Unlike drifting from solids, edges or wires, DRIFT TRACK does not take its number of lines from a LINES keyword.

Although permitted, the ION option is not meaningful used together with the latter two clustering models.

An example of a TRACK drift line plot, made with the following command:

track -2.9 0.9 2.9 0.9 muon energy 1 GeV
drift track noisochrone
This figure shows a Heed simulation of a 1 GeV muon in Argon-ethane, see HEED for more information on this.

8.6.4.1: graph

The following graphs can be produced:

The graphs can be customised with the FUNCTION-GRAPH option which takes as argument a function using the following symbolic parameters:

Variable Meaning Unit
LENGTH drift line path length cm
DIFFUSION integrated diffusion microsec
AVALANCHE multiplication factor numeric

Care should be taken that the AREA is chosen sufficiently large to let the particles reach their target.

You may switch of the printing and plotting of both drift lines and the plotting of isochrones if you're only interested in the graph.

The graph is drawn either as a line or as a set of markers, depending on the setting of the MARKER and SOLID options.

[By default, no graphs are produced. The set of requested graphs is remembered from one call to the next.]

8.6.4.2: MARKER

The options MARKER and SOLID determine the way the graphs are plotted.

MARKER means that all points are represented by small symbols, e.g. crosses. The symbol that is chosen, as well as its size and colour are taken from polymarker representation FUNCTION-1.

SOLID means that they are joined by straight line segments. The line type, width and colour are taken from polyline representation FUNCTION-1.

[The initial default is SOLID.]

8.6.5: ZERO

Indicates that the drift line are calculated from the zeroes of the electrostatic field, both in the attracting and in the repelling directions.

The ELECTRON/ION and POSITIVE/NEGATIVE settings are ignored. This choice is useful when you're determining the precise acceptance boundaries for each of the wires.

Note: zero finding is not available yet in the default version of Garfield.

8.6.6: RUNGE-KUTTA-DRIFT

Requests the use of the Runge_Kutta_Fehlberg algorithm for computing drift lines.

Runge Kutta integration is easier to use than Monte Carlo stepping in that the integration parameters are more tolerant.

The parameters controling the accuracy are adjusted for chambers that are several centimeters large. When studying much smaller structures, at the micron scale, one may wish to request more accuracy.

The Runge Kutta algorithm is well suited for smooth fields, such as those obtained with analytic potentials. The field computed from field maps is sometimes not even continuous, and one should in such cases prefer the Monte Carlo algorithm.

[The initial default is RUNGE-KUTTA-DRIFT.]

8.6.7: MONTE-CARLO-DRIFT

Requests Monte_Carlo calculation of a drift path, instead of a Runge Kutta Fehlberg integration.

This option is particularly interesting used in conjuction with drifting from a TRACK and on which clusters are generated with HEED.

When using this option, care has to be taken that the step_size has been set to a value appropriate to the chamber.

[The initial default is RUNGE-KUTTA-DRIFT.]

8.6.8: ISOCHRONES

Requests calculation and plotting of isochrones. You must specify the interval, in microsec, after the ISOCHRONES keyword.

The appearance of the isochrones is affected by:

Plotting isochrones can be a CPU intensive operation, depending on the number of drift lines, the number of isochrones and the options that have been chosen.

In order to plot only the isochrones and not the drift lines, one uses ISOCHRONES in conjunction with NOLINE-PLOT.

The drift time used for the isochrones is measured from the wire or the solid where the electron or ion ends up. Isochrones are only plotted for electrons and ions that do reach a wire or a solid. Isochrones are not plotted for particles that reach a replica of a wire (in case of periodic chambers).

Note that isochrones can also be obtained with TABLE CONTOUR and with PLOT-FIELD CONTOUR TIME. These commands do not take the end-point of the electrons into account, and as a result may produce isochrones joining points leading to different wires or solids.

[Isochrones are by default not plotted.]

8.6.9: LINE-PLOT

Requests plotting of the drift lines. You may wish to switch this option off if you want to see only isochrones.

Electron drift lines are plotted with the representation E-DRIFT-LINE and ion drift lines with ION-DRIFT-LINE.

[This option is initially on.]

8.6.10: LINE-PRINT

Requests printing of drift line summary data.

This option is not compatible with LINE-PLOT in interactive VM/CMS (because of system shortcomings) unless the output has been rerouted (> dsname).

This option is initially off.

8.6.11: ELECTRON

Requests drifting of electrons.

8.6.12: ION

Requests drifting of ions.

8.6.13: POSITIVE

By default, electrons are drifted with negative charge and ions with positive charge. If you wish to see the origin of the electrons and ions arriving at a given position, you may wish to reverse the sign.

The POSITIVE option forces the charge to be positive, no matter whether the particle is an electron or an ion.

[The default setting of this option depends on the context.]

8.6.14: NEGATIVE

By default, electrons are drifted with negative charge and ions with positive charge. If you wish to see the origin of the electrons and ions arriving at a given position, you may wish to reverse the sign.

The NEGATIVE option forces the charge to be negative, no matter whether the particle is an electron or an ion.

[The default setting of this option depends on the context.]

Section 8.7: GET-TRACK

Retrieves a prepared track from a dataset written by WRITE-TRACK. This saves time since one doesn't have to run PREPARE-TRACK again.

Format:

GET-TRACK dsname [member]

Example:

GET-TR lib

(This call will retrieve the first prepared track in the dataset LIB.DAT, which may contain members of different type as well.)

8.7.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

8.7.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

Section 8.8: GRAPHICS-INPUT

Enters a graphics menu driven mini drift section. The edges of the AREA and the TRACK can very easily be changed by simply pointing to them. Typical calculations include a single drift line from a point indicated on the screen, drift lines from the TRACK and drift lines from a wire (and its periodic repetitions) selected on the screen.

You have some control over the graphics input mode with the options listed below.

Format:

GRAPHICS-INPUT [CHOICE-PET chpet] [LOCATOR-PET locpet1 locpet2] ...
               [PICK-PET pickpet] [VALUATOR-PET valpet] ...
               [CHOICE-DEVICE chdev] [LOCATOR-DEVICE locdev] ...
               [PICK-DEVICE pickdev] [VALUATOR-DEVICE valdev] ...
               [WORK-STATION wkid]

Example:

GRA LOC-PET 1 4

Chooses rubber band for the second point.

8.8.1: prompt_echo

The prompt-echo type (PET) determines the way the initial value is shown and how you can choose a new one. For a position, for instance, you have the choice between cross hairs, a marker, a rubber band etc.

The PET can be chosen independently for each input mode.

8.8.1.1: CHOICE-PET

Used for menus.

8.8.1.2: LOCATOR-PET

Used to choose a specific point. Here you have to specify 2 values: one for the initial point, another for the final point if applicable. The final point of an area has by default a rubber band PET.

8.8.1.3: PICK-PET

Used to select a wire.

8.8.1.4: VALUATOR-PET

Used to enter a value.

8.8.2: device

The device number via which you wish to enter input for a given mode.

8.8.2.1: CHOICE-DEVICE

Used for menus.

8.8.2.2: LOCATOR-DEVICE

Used to choose a specific point.

8.8.2.3: PICK-DEVICE

Used to select a wire.

8.8.2.4: VALUATOR-DEVICE

Used to enter a value.

8.8.3: WORK-STATION

The identifier of the work station that is to execute the various operations. This is at present the same workstation for each of the input modes.

Section 8.9: GRID

Chooses the x (or r) and y (or phi) density of the grid inside the AREA from which instructions like TABLE will calculate drift lines.

The grid is common to all sections.

Format:

GRID  number_of_steps_in_x  [number_of_steps_in_y]

Example:

GRID 10 20

8.9.1: number

Number of equal grid divisions.

You may supply either 1 or 2 arguments. If the 2nd argument is omitted the first value will be used for both the x (or r) and the y (or phi) spacing.

[Default is 25 for both.]

Section 8.10: INTEGRATION-PARAMETERS

Enables one to change the following:

These parameters are used both in this section and in the signal section.

Format:

INTEGRATION-PARAMETERS ...
     [INTEGRATION-ACCURACY accuracy] ...
     [ NOMAXIMUM-STEP-LENGTH | ...
       MAXIMUM-STEP-LENGTH maximum_step ] ...
     [ MONTE-CARLO-TIME-INTERVAL tstep | ...
       MONTE-CARLO-DISTANCE-INTERVAL dstep | ...
       MONTE-CARLO-COLLISIONS nstep ] ...
     [ CHECK-ATTRACTING-WIRES | ...
       CHECK-ALL-WIRES] ...
     [ REJECT-KINKS | ...
       NOREJECT-KINKS ] ...
     [TRAP-RADIUS ntrap] ...
     [INTERPOLATION-ORDER order] ...
     [ COMPUTE-IF-INTERPOLATION-FAILS | ...
       ABANDON-IF-INTERPOLATION-FAILS ] ...
     [CLOUD-PROJECTION-DISTANCE ncloud] ...
     [CLOUD-PROJECTION-METHOD method] ...
     [DIFFUSION-ACCURACY eps_diff] ...
     [TOWNSEND-ACCURACY eps_Town] ...
     [ATTACHMENT-ACCURACY eps_att] ...
     [DIFFUSION-STACK-DEPTH stack_diff] ...
     [TOWNSEND-STACK-DEPTH stack_Town] ...
     [ATTACHMENT-STACK-DEPTH stack_att] ...
     [PROJECTED-PATH-INTEGRATION | ...
       TRUE-PATH-INTEGRATION ] ...
     [ DRAW-ISOCHRONES | ...
       MARK-ISOCHRONES ] ...
     [ SORT-ISOCHRONES | ...
       NOSORT-ISOCHRONES ] ...
     [ ISOCHRONE-CONNECTION-THRESHOLD iso_thr | ...
       NOISOCHRONE-CONNECTION-THRESHOLD ] ...
     [ISOCHRONE-ASPECT-RATIO-SWITCH iso_aspect] ...
     [ISOCHRONE-LOOP-THRESHOLD iso_loop] ...
     [ CHECK-ISOCHRONE-CROSSINGS | ...
       NOCHECK-ISOCHRONE-CROSSINGS ]

Example:

INT DIFF-ST 5, DIFF-ACC 1.0E-3

Will limit the number of subdivisions to 32 per drift line step (the default is usually 2**20) and asks for a relative precision per step of one permille.

8.10.1: accuracy

Sets the accuracy of Runge_Kutta_Fehlberg drift line integration.

This parameter has no effect on Monte Carlo integration.

This parameter enters in the update of the step size used in drift line integration. The initial value of this parameter is suitable for chambers with a size of several cm's which have a reasonably complicated field structure. If the field is very simple, or if the chamber is very small, then a smaller value should be chosen.

[This parameter is initially set to 1E-8.]

8.10.2: maximum_step

The maximum step size that is allowed.

The Runge_Kutta_Fehlberg drift line integration method automatically updates the step length at each step. When traversing a large area with a very smooth field, the step size becomes large. If this is not desired, for instance because there is a fine structure behind the smooth area, then one should limit the step size with this option.

This parameter has no effect on Monte Carlo integration.

[By default, there is no limit to the step size.]

8.10.3: step_size

When performing Monte Carlo drift line integration, one has the choice between 3 methods:

These parameters have no effect on Runge Kutta Fehlberg integration.

Default settings are:

8.10.4: ntrap

Sets the trap distance (in terms of wire radii). If an electron or ion can be attracted by a wire (this depends on the charge on the wire but also on the setting of the option CHECK-ALL-WIRES) and if the particle passes closer by the wire than a distance of

ntrap*radius

then the electron or ion is considered to be caught by the wire.

From the moment a wire is considered caught by a wire, a dedicated integration algorithm takes over which is better at estimating the residual drift time than the default algorithm.

[This parameter is preset to a value of the order of 2-5 (depending on program version). This can be too large if the wires are very thick but it may as well be too small for very thin wires.]

8.10.5: order

Sets the order with which the drift time, the diffusion, the multiplication and the attachment losses are interpolated when using prepared tracks.

For the lower orders, you may also specify the keywords LINEAR, QUADRATIC or PARABOLIC and CUBIC.

Although values between 1 and 10 are accepted, orders larger than 2 are not recommended since they tend to lead to oscillation.

[Default: 2, parabolic interpolation.]

8.10.6: COMPUTE-IF-INTERPOLATION-FAILS

In case a prepared track can not be interpolated at a certain point, this option requests that the drift line be computed.

Reasons why a track can't be interpolated for a point are:

Computation time can increase dramatically if many points need to be computed.

If you specify ABANDON-IF-INTERPOLATION-FAILS, then such points are assigned a status of "Abandoned", a drift time, diffusion, multiplication, loss and incidence angle of 0.

[By default, drift lines are computed when needed.]

8.10.7: CHECK-ALL-WIRES

Depending on their charge, wire can either attract a particle, repel it or have no effect. Wires can also have a multipole moment which makes them attractive from one side and not from another.

If the CHECK-ALL-WIRES option is in effect, then all wires, no matter their charge, are considered able to catch a particle. As soon as a particle comes closer to any wire than the trap radius (see ntrap) an attempt will be made to drift it to the wire.

This is meaningful if you have e.g. dipole (q=0) type wires, but this is harmful if you particles pass near repelling wires, such as gating grids. This option also interferes with calculation of signals due to ions drifting from the neighbourhood of the sense wires.

When not needed, this option also wastes a lot of CPU time.

[By default, only attracting wires are checked.]

8.10.8: CHECK-ATTRACTING-WIRES

When the CHECK-ATTRACTING-WIRES option is in effect, a particle will not be considered caught when it comes closer than the trap radius to a wire that is charged such that it can not attract the particle that is drifting.

This is usually the recommended mode but there are cases, such as the presence of wires with almost no net charge, but with a multipole moment, where the alternative is better suited.

[This option is on by default.]

8.10.9: REJECT-KINKS

This option requests drift line calculation to be aborted if the drift line makes a bend sharper than 90 degrees. Such bends rarely occur in smooth fields, the most common case is a drift line that tries to cross a saddle point. The REJECT-KINKS option will ensure that the drift line doesn't repeatedly go back and forth across the saddle point.

Since fields obtained with finite element methods occasionally have areas with very uneven fields, it may be advisable in such cases to switch the option off.

[The option is on by default.]

8.10.10: ncloud

Sets the distance from the wire (in multiples of the wire radii) at which the integration routine for combined longitudinal and transverse diffusion changes from accumulating the diffusion covariance matrix to projecting the accumulated probability distribution onto the target wire.

[This parameter is preset to a value of the order of 2-5.]

8.10.11: method

When both transverse and longitudinal diffusion have been entered in the gas section, the diffusion is calculated by propagating a cloud along the drift line.

When the drift line approaches the wire, the cloud as a whole is projected onto the wire. For this phase, various algorithms are put at your disposal:

8.10.11.1: NO-PROJECTION

No special treatment when approaching the wire, hence the value of ncloud is not relevant.

8.10.11.2: INTEGRATION

As soon as the cloud enters the 'ncloud' zone, the following is done:

Complete integration over the cloud of the local distance to the wire divided by the local drift velocity.

The longitudinal diffusion over the remaining distance to the wire is added to the estimate.

8.10.11.3: CENTRAL-VELOCITY-INTEGRATION

As soon as the cloud enters the 'ncloud' zone, an integration similar to INTEGRATION is carried out, but the drift velocity is always taken to be the drift velocity at the centre of the cloud.

The longitudinal diffusion over the remaining distance to the wire is added to the estimate.

[This is currently the default method.]

8.10.11.4: LONGITUDINAL-DIMENSION

When the cloud centre enters the 'ncloud' zone, the dimension of the cloud over a line through cloud centre and wire centre is taken as measure of diffusion spread.

The longitudinal diffusion over the remaining distance to the wire is added to the estimate.

The longitudinal dimension is in principle the dimension that matters, but in the presence of a strong magnetic field, the cloud rapidly rotates near the wire. At the same time, the cloud stretches to the point of becoming almost one-dimensional. A small rounding error in the cloud alignment, can make the dimension along the axis pointing to the wire, very small.

For this reason, this method is not recommended, unless the cloud trap radius is very large (in which case the velocity estimates are likely to be inaccurate).

8.10.11.5: LARGEST-DIMENSION

This is similar to LONGITUDINAL-DIMENSION but the cloud size is taken to be the largest cross section of the cloud.

The longitudinal diffusion over the remaining distance to the wire is added to the estimate.

For reasons explained under LONGITUDINAL-DIMENSION, this method must be considered superior, provided the cloud-trap radius is small.

8.10.12: eps

A step is subdivided if the difference between the first and second order estimates differ more than a fraction epsilon of the total first order estimate without subdivisions.

[The default is 1.0E-3.]

8.10.13: stack

The stack depth is the maximum number of subdivisions allowed during the integration, in order to achieve the requested accuracy.

This parameter should be set to a small value (1 or 2) if the field is interpolated in a finite element map because the electric field, and hence the quantity to be integrated, is usually discontinuous across element boundaries.

If the field is computed from analytic formulae, then the maximum stack depth has usually little impact on the integration of the diffusion coefficients, since the latter are normally fairly smoothly varying quantities.

For the integration of the Townsend coefficient however, which suddenly grows from 0 to an appreciable value, the stack depth is a critical parameter in the accuracy of the computation. Although CPU time can go up rapidly with stack depth, it is a good idea to keep a large value: when not needed, no use of the stack is made.

[Default is MXSTCK, usually set to 20, which is also the maximum. The smallest permitted value is 1 and this setting will usually already give a reasonable accuracy. The default stack depth is large and may result in excessively lengthy computations. ]

8.10.14: PROJECTED-PATH-INTEGRATION

Monte_Carlo drift paths are longer than the mean drift paths as computed with the Runge_Kutta_Fehlberg method. Moreover, the path length computed with the Monte Carlo method increases with decreasing step length.

As a result, integrating quantities such as the Townsend and the attachment coefficient over Runge Kutta Fehlberg paths leads to smaller multiplications and larger losses than those obtained integrating over Monte Carlo paths, while the integral over the latter is ill defined since it depends on the step size.

When the PROJECTED-PATH-INTEGRATION integration parameter is active, the Townsend and attachment coefficients are integrated over path segments projected on the local drift velocity vector. This ensures that the path length integral doesn't depend on the step size used in Monte Carlo integration.

This option has effect on

[Default is TRUE-PATH-INTEGRATION.]

8.10.15: DRAW-ISOCHRONES

Requests isochrones to be drawn as lines, rather than marked.

When this option is selected, you may also wish to inspect the settings of the other isochrone related options.

This action of this option can reversed with the MARK-ISOCHRONES option.

[By default, isochrones are drawn as lines.]

8.10.16: MARK-ISOCHRONES

Requests marking the points on the isochrones.

If this option is active, no sorting needs to be done. Hence, the other isochrone options are ignored. Plotting isochrones is fast with this option switched on.

This action of this option can reversed with the DRAW-ISOCHRONES option.

[By default, isochrones are drawn as lines.]

8.10.17: SORT-ISOCHRONES

Depending on the source of the points that serve to draw the isochrones, they can be in some definite order or not.

By setting SORT-ISOCHRONES, an attempt is made to order the points in such a manner that the isochrones appear as reasonably smooth lines. Any attempt to do so is likely to fail for certain cases. Moreover, sorting can take a large amount of computing time - the problem is related to the notorious "traveling salesperson problem (TSP)".

Garfield, for these reasons uses a simple algorithm to sort the points on a contour: each contour is classified as being either linear or arcs. Linear contours are sorted along the main axis, points on arcs by angle with respect to the centre of gravity. Arcs that appear to be nearly full loops are drawn as closed contours, otherwise as an open arc.

The sorting algorithm by itself is fast - the check on intersects between isochrones and drift lines in contrast is fairly time consuming.

Sorting is not useful (hence potentially harmful) when the drift lines come from a track on which the points are ordered - which is usually the case. The sort is useful on the other hand for drift lines starting from wires or other electrodes.

The SORT-ISOCHRONES option is ignored when MARK-ISOCHRONES is in effect.

[By default: sort done]

8.10.18: ISOCHRONE-CONNECTION-THRESHOLD

Points on an isochrone are only joined if they are less than a fraction iso_thr away from each other on the screen. Points that can not be connected are shown by a marker.

The fraction iso_thr can be set to any value between 0 (only markers) and 1 (isochrones are only interrupted by drift line crossings).

Selecting NOISOCHRONE-CONNECTION-THRESHOLD is tantamount to setting iso_thr to 1.

[Initial setting: 0.2]

8.10.19: ISOCHRONE-ASPECT-RATIO-SWITCH

When an isochrone appears to be more or less circular, its points are ordered by increasing angle with respect to the centre of gravity. If the isochrone, on the other hand, seems to be more or less linear, the points are ordered along the longest principal axis of the distribution.

Whether the set is circular or linear is decided by computing the RMS in the two principal axes of the point distribution. If the ratio of these two RMS's exceeds iso_aspect, then the isochrone is assumed to be linear, otherwise circular.

[Initial setting: 3]

8.10.20: ISOCHRONE-LOOP-THRESHOLD

Isochrones that appears to be circular (rather than linear, see ISOCHRONE-ASPECT-RATIO-SWITCH for the conditions under which this happens) are closed if the largest distance between 2 points doesn't exceed a fraction iso_loop of the total length of the isochrone.

[Initial setting: 0.2]

8.10.21: CHECK-ISOCHRONE-CROSSINGS

Requests ensuring that drift lines do not cross isochrones.

Such crossings can for instance occur if the drift lines from a track flow left or right of an intermediate object, which itself also attracts some electrons, to a wire located behind the object.

This check is fairly time consuming.

[By default: check done]

Section 8.11: LINES

Sets the default number of drift lines for a couple of commands such as track preparation. The parameter also governs in part the accuracy of the x(t) calculation in sets the number of drift lines used for the initial crude search for the optimal point in y for each x.

Please note that LINES has no effect anymore on the DRIFT command. For DRIFT TRACK, use the TRACK command to set a clustering model. For DRIFT EDGES, DRIFT SOLIDS and DRIFT WIRES, use the respective LINES option on the DRIFT command line.

Format:

LINES lines

Example:

LINES 50

Section 8.12: LORENTZ-ANGLE

Prints the Lorentz-angle, i.e. the angle between the drift vector and the electric field, at the point (x,y,z).

Format:

LORENTZ-ANGLE x y z

Example:

LORENTZ 0.5 0.5 1

Section 8.13: MINIMISE

Searches for the minimum of e.g. the drift time over a curve.

Format:

MINIMISE f_min
         [SELECTION-FUNCTION f_select] ...
         ON f_curve
         RANGE t_min t_max   N n ...
         [ELECTRON | ION]
         [NEGATIVE | POSITIVE] ...
         [FUNCTION-PRECISION eps_f] ...
         [POSITIONAL-RESOLUTION eps_pos] ...
         [ITERATE-LIMIT itermax] ...
         [PRINT | NOPRINT] ...
         [DATASET dataset [member] [REMARK remark]]

Example:

MINIMISE TIME ON '5*COS(T), 5*SIN(T)' RANGE {PI/4,3*PI/4}

This instruction asks for a minimisation of the drift time over an arc with radius 5 and in the angular range pi/4 to 3 pi/4. Note that quotes are used to specify the curve: a comma has to be placed between the two coordinates, but since the comma is a separator and since ON expects only one element, the expression is placed in quotes. RANGE on the other hand expects two elements and quotes should therefore not be used !

8.13.1: f_min

The function to be minimised has to depend on at least one of the following variables:

Symbol meaning
TIME total drift time [micro seconds]
LENGTH length of the drift line [cm]
DIFFUSION integrated diffusion coefficient [cm]
AVALANCHE integrated and exponentiated Townsend coefficient
LOSS integrated and exponentiated attachment coefficient

[The default function to be minimised is TIME.]

8.13.2: f_select

This function should return either True or False. If False is returned, then the point will not be considered anymore during the minimisation process.

The following variables can be used:

Symbol Meaning
TIME total drift time [micro seconds]
LENGTH length of the drift line [cm]
DIFFUSION integrated diffusion coefficient [cm]
AVALANCHE integrated and exponentiated Townsend coefficient
LOSS integrated and exponentiated attachment coefficient
STATUS information on what happens to the particle

All variables are of type Number except for STATUS which is a String and which can have one of the following values:

`Left_Area`, `Too_Many_Steps`, `Abandoned`, `Hit_Plane`, `Left_Drift_Medium`, `Left_Mesh`, `Hit_X_Wire` and `Hit_X_Replica`. `X` is the label that you have assigned to the wire.

[The default selection curve returns always True.]

8.13.3: ON

ON should be followed be a parametrisation in terms of the variable T of the curve over which teh minimisation should take place.

The range of T can be specified via RANGE.

[No default curve is provided.]

8.13.4: RANGE

RANGE should be followed by the minimum and the maximum value the variable T is allowed to take during minimisation, see ON for further information on T.

[No default RANGE is provided.]

8.13.5: N

The number of points on the curve for the initial scan of the curve.

[The default value for N is 20.]

8.13.6: ELECTRON

Requests that the minimisation be carried out for electrons.

[This is the default.]

8.13.7: ION

Requests that the minimisation be carried out for ions.

[By default, minimisation is done for electrons.]

8.13.8: POSITIVE

Requests that the minimisation be carried out for positively charged electrons or ions.

[The default is NEGATIVE.]

8.13.9: NEGATIVE

Requests that the minimisation be carried out for negatively charged electrons or ions.

[This is the default.]

8.13.10: FUNCTION-PRECISION

The procedure assumes it has converged if the relative change in function value has dropped below eps_f.

[The default value is 10E-4, which is also the smallest reasonable value on computers like Vax and IBM. On Cray and other computers with 64 bit precision, eps_f can be made smaller.]

8.13.11: POSITIONAL-RESOLUTION

The procedure assumes it has converged if the relative change in position of the minimum has dropped below eps_pos.

[The default value is 10E-4, which is also the smallest reasonable value on computers like Vax and IBM. On Cray and other computers with 64 bit precision, eps_pos can be made smaller.]

8.13.12: ITERATE-LIMIT

The maximum number of iteration steps during the minimisation process.

[By default 20.]

8.13.13: PRINT

Requests some printout during the minimisation procedure.

[This is default.]

8.13.14: DATASET

Requests dataset output of the minimisation results.

[No such output is produced by default.]

Section 8.14: OPTIONS

Determines whether the drift lines produced by other commands than the DRIFT instruction are plotted or printed. Commands affected by these options include ARRIVAL-TIME-DISTRIBUTION and PREPARE-TRACK. The option is also honoured in the debugging mode of several other commands.

You may also change global options in the same statement, see the top level OPTIONS command for further information.

Format:

OPTIONS [DRIFT-PRINT | NODRIFT-PRINT] ...
        [DRIFT-PLOT | NO-DRIFT-PLOT] ...
        [KEY | NOKEY] ...
        [CONTOUR-ALL-MEDIA | CONTOUR-DRIFT-MEDIUM] ...
        [NOWIRE-MARKERS | WIRE-MARKERS] ...
        [NOCHECK-MAP-INDICES | CHECK-MAP-INDICES]

Example:

OPT DR-PL NODR-PR

8.14.1: DRIFT-PRINT

Requests printing of drift line summary data in a few, nearly forgotten, commands like TABLE.

Most commands have their local print option.

8.14.2: DRIFT-PLOT

Requests plotting of the drift lines used by for instance XT-PLOT and ARRIVAL-TIME-DISTRIBUTION.

The option is particularly useful to verify that prepared tracks are interpolated with a reasonable order, and to judge whether there is a need to set the COMPUTE-IF-INTERPOLATION-FAILS option.

[The option is by default off.]

8.14.3: KEY

Requests labelling of the contours produced by TABLE CONTOUR. This option is shared with the field section where it controls labelling of the (e.g. potential) contours.

8.14.4: CONTOUR-ALL-MEDIA

Requests that contours be drawn across all non-conducting media.

This option is ignored if the field is computed from wires and planes.

[This is default.]

8.14.5: CONTOUR-DRIFT-MEDIUM

Requests contours be drawn exclusively in the material that has been designated as drift medium.

This option is ignored if the field is computed from wires and planes. The option is honoured only if the dielectric constants are present in the field map.

[Contours are by default drawn in all media.]

8.14.6: WIRE-MARKERS

If active, wires will be plotted as markers and not as circles with the size of the wire.

For further information, see the WIRE-MARKERS option in the cell section.

8.14.7: CHECK-MAP-INDICES

Requests a verification of the map index calculation.

See the CHECK-MAP-INDICES option in the field section for further information.

Section 8.15: PLOT-FIELD

This instruction plots the quantities related to drifting of electrons and ions in a variety of ways, such as contours, a surface plot, a graph, an histogram.

Similar instructions exist in the field and signal sections.

CPU time can be saved if several plots are combined in a single command.

Format:

PLOT-FIELD [CONTOUR [f1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                           [N n] ...
                           [LABELS | NOLABELS]] ...
           [GRAPH [f2]     [ON f_curve] ...
                           [N n]] ...
                           [SCALE min max] ...
                           [NOPRINT | PRINT] ...
           [HISTOGRAM [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                           [BINS nbin]] ...
           [SURFACE [f4]   [ANGLES phi theta]] ...
           [VECTOR [f5 f6]] ...
           [RUNGE-KUTTA-DRIFT | MONTE-CARLO-DRIFT] ...
           [ELECTRON | ION] ...
           [POSITIVE | NEGATIVE]

If you don't manage to fit all this on a single line, remember that lines that end on an ellipsis are continued on the next.

Examples:

PLOT HIST DIFFUSION VECTOR VDX, VDY SURF CONT
PLOT CONTOUR TIME RANGE 0.1 0.3

(The first example makes most of the plots using default functions and ranges - useful as a first call. The second example makes a more detailed contour plot.)

8.15.1: functions

All functions in the description of the PLOT-FIELD command (f1, f2 ... f6) may depend on the following set of variables:

Symbol Meaning Note
X, Y, Z Position R, PHI for polar cells
EX, EY, EZ, E E-field at (x,y,z) ER, EPHI for polar cells
BX, BY, BZ, B B-field at (x,y,z) only if there is a B-field
VDX, VDY, VDZ, VD Local drift velocity VDR, VDPHI for polar cells
LORENTZ Local Lorentz angle -
TIME Total drift time -
PATH Total drift path length -
DIFFUSION Integrated diffusion only if data is available
AVALANCHE Avalanche multiplication only if data is available
LOSS Loss due to attachment only if data is available
STATUS Status code See below
P Pressure of the gas -

The status code is a Number, not a string.

Other variables can be added on request.

8.15.2: contour

Produces a plot of the lines of equal function values.

Contours are drawn in the part of the viewing plane that is located within the current AREA box.

The contours are labeled with the function value if the LABEL option is on (which is by default the case).

If you request AUTOMATIC scaling of the range, contours are drawn at decent function heights covering the range of the function on the AREA. The number of contours is used to compute a rough distance between two contours; the distance is rounded downwards. The number of contours actually drawn may therefore be larger than the number you request.

Note that much better equal time contours can be obtained with the DRIFT WIRES ISOCHRONES=delta NODRIFT-PLOT instruction which takes the end-point of the drift lines into account when deciding which points of the contours are to be joined with a line.

The contours are drawn with the representation CONTOUR-NORMAL and are labeled with CONTOUR-LABELS.

[The default function is VD, the drift velocity, and the contour range is by default adjusted automatically. By default, about 20 contours are plotted.]

8.15.3: graph

The function is evaluated on the track or on the curve specified with the ON keyword.

The geometric aspects of the track, if used, should be set by means of the TRACK command before calling PLOT-FIELD. Other aspects of the track, such as the clustering model, are not used in the present context.

A curve should be parametrised in terms of T which will run from 0 to 1. All 3 coordinates of the curve should be specified. Note that ON expects only one argument, the parametrisation should therefore be enclosed in quotes, e.g.

'cos(pi*t),sin(pi*t),0'
would be appropriate to describe a semi-circle in the z=0 plane.

The SCALE option can be used to force a vertical scale in the plot, this can for instance be useful if you intend to overlay various graphs.

If you select the PRINT option, then the values plotted in the graph will also be printed out. Rerouting of the output (> file) can be used to write the values to a file.

The number of sampling points can be set with N, default is 200.

[The default function is VD, the drift velocity.]

8.15.4: histogram

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are entered in an histogram.

This kind of plot can be useful to estimate for instance the spread in drift time over a given region.

The automatic search for proper binning (AUTOMATIC) uses the first few entries to set the range. Since the grid is scanned in a regular sequence, these entries are not necessarily representative for the entire sample, in particular if the number of bins is small compared to the grid size. See AUTOSCALE for details on the automatic binning procedure.

[The default function is VD. The number of bins is preset to 100 and the range is by default chosen automatically.]

8.15.5: surface

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are presented as a three dimensional plot.

The plot is first rotated by phi degrees around the z-axis and then tilted by theta degrees from the z-axis.

This plot is decorative but it is generally agreed upon that it is hard to extract any meaningful information from it ...

[The default function is VD, i.e. the magnitude of the drift velocity. The default viewing angles are 30 and 60 degrees. The viewing angles are remembered from one call to the next.]

8.15.6: vector

This plot shows the flow of a 3-vector sampled over a GRID grid of points in the part of the current viewing plane that is located inside the AREA box. The vectors are projected onto the current viewing plane.

The z-component is set to 0, if not explicitely specified. For other than (x,y) views, this may give incorrect impressions.

The vectors are normalised in 3 dimensions when they are plotted - the length of the vectors shown does not contain information on the magnitude of the quantity that is plotted. A vector that appears point like has no component in the viewing plane.

It is advisable to have roughly equal ranges in view of the scaling that is performed on the vectors.

The vectors are plotted using the FUNCTION-1 representation. The appearance of the arrow is influence by the ARROW-TIP-ANGLE and ARROW-TIP-LENGTH settings.

[The default functions are VDX, VDY, VDZ, i.e. the drift velocity.]

8.15.7: ELECTRON

Requests drifting of electrons, not ions.

[This is default.]

8.15.8: ION

Requests drifting of ions, not electrons.

[This is not default.]

8.15.9: POSITIVE

By default, electrons are drifted with negative charge and ions with positive charge. If you wish to see the origin of the electrons and ions arriving at a given position, you may wish to reverse the sign.

The POSITIVE option forces the charge to be positive, no matter whether the particle is an electron or an ion.

8.15.10: NEGATIVE

By default, electrons are drifted with negative charge and ions with positive charge. If you wish to see the origin of the electrons and ions arriving at a given position, you may wish to reverse the sign.

The NEGATIVE option forces the charge to be negative, no matter whether the particle is an electron or an ion.

8.15.11: RUNGE-KUTTA-DRIFT

Requests the use of the Runge_Kutta_Fehlberg algorithm for computing drift lines.

Runge Kutta integration is easier to use than Monte Carlo stepping in that the integration parameters are more tolerant.

The parameters controling the accuracy are adjusted for chambers that are several centimeters large. When studying much smaller structures, at the micron scale, one may wish to request more accuracy.

The Runge Kutta algorithm is well suited for smooth fields, such as those obtained with analytic potentials. The field computed from field maps is sometimes not even continuous, and one should in such cases prefer the Monte Carlo algorithm.

[The initial default is RUNGE-KUTTA-DRIFT.]

8.15.12: MONTE-CARLO-DRIFT

Requests Monte_Carlo calculation of a drift path, instead of a Runge_Kutta_Fehlberg integration.

When using this option, care has to be taken that the step size has been set to a value appropriate to the chamber, see in particular the step_size as set with the INTEGRATION-PARAMETERS command.

[The initial default is RUNGE-KUTTA-DRIFT.]

Section 8.16: PREPARE-TRACK

Calculates and stores an interpolation table for drift line related quantities. Prepared tracks are used e.g. when in a Monte Carlo calculation drift times are needed at many randomly located points on one track. The difference in CPU time usage can be dramatic while the loss in accuracy is usually negligible.

Interpolation of tracks is currently done in 3 cases:

The track thus prepared, can be saved in a dataset with WRITE-TRACK from where it can be retrieved in subsequent runs with GET-TRACK.

Format:

PREPARE-TRACK ...
     [ATTACHMENT-COEFFICIENT | NOATTACHMENT-COEFFICIENT] ...
     [DIFFUSION-COEFFICIENT | NODIFFUSION-COEFFICIENT] ...
     [TOWNSEND-COEFFICIENT | NOTOWNSEND-COEFFICIENT] ...
     [LINES n]

Example:

PREP-TR

(Accept all defaults, usually adequate.)

8.16.1: ATTACHMENT-COEFFICIENT

The attachment coefficient will be integrated and the result will be stored along with the other data if this option is selected.

8.16.2: DIFFUSION-COEFFICIENT

The diffusion coefficient will be integrated and the result will be stored along with the other data if this option is selected.

8.16.3: TOWNSEND-COEFFICIENT

The Townsend coefficient will be integrated and the result will be stored along with the other data if this option is selected.

8.16.4: LINES

The number of drift lines over which the interpolation will take place. The number is rounded to the next higher multiple of 4. The number may not exceed MXLIST-4.

In a first step, 75 % of the drift lines are distributed uniformly over the track. The remaining 25 % of the points are chosen in a matter that tries to optimise the accuracy of the interpolation table.

When interpolation is requested for a point which is located between 2 tabulated points from where electrons reach different electrodes, Garfield either computes the drift line (if the integration parameter COMPUTE-IF-INTERPOLATION-FAILS has been selected) or returns a drift line status of Abandoned. In case electrons starting from the track reach several different electrodes, LINES should therefore be chosen large so as to minimise the regions where explicit calculation is required.

[By default, the number set with LINES.]

Section 8.17: SELECT

Selects and groups the electrodes which are to be handled specially. The selection is common to all sections, but the interpretation of the selection is left to the individual instructions.

The grouping is of no importance in this section. The selection determines for instance which wires are processed by DRIFT WIRES, ARRIVAL-TIME-DISTRIBUTION and XT-PLOT.

Format:

See SELECT

Example:

SEL (1 S) 2 F

(Put wire 1 together with all S wires in one group, make wire 2 a group of its own and do the same for each of the F wires.)

Section 8.18: SINGLE

An instruction that will print and plot details about a single drift line from (x,y). The information can be presented as a table of the position, the integrated drift time and a user specified function, but also as a graph of one function against another.

Similar plots can be obtained by first computing a drift line with the DRIFT_ELECTRON, DRIFT_ELECTRON_3, DRIFT_MC_ELECTRON, DRIFT_POSITRON, DRIFT_POSITRON_3, DRIFT_MC_POSITRON, DRIFT_ION, DRIFT_ION_3, DRIFT_MC_ION, DRIFT_MC_NEGATIVE_ION, DRIFT_NEGATIVE_ION or DRIFT_NEGATIVE_ION_3 procedure, then retrieving it with GET_DRIFT_LINE and finally making the graph with PLOT_GRAPH.

Format:

SINGLE  FROM  x y ...
        [PLOT f1 VS f2 | NOPLOT] ...
        [PRINT f3 | NOPRINT] ...
        [NEGATIVE | POSITIVE] ...
        [ELECTRON | ION]

Examples:

SINGLE FROM 0.5 0.3 PLOT DIFFUSION VS PATH
SINGLE FROM 0.1 0.2 PRINT VDX

8.18.1: functions

The functions may use the following variables:

Symbol Meaning Note
X, Y, Z Position R, PHI for polar cells
EX, EY, EZ, E E-field at (x,y,z) ER, EPHI for polar cells
BX, BY, BZ, B B-field at (x,y,z) only if there is a B-field
VDX, VDY, VDZ, VD Local drift velocity VDR, VDPHI for polar cells
TIME Cumulative drift time -
PATH Cumulative path length -
DIFFUSION Local long. diffusion only if data is available
TOWNSEND Local Townsend coeff. only if data is available
ATTACHMENT Local attachment coeff. only if data is available
STATUS Drift line status code numeric status code

See istat for an explanation of the numeric status code.

[No meaningful default functions are provided.]

8.18.2: PRINT

Requests a printed table of the coordinate and integrated drift time at each step and of the function f3.

[The table is by default not produced.]

8.18.3: PLOT

Requests a graph of function f1, plotted along the y-axxis, vs function f2, plotted along the x-axis.

[By default, a graph is not made.]

8.18.4: ELECTRON

The drift line will be calculated for an electron.

8.18.5: ION

The drift line will be calculated for an ion.

8.18.6: POSITIVE

The particle which is drifted has a positive charge.

8.18.7: NEGATIVE

The particle which is drifted has a negative charge.

Section 8.19: SPEED

A debugging instruction that will evaluate the drift speed at a given point (x,y,z). The POSITIVE or NEGATIVE keyword should, if used, be placed after the ELECTRON or ION keyword, if used.

Similar functionality is provided by the ELECTRON_VELOCITY and ION_VELOCITY procedures.

Format:

SPEED x y z   [ELECTRON | ION]   [NEGATIVE | POSITIVE]

Example:

SPEED 0.5 1.5 0

Section 8.20: TABLE

Prints a table of drift times for electrons or ions starting from a GRID of regularly spaced points inside the AREA.

The POSITIVE or NEGATIVE keyword should, if used, be at the end of the command.

Format:

TABLE [TABLE | NOTABLE] ...
      [NOCONTOUR | CONTOUR] ...
      [ELECTRON | ION] ...
      [NEGATIVE | POSITIVE]

This command must be entered on a single line !

Example:

TABLE

(Only produce the table, no contours.)

8.20.1: TABLE

Requests printed output from the TABLE instruction. It is probably advisable to rerout it to some output file.

8.20.2: CONTOUR

Requests that the results from this instruction be represented as a set of equal drift time contours. This plot is necessarily much cruder than those obtained with DRIFT WIRES NOLINE-PLOT ISOCHRONES=deltat.

Section 8.21: TIME

Times n drift line calculations [default: 10].

Format:

TIME [n]

Example:

TIME 5

Section 8.22: TIMING

Computes the arrival time distribution of the n'th electron over a given area. Unlike the ARRIVAL-TIME-DISTRIBUTION instruction, TIMING does not produce calibration curves, but merely timing distributions.

This instruction overwrites the geometrical part of the track description, but uses the clustering type entered via the TRACK statement.

Format:

TIMING [ELECTRONS {electron | LAST | ONE-BUT-LAST | ... }] ...
       [TIME-WINDOW tmin tmax ] ...
       [X-RANGE xmin xmax] [Y-RANGE ymin ymax] ...
       [ANGLE-RANGE phimin phimax] ...
       [BINS bins] ...
       [ITERATIONS loops] ...
       [RUNGE-KUTTA-DRIFT | MONTE-CARLO-DRIFT] ...
       [NOATTACHMENT | ATTACHMENT] ...
       [WEIGHTING-FUNCTION weight] ...
       [NOKEEP-HISTOGRAMS | KEEP-HISTOGRAMS] ...
       [NOPLOT-OVERALL | PLOT-OVERALL] ...
       [NOPLOT-SELECTED-ELECTRON | PLOT-SELECTED-ELECTRON] ...
       [NOPRINT-OVERALL | PRINT-OVERALL] ...
       [NOPRINT-SELECTED-ELECTRON | PRINT-SELECTED-ELECTRON]

If you don't manage to fit all this on a single line, remember that lines that end on an ellipsis are continued on the next.

The PROGRESS-PRINT global option enables you to follow the progress of the computations.

Example:

TRACK MUON ENERGY 20 GeV
TIMING ELECTRON 3 LAST Y-RANGE -0.3 +0.3

Computes the arrival time distribution of the 3rd and the last electron for random vertical Heed-generated tracks of 20 GeV muons in the y range [-0.3, +0.3]. The x-range is default, i.e. the x-portion of the AREA.

8.22.1: electron

These are the electrons you wish to select for output. One can either specify these by a sequence number or with such keywords as LAST, ONE-BUT-LAST etc.

This should be approximately the threshold of the electronics, but since electronics usually doesn't trigger on a well defined electron, one can't obtain a too accurate resolution from this kind of instruction. If resolution estimates are required, one should compute signals and process these by an electronics simulation program.

[Default: only the 5th electron.]

8.22.2: TIME-WINDOW

Specifies the time window of all arrival time histograms, both of the selected electron and of all electrons. If you do not specify a time window, then all timing histograms are given a range automatically.

8.22.3: X-RANGE

The part of the AREA to be covered by the tracks.

Tracks are generated uniformly over this x-range. The WEIGHTING-FUNCTION can be used to assign probabilities to the various x values.

[Default: the entire x-range of the AREA.]

8.22.4: Y-RANGE

The vertical extent of the tracks. This parameter is less trivial than it might appear: if the range does not cover the full acceptance boundaries of the wire, the program will give wrong results for late electrons. If the range is chosen too small, the waste of CPU time is considerable and also the accuracy may suffer if the LINES parameter does not compensate.

[Default: the entire y-range of the AREA.]

8.22.5: ANGLE-RANGE

The range of angles of the tracks with respect to the vertical.

Tracks will be generated according to a uniform distribution over this angular range. The WEIGHTING-FUNCTION can be used to attribute a probability to each angle.

One may also enter a single angle if tracks are to be generated only at that angle.

[Default: only vertical tracks are generated.]

8.22.6: MONTE-CARLO-DRIFT

Specifying this option requests the use of Monte Carlo style drift line integration in which diffusion is accounted for on a step by step basis.

Each electron of a cluster is in this case drifted separately.

When using this option, you have to be sure that the time or distance interval for Monte Carlo integration has been set to a reasonable value with INTEGRATION-PARAMETERS.

[Default: Runge-Kutta-Fehlberg integration is used.]

8.22.7: ATTACHMENT

Requests that attachment data is taken into account.

[Default: attachment data is not taken into account.]

8.22.8: WEIGHTING-FUNCTION

A function of X (x-coordinate of the track) and ANGLE (the inclination angle of the track in degrees) which is used to assign a probability to tracks with a given (x,angle) pair.

Tracks are generated uniformly within the X-RANGE and the ANGLE-RANGE.

[Default: a weight of 1 is assigned to each track.]

8.22.9: bins

The number of bins in the histograms used to compute the time at which the selected histogram has a given probability to have arrived - the mean arrival time is computed directly without histogram.

[Default: half of MXLIST, usually 100 bins.]

8.22.10: KEEP-HISTOGRAMS

This option can be used to store the arrival time histograms for later study. The histograms are made accessible via global variable names that are displayed while the command is carried out (SELECTED and ALL).

You have to declare the Global variables before the loop if

This can be accomplished by assigning them an arbitrary value. Declaring is not required if the variables are only used outside the loop, in procedure Calls, in Say statements or for substitution in normal input statements.

[Default: histograms are not kept.]

8.22.11: loops

The number of Monte Carlo loops over track generation. These loops can consume considerable CPU time since the drift times, diffusion coefficients etc are computed for each drift line individually (in contrast the ARRIVAL which uses interpolation).

[Default: 1000.]

8.22.12: plot_options

Garfield can be asked to output for each track the timing histograms for all (PLOT-OVERALL) and the selected electron (PLOT-SELECTED-ELECTRON). Both are by default not plotted.

8.22.13: print_options

The timing histograms for the selected electron and for all electrons are printed out at your request. In the printout, additional information such as the mean and width are provided. These quantities are computed from the entries themselves, not from the accumulated bin contents. The internal arithmetic is done in double precision.

Section 8.23: TRACK

Defines the track that is used, amongst others, by the PLOT-FIELD command in the field section, the ARRIVAL-TIME-DISTRIBUTION, DRIFT, PLOT-FIELD and TIMING commands in the drift section as well as by the PLOT-FIELD and SIGNAL commands in the signal section.

The track is shared between commands from nearly all sections, hence the elaborate format. Tracks have 2 main aspects, the location and the clustering model. Some commands use only the location, e,g, the PLOT-FIELD commands, while others, such as signal calculations, also need to know the clustering model:

Tracks are 3-dimensional objects. You may omit the z-component of the track, to indicate that the track is located in the (x,y) plane. However, multiple scattering may cause the track to leave this plane and delta electrons, Auger electrons and photons are generated irrespective of whether you specify a track located in the (x,y) plane or not.

The model to be used is determined by the last keyword that is found on the line. If you set parameters for several models, then you can, to avoid ambiguity, type one of the model names (FIXED-NUMBER, EQUAL-SPACING etc) at the end of the line.

Format:

TRACK  [ x0 y0 | x0 y0 x1 y1 | ...
         x0 y0 z0 | x0 y0 z0 x1 y1 z1 | ...
         FROM x0 y0 [z0] | ...
         { TO x1 y1 [z1] | DIRECTION dx dy [dz] RANGE range } ] ...
       [ FIXED-NUMBER ]  ...
            [ LINES nline ]                    | ...
       [ EQUAL-SPACING ]                       | ...
       [ EXPONENTIAL-SPACING ]                 | ...
       [ SINGLE-CLUSTER ]                      | ...
       [ WEIGHTED-DISTRIBUTION ] ...
            [ WEIGHTING-FUNCTION  { f | weight vs coordinate } ] ...
            [ SAMPLES nsample ]                | ...
       [ HEED ] ...
            [ DELTA-ELECTRONS | NODELTA-ELECTRONS ] ...
            [ TRACE-DELTA-ELECTRONS | NOTRACE-DELTA-ELECTRONS ] ...
            [ MULTIPLE-SCATTERING | NOMULTIPLE-SCATTERING ] ...
            [ particle | MASS mass CHARGE charge ] ...
            [ ENERGY energy ]                  | ...
       [ EQUAL-FLUX-INTERVALS ] ...
            [ FLUX-LINES n]                    | ...
       [ CONSTANT-FLUX-INTERVALS ] ...
            [ FLUX-INTERVAL dv]

Examples:

track * * * 5

Keep all old values except the y coordinate of the end point.

track 1 1 1 2 2 2

Defines a track from (1,1,1) to (2,2,2).

track from 1 1 1 direction 0 0 1 range 5
track mu+ energy 1000 lines 10 multiple-scattering nodelta
track fixed
drift track
track heed
drift track

In a first TRACK statement, the location of the track is described. The length of the track projected onto the DIRECTION is limited to 5 cm. The second TRACK statement provides HEED with a description of the particle, indicates that multiple scattering should be taken into account, but not delta electrons. The same line changes the default number of deposits for the FIXED-NUMBER model to 10. The third TRACK statement selects the model to be used, a plot is made with this model, the model is then changed to HEED and another plot is produced.

8.23.1: FROM

The coordinates of the starting point of the track.

This would usually be a set of 3 numbers. If you omit the z-coordinate, 0 is assumed.

[No default, in cm.]

8.23.2: TO

The coordinates of the end point of the track. If the particle undergoes multiple scattering or energy loss (HEED model), then the end point merely serves to compute the initial direction of the particle.

When both TO is used and DIRECTION and RANGE, then the information provided with TO is taken.

This would usually be a set of 3 numbers. If you omit the z-coordinate, 0 is assumed.

[No default, in cm.]

8.23.3: DIRECTION

The direction in which the particle starts moving from the starting point.

When using DIRECTION, you must also use RANGE. You should not use TO however in this case, since TO overrules the information from DIRECTION and RANGE.

This would usually be a set of 3 numbers. If you omit the z-coordinate, 0 is assumed.

[No default, in cm.]

8.23.4: RANGE

This is the maximum distance the particle is allowed to travel from the starting point. The range is measured by projection onto the DIRECTION, i.e. the additional length that results from multiple scattering is not taken into account.

The RANGE should be chosen sufficiently large to avoid having the particle cut prematurely, but not too large either - this would cause overflow in HEED's internal buffers.

[No default, in cm.]

8.23.5: FIXED-NUMBER

Requests the simple model in which an electron or an ion is generated at equally spaced points along the track.

The number of points can be specified after the LINES keyword. The number of clusters per cm, which can be entered in the gas section with PARAMETERS, is not used.

Each deposit contains a single electron or ion, a cluster size distribution, if entered, is not used by this model.

The track is straight in this model.

If this keyword is used, it should be the last keyword on the command line. The model is implied by the use of the LINES keyword.

8.23.5.1: LINES

Number of electrons or ions deposited on the track.

Used only with the FIXED-NUMBER model.

Note that for a track of length 0, and (e.g.) LINES=25, one would get 25 deposits in the same point. This can be meaningful if you ask for Monte Carlo drifting from that point.

[Default: 20]

8.23.6: EQUAL-SPACING

Requests a model in which the number of clusters generated along a straight track is always exactly

     mean * length

where "mean" is the mean number of clusters per cm as entered with the MEAN option of the PARAMETERS statement in the gas section and where "length" is the distance between the start and end points of the track.

The clusters are deposited with a constant spacing.

The cluster size distribution will usually be taken from a CLUSTER statement, but can also be derived from data entered with PARAMETERS.

Both the cluster size distribution and the number of clusters must be specified as described above. Heed is not called to fill in missing data.

If this keyword is used, it should be the last keyword on the command line.

8.23.7: EXPONENTIAL-SPACING

Requests a model in which the number of clusters generated along a straight track is Poisson distributed with a mean of:

mean * length

where "mean" is the mean number of clusters per cm as entered with the MEAN option of the PARAMETERS statement in the gas section and where "length" is the distance between the start and end points of the track.

The spacing between the clusters is exponentially distributed.

The cluster size distribution will usually be taken from a CLUSTER statement, but can also be derived from data entered with PARAMETERS.

Both the cluster size distribution and the number of clusters must be specified as described above. Heed is not called to fill in missing data.

If this keyword is used, it should be the last keyword on the command line.

8.23.8: WEIGHTED-DISTRIBUTION

This model generates single electron or ion deposits (and not clusters) at positions that follow a user specified distribution. The model can be used to simulate certain background conditions.

The deposits are generated in random sequence.

If this keyword is used, it should be the last keyword on the command line. The use of this model is implied by the keywords WEIGHTING-FUNCTION and SAMPLES.

8.23.8.1: WEIGHTING-FUNCTION

The distribution of the points along the track can be specified in either of 2 ways:

The function should return only non-negative values with a total contents larger than zero. The function need not be normalised.

8.23.8.2: SAMPLES

The number of sampling points in the WEIGHTED-DISTRIBUTION model.

8.23.9: SINGLE-CLUSTER

A single cluster is generated on each track. The cluster size is taken from the information entered in the gas section with the CLUSTER or the PARAMETERS statement.

This model differs from FIXED-NUMBER with a number of samples set to 1 in that the cluster of SINGLE-CLUSTER is at a random location while it would be in the middle of the track when using FIXED-NUMBER.

This model can be seen as a rough approximation to photon from e.g. an Fe 55 source, provided an adequate cluster size distribution is entered.

If this keyword is used, it should be the last keyword on the command line.

8.23.10: HEED

This option calls the Heed program to take care of cluster generation. This program simulates the ionisation of the gas molecules by a particle.

The particle knocks an electron out of an atom. The electron may have sufficient energy to cause further ionisations (in that case we speak of a delta electron) or it may start drifting towards the anode. The atom returns to its ground state by either emitting an Auger electron or by fluorescence photons. The Auger electrons are treated like the ionisation electrons. The photons can be absorbed in other atoms.

When using the Heed interface, you must define the gas mixture with a HEED command in the gas section. You should specify on the TRACK statement what kind of particle traverses the chamber. Clustering information entered in the gas section through the PARAMETERS and CLUSTER statements is not used when clustering is performed hy Heed.

If this keyword is used, it should be the last keyword on the command line. The use of this model is implied by the specification of a particle type, charge or energy and by the options related to multiple scattering and delta electrons.

8.23.10.1: particle

Some common particles can be described by name:

Name Particle Mass [MeV] Charge
ELECTRON electron (e-) 0.51099907 -1
POSITRON positron (e+) 0.51099907 +1
MU-MINUS negative muon (mu-) 105.658389 -1
MU-PLUS positive muon (mu+) 105.658389 +1
TAU-MINUS negative tau (tau-) 1777.00 -1
TAU-PLUS positive tau (tau+) 1777.00 +1
GAMMA photon 0 0
PION-MINUS negative pion (pi-) 139.56995 -1
PION-0 neutral pion (pi0) 134.9764 0
PION-PLUS positive pion (pi+) 139.56995 +1
KAON-MINUS negative kaon (K-) 493.677 -1
KAON-0 neutral K or anti-K 497.672 0
KAON-PLUS positive kaon (K+) 493.677 +1
PROTON proton (p) 938.27231 +1
ANTI-PROTON antiproton (p-bar) 938.27231 -1
NEUTRON neutron (n) 939.56563 0
ANTI-NEUTRON antineutron (n-bar) 939.56563 0

Although some neutral particles are included in this list, their use is, with the exception of photons, not meaningful since these particles do not cause ionisation losses in the Heed model.

Gamma's are scheduled for inclusion at a later stage.

8.23.10.2: MASS

If the particle is not known by its name, then one can describe it with its mass and charge.

The mass can either be a number, in which case it is assumed to be in MeV, or a number followed by a unit (eV, keV, MeV or GeV).

[Default: muon mass]

8.23.10.3: CHARGE

If the particle is not known by its name, then one can describe it with its mass and charge.

The charge of the particle should be in proton charges, i.e. an electron would have charge -1, a K+ would have +1.

Currently, only charges of +1 and -1 are accepted.

8.23.10.4: ENERGY

The energy of the particle traversing the chamber.

The energy can either be a number, in which case it is assumed to be in MeV, or a number followed by a unit (eV, keV, MeV or GeV).

[Default: 1 GeV]

8.23.10.5: MULTIPLE-SCATTERING

Heed will optionally make the incoming particle undergo multiple scattering.

Keep in mind that multiple scattering will slow Heed down.

Track preparation is compatible with multiple scattering but such a combination is not meaningful since the drift path of electrons produced far from the prepared track has to be computed without interpolation.

[Multiple scattering is on by default.]

8.23.10.6: DELTA-ELECTRONS

Heed generates its electrons through delta electrons. If you are not interested in the spatial extent of delta electrons, you may opt to have all electrons moved to the location of the interaction that created the delta electron.

The DELTA-ELECTRONS option is compatible with track preparation, e.g. in the context of signal calcultions, but the drift path of electrons produced far from the prepared track will be computed rather than interpolated.

Apart from this, there is no substantial gain in time by switching delta electrons off.

[Delta electrons are by default kept as they come out of Heed]

8.23.10.7: TRACE-DELTA-ELECTRONS

Delta electrons usually have a sufficiently low energy to be affected by the E and B fields present in the chamber.

When this option is switched on, they are traced from one collision to the next following the E and B field. Since this is a time consuming operation, you may wish to switch tracing off when studying only the cluster statistics.

Delta electrons are not traced either when the NODELTA-ELECTRONS option is specified.

[Tracing is on by default.]

8.23.11: EQUAL-FLUX-INTERVALS

Generates points along the track spaced by equal flux intervals. The spacing of drift lines from such points indicates the electric field strength.

The number of points can be set with the FLUX-LINES keyword.

The flux is computed by integrating the electric field component that is in viewing plane and perpendicular to the track.

If the flux changes sign over the track, then points are only generated over the parts of the track where the flux is positive if the total flux over the track is positive. Conversely, if the total flux is negative, points are generated only in areas where the flux is negative.

The cluster size is set to 1 and the cluster energy to 0 in this model.

If this keyword is used, it should be the last keyword on the command line. The use of this model is implied by the presence of the FLUX-LINES keyword.

8.23.11.1: FLUX-LINES

Number of flux lines to be plotted.

Segments of the track over which no points are generated because of a change of sign in the flux, do not consume points.

This keyword is only used by the EQUAL-FLUX-INTERVALS model.

[Default: 20 lines]

8.23.12: CONSTANT-FLUX-INTERVALS

Generates points along the track spaced by a given flux interval. The spacing of drift lines from such points indicates the electric field strength.

The flux between 2 points can be specified following the FLUX-INTERVAL keyword.

The flux is computed by integrating the electric field component that is in viewing plane and perpendicular to the track.

If the flux changes sign over the track, then points are only generated over the parts of the track where the flux is positive if the total flux over the track is positive. Conversely, if the total flux is negative, points are generated only in areas where the flux is negative.

The cluster size is set to 1 and the cluster energy to 0 in this model.

If this keyword is used, it should be the last keyword on the command line. The use of this model is implied by the presence of the FLUX-INTERVAL keyword.

8.23.12.1: FLUX-INTERVAL

The flux interval between 2 successive points on the track.

The flux interval is specified in units of V.

This keyword is only used by the CONSTANT-FLUX-INTERVALS model.

[Default: 10 V.]

8.23.13: representations

The track is plotted using the following representations:

The track location and, when using the Heed model also the clusters, are shown usually as last elements of a figure to ensure that they are not hidden under drift lines.

In other models than Heed, the track location is plotted but the cluster locations are not marked.

Section 8.24: XT-PLOT

Produces an x(t) plot: the relation between the position of a track and the drift time. This is a calibration curve used by the track reconstruction program.

The XT-PLOT algorithm works as follows:

  1. From around the SELECTed wires, a number of drift lines are computed (see LINES) drifting them backwards from the wire.
  2. The crossing points of these drift lines are determined with a series of lines at an angle to the y-axis and crossing the x-axis at regular intervals (see xmin-xmax and xstep). The lines will be referred to as 'minimisation lines'. For each of the crossing points, the drift time is interpolated on the drift line.
  3. On a subset (see jump) of the minimisation lines the 3 smallest drift times are kept, drift lines from the corresponding crossing points are computed to enhance the accuracy of the time estimate, and these 3 points are then used as start for a parabolic minimisation procedure with a limited number of iterations (see the itermax) and which is declared to converge if the minimum drift time doesn't change much (see eps).
  4. The results are printed (see PRINT-XT-RELATION), plotted (see PLOT-XT-RELATION and SCALE) and output to a dataset (see DATASET).

Note that there is another instruction in Garfield, ARRIVAL-TIME-DISTRIBUTION, that serves approximately the same purpose. The differences between XT-PLOT and ARRIVAL are summarised in the table below. As can be seen from the table, ARRIVAL provides more detail than XT-PLOT, which in return is faster.

For accurate calibration, the use of signals is recommended. This permits, in addition to all the features ARRIVAL, processing of the signals by electronics and the setting of a true threshold.

-----------------------------------------------------------------------
Aspect    ARRIVAL                        XT-PLOT
-----------------------------------------------------------------------
input     complete gas tables,           drift velocity and optionally
          clustering properties          diffusion and Lorentz angle
          (spacing, cluster size)        tables
method    Monte Carlo generation of      parabolic minimisation of the
          tracks with clusters           drift time over lines
included  drift velocity, Lorentz        drift velocity, Lorentz angle,
          angle, diffusion, attachment,  optionally also diffusion
          cluster spacing and size       over the fastest drift line
output    mean, median and RMS of        minimum drift time, diffusion
          selected electrons             over the fastest drift line
-----------------------------------------------------------------------

Format:

XT-PLOT [DATASET dsname [member] [REMARK remark] ...
        [ANGLE angle] ...
        [X-RANGE xmin xmax]  [X-STEP xstep]  [JUMP jump] ...
        [ITERATIONS {YES|NO|itermax}]  [PRECISION eps] ...
        [LEFT-ANGLE-RANGE lmin lmax]  [RIGHT-ANGLE-RANGE rmin rmax] ...
        [PRINT-XT-RELATION | NOPRINT-XT-RELATION] ...
        [PLOT-XT-RELATION | NOPLOT-XT-RELATION] ...
        [SCALE min max]

Examples:

XT-PLOT
XT DATASET lib.dat xt1 PRECISION 1E-2

(The second example will produce fairly quickly a crude x(t).)

8.24.1: DATASET

Requests output of the x(t) relation to a dataset [no dataset is written by default].

8.24.2: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

8.24.3: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

8.24.4: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset. The default remark for x(t) relations states the wire number and the angle.

8.24.5: angle

The angle of the lines over which the drift time is minimised, measured with respect to the y-axis. The accuracy of the calculations becomes less when this angle becomes large.

[Default: 0 degrees.]

8.24.6: xmin-xmax

The range in x to be covered by the x(t) relation.

[By default the whole x-range of the drift area is taken.]

8.24.7: xstep

The distance between successive x points for which a corresponding minimal drift time is computed.

[By default chosen such that the step size is a reasonable number for about 20 data points.]

8.24.8: jump

The number of points between two accurately calculated points. The drift times for the intermediate points are obtained by interpolating the minimising drift line from the adjacent points, a procedure that is slightly less accurate than full drift line calculation.

[By default, no point is interpolated.]

8.24.9: itermax

The maximum number of iterations allowed.

[Default: 5.]

8.24.10: eps

An accuracy parameter, to be adjusted with great care.

[Default: 1E-4.]

8.24.11: angle_range

To save CPU time whilst gaining precision, it sometimes makes sense to explore only a limited angular range as seen from the target sense wire.

This option should be used with great caution if a magnetic field is present since the drift lines in this case normally approach the wire at a (substantial) angle.

[The default range is +90 to -90 degrees both left and right.]

8.24.12: PRINT-XT-RELATION

Requests a printout of the x(t) relation.

[On by default.]

8.24.13: PLOT-XT-RELATION

Requests a graph of the x(t) relation.

The graph usually shows 2 curves:

Both curves are interrupted if the procedure has doubts about the accuracy of a neighbouring point - markers are used if both neighbours of a reliable point are considered unreliable.

[On by default.]

8.24.14: SCALE

Can be used to force a vertical scale in the x(t) relation plot, e.g. when you wish to overlay several of them.

Section 8.25: WRITE-ISOCHRONES

Use this command to write out the coordinates of the points used for the isochrones as a result of the last DRIFT command.

This statement should be issued after the DRIFT command.

Format:

WRITE-ISOCHRONES DATASET dsname [member] [REMARK remark]

Example:

WR-ISO 'test data b'

(Writes the isochrones to the VM/CMS dataset TEST DATA on the users B disk.)

8.25.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

8.25.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

8.25.3: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset.

Section 8.26: WRITE-TRACK

Once a track has been prepared with PREPARE-TRACK, it can be written to a dataset for later retrieval with GET-TRACK.

Format:

WRITE-TRACK DATASET dsname [member] [REMARK remark]

Example:

WR-TR 'disk$scratch:[pubzh.work.garfield]track.dat'

8.26.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

8.26.2: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

8.26.3: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset.

Chapter 9: &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 build an hopefully detailed simulation of your signal.

Section 9.1: overview

The instructions of the signal section fall in 5 categories:

Setting parameters:

Command Short description
AREA Sets the size of the plotting area
AVALANCHE Sets the avalanche model
FOURIER Number of Fourier terms (periodic cells)
GRID Grid density for PLOT-FIELD
INTEGRATION-PARAMETERS Drift line integration parameters
OPTIONS Various printing and plotting options
RESOLUTION Sets the time window of the signals
SELECT Establishes the list of sense wires
TRACK Sets the track for which a signal is generated

Computing and processing a signal:

Command Short description
ADD-NOISE Adds noise to the signals
CONVOLUTE-SIGNALS Convolutes signals with a transfer function
PLOT-SIGNALS Plots the signals
SIGNAL Simulates a signal
WRITE-SIGNALS Stores a signal in a dataset

Service instructions:

Command Short description
PREPARE-TRACK Prepare a track for interpolation
GET-TRACK Retrieve a a prepared track from a dataset
WRITE-TRACK Save a prepared track in a dataset

Debugging instructions:

Command Short description
CHECK Verify proper functioning
PLOT-FIELD Plots the signal induction field

Note: There are procedures that perform signal related tasks: GET_RAW_SIGNAL, GET_SIGNAL, INDUCED_CHARGE, LIST_RAW_SIGNALS, STORE_SIGNAL, THRESHOLD_CROSSING, WEIGHTING_FIELD and WEIGHTING_FIELD_3.

Section 9.2: ADD-NOISE

This statement is meant to add noise to the signals, but it can be used to add other things to the signal too.

The noise function is evaluated separately for each wire, but the same noise is added to the direct and cross-induced parts of the signals.

Format:

ADD-NOISE NOISE-FUNCTION function

Example:

ADD-NOISE NOISE-FUNCTION -0.01*RND_POISSON(30)

In this example, each of the sampling points of the signal has a Poisson distributed number with mean 30, multiplied by -0.01, added to it.

9.2.1: function

The noise function can be a function of T, the time in microsec corresponding to the signal sample. Such a dependence is of course not required.

There is no default function, but the function is remembered

Section 9.3: AREA

Changes the area in which electrons and ions are allowed to drift. This is also the part of the chamber that is plotted.

Formats:

See the AREA command of the field section.

Section 9.4: AVALANCHE

Chooses the type of avalanche to be used in the simulation.

No default type of avalanche is set - you must therefore issue an AVALANCHE command prior to any signal calculation.

Only avalanches generated by electrons that hit an electrode (a wire, a plane, the tube, a solid) are affected by this statement. In particular, avalanches in a field map for which no solids have been defined, are not affected by this statement.

Format:

AVALANCHE {EXPONENTIAL mean | ...
           FIXED factor | ...
           FIXED-TOWNSEND | ...
           GAUSSIAN mean relative_sigma | ...
           POLYA-FIXED [mean [theta]] | ...
           POLYA-TOWNSEND [theta] | ...
           TOWNSEND}

Examples:

aval exp 1e4
aval townsend

9.4.1: EXPONENTIAL

The multiplication factors are approximately exponentially distributed provided the mean multiplication is "average".

For large fields, deviations are observed which can be modeled better with a Polya distribution.

[Default: none, you have to specify the mean multiplication.]

9.4.2: FIXED

Results in a fixed multiplication by the factor that you specify.

[Default: none, you have to specify the multiplication factor.]

9.4.3: FIXED-TOWNSEND

The Townsend coefficient is integrated over the drift line, and the integral is exponentiated yielding a multiplication factor.

The multiplications obtained with this option are constant for a given drift path. They may vary when the Monte Carlo drift line integration routines are used since these introduce variations in the drift path.

9.4.4: GAUSSIAN

Not a physical choice for a single avalanche but sometimes used when many exponentially distributed avalanches overlap, resulting in a gamma distribution - which is similar in shape to a Gaussian.

Please note that the 2nd argument is a relative, not an absolute, standard deviation. If you use for instance

avalanche gaussian 20000 0.5

then you'll end up with normally distributed multiplication with mean 20000 and a sigma of 10000.

[Default: none, you have to specify both the mean and the relative standard deviation.]

9.4.5: POLYA-FIXED

The mean multiplication does not depend on the drift line (you specify the number as first argument) but the fluctuations are according to a Polya distribution with parameter theta.

The Polya distribution is a gamma distribution that matches reasonably well the fluctuations in a cylindrically symmetric amplication region. The meaning of the parameter theta is described in the paper by G. D. Alkhazov, NIM 89 (1970) 155-165.

When theta is set to 0, an exponential distribution is obtained.

[The default value for the mean multiplication is 1, the default setting of the theta parameter is 0.5.]

9.4.6: POLYA-TOWNSEND

The mean multiplication is obtained by integrating the Townsend coefficient over the curent drift line and the fluctuations are according to a Polya distribution with parameter theta.

The Polya distribution is a gamma distribution that matches reasonably well the fluctuations in a cylindrically symmetric amplication region. The meaning of the parameter theta is described in the paper by G. D. Alkhazov, NIM 89 (1970) 155-165.

When theta is set to 0, an exponential distribution is obtained. If theta < 0, the distribution is "concave", while for theta > 0 the distribution assumes the more usual shape with a maximum.

The shapes can be examined with the following statements:

Say "Please enter theta"
Parse terminal theta
Call book_histogram(ref,100,0.0,5.0)
For i From 1 To 50000 Do
   Call fill_histogram(ref,rnd_polya(theta))
Enddo
!opt log-y
Call plot_histogram(ref,`Multiplication`,`Polya distribution`)
Call plot_end

Additional fluctuations are obtained when the Monte Carlo drift line integration routines are used since these introduce variations in the drift path.

[The default value for theta is 0.5.]

9.4.7: TOWNSEND

The Townsend coefficient is integrated over the drift line, and the integral is exponentiated. The result is used as mean of an exponential distribution of multiplications.

This is similar to the EXPONENTIAL option, but here the mean of the distribution may be different for each cluster.

Additional fluctuations are obtained when the Monte Carlo drift line integration routines are used since these introduce variations in the drift path.

Section 9.5: CHECK

A debugging instruction, checking signal related routines.

Format:

CHECK [AVALANCHE] ...
      [DIFFUSION] ...
      [CLUSTER] ...
      [RANGE min max] ...
      [FROM x y] ...
      [N n] ...
      [BINS nbin]

Example:

CH AVALANCHE FROM 5 6 BINS 50

Section 9.6: CONVOLUTE-SIGNALS

Once SIGNAL has computed the currents induced in the electrodes of the chamber, they would normally be written out with WRITE-SIGNALS for further processing by programs like Spice (see http://wwwcae.cern.ch/Pspice/Pspice.html).

Signal processing in Garfield is limited to convoluting the induced currents with transfer functions and to addition of certain types of noise with ADD-NOISE.

The CONVOLUTE-SIGNALS command convolutes all signals that are available at the moment the command is issued, with the transfer function that is specified. You may issue several of these commands in succession.

The transfer function is only evaluated once for all signals. The transfer function should therefore not depend on random number generators.

Format:

CONVOLUTE-SIGNALS ...
     TRANSFER-FUNCTION { function  |  transfer VS time } ...
     [ADD-ON-FUNCTION add] ...
     RANGE tmin tmax

Example:

convolute-signals ...
     transfer-function 250*(6*t/0.025)**6*exp(-6*t/0.025) ...
     range 0 2000

(This example, taken from an Atlas muon tube study, simulates the response of a pre-amplifier.)

9.6.1: TRANSFER-FUNCTION

The transfer function, which can be specified in either of two ways:

There is no default transfer function, but the transfer function is remembered from one call to the next.

9.6.2: ADD-ON-FUNCTION

Some transfer functions contain, in the time domain, a delta distribution term. This is for instance the case of pole/zero filters which have as transfer functions (modulo overall constant factors):

       s + 1/t1
F(s) = -------- ,   F(t) = (1/t1 - 1/t2) * exp(-t/t2) + delta(t)
       s + 1/t2

To simulate such a filter, one would convolute with exp(-t/t2) and add the original signal on top.

The function to be added is allowed to be a function of the time, written as T, and of the signal, written as SIGNAL. In the case of the example, one would therefore type

CONVOLUTE TRANSFER-FUNCTION 0.2*EXP(-T/0.012) ADD SIGNAL

[By default, no function is added.]

9.6.3: RANGE

The range over which the transfer function is valid, beyond this range the transfer function is set to 0.

[By default, the range is set to [0, 1E10] microsec.]

Section 9.7: FOURIER

In periodic cells, the accuracy of the signal calculation depends amongst others on the number of periods taken into account. A high number of periods only leads to improved precision though if there are equipotential planes in the cell. The number of terms must be an integral power of 2 [default: 1 term].

Format:

FOURIER terms

Example:

FOURIER 16

(Note that this setting may require a fantastic amount of disk I/O !)

Section 9.8: GET-TRACK

Retrieves a prepared track from a dataset with WRITE-TRACK.

Format:

See the GET-TRACK command in the drift section.

Section 9.9: GRID

Sets the density of sampling points on the grid. This number is usually of the order of 25 for vector plots like those made in response to the PLOT-FIELD instruction.

The grid is common to all sections.

Format:

GRID  number_of_steps_in_x  [number_of_steps_in_y]

Example:

GRID 25 15

9.9.1: number

Number of equal grid divisions.

You may supply either 1 or 2 arguments. If the 2nd argument is omitted the first value will be used for both the x (or r) and the y (or phi) spacing.

[Default is 25 for both.]

Section 9.10: INTEGRATION-PARAMETERS

See the INTEGRATION-PARAMETERS command in the drift section.

Section 9.11: OPTIONS

In addition to the top level OPTIONS, and the OPTIONS of the drift section, the following options related to signal calculations are available:

Format:

OPTIONS [CLUSTER-PRINT|NOCLUSTER-PRINT] ...
        [CLUSTER-PLOT|NOCLUSTER-PLOT] ...
        [CONTOUR-ALL-MEDIA | CONTOUR-DRIFT-MEDIUM] ...
        [NOWIRE-MARKERS | WIRE-MARKERS] ...
        [NOCHECK-MAP-INDICES | CHECK-MAP-INDICES]

Example:

OPT NOCLUSTER-PRINT

9.11.1: CLUSTER-PLOT

Requests that, while SIGNAL runs, a plot be produced of the track, the clusters, the electron drift lines and the drift lines of the ions produced in the avalanches.

The electron drift lines are plotted with representation E-DRIFT-LINE, the ions with ION-DRIFT-LINE.

The various elements of the track are shown with their respective representations.

[This option is initially on.]

9.11.2: CLUSTER-PRINT

Requests printing of a table of clusters.

On certain systems, the graphics and printed output appear on the same screen. If both CLUSTER-PLOT and CLUSTER-PRINT are desired, it is on such systems advisable to redirect the printed output since the output of these 2 options is produced simultaneously.

[This option is initially on.]

9.11.3: CONTOUR-ALL-MEDIA

Requests that contours be drawn across all non-conducting media.

This option is ignored if the field is computed from wires and planes.

[This is default.]

9.11.4: CONTOUR-DRIFT-MEDIUM

Requests contours be drawn exclusively in the material that has been designated as drift medium.

This option is ignored if the field is computed from wires and planes. The option is honoured only if the dielectric constants are present in the field map.

[Contours are by default drawn in all media.]

9.11.5: WIRE-MARKERS

If active, wires will be plotted as markers and not as circles with the size of the wire.

For further information, see the WIRE-MARKERS option in the cell section.

9.11.6: CHECK-MAP-INDICES

Requests a verification of the map index calculation.

See the CHECK-MAP-INDICES option in the field section for further information.

Section 9.12: PLOT-FIELD

Plots quantities related to signal computations in various ways, such as vector diagrams, a graph, a surface plot and an histogram.

The main quantities of interest in this context are the so-called weighting_field and the charges induced in an electrode by electrons and ions drifting from a given point.

The weighting field and the induced charge are plotted seperately for each electrode that is read out. You can however limit the set of plots to a subset of electrodes.

There are related instructions in the field and drift sections.

Format:

PLOT-FIELD [CONTOUR [f1]   [RANGE {cmin cmax | AUTOMATIC}] ...
                           [N n] ...
                           [LABELS | NOLABELS]] ...
           [GRAPH [f2]     [ON f_curve] ...
                           [N n]] ...
                           [SCALE min max] ...
                           [NOPRINT | PRINT] ...
           [HISTOGRAM [f3] [RANGE {hmin hmax | AUTOMATIC}] ...
                           [BINS nbin]] ...
           [SURFACE [f4]   [ANGLES phi theta]] ...
           [VECTOR [f5 f6]] ...
           [GROUP {ALL | sense }] ...
           [TIME-WINDOW tmin tmax] ...
           [RUNGE-KUTTA-DRIFT | MONTE-CARLO-DRIFT]

If you don't manage to fit all this on a single line, remember that lines that end on an ellipsis are continued on the next.

Examples:

plot-field hist status_e vector surf cont
plot-field contour time_ion range 1000 3000

(The first example makes most of the plots using default functions and ranges - useful as a first call. The result will be an histogram that shows where electrons end up, a vector plot of the weighting field and a contour plot of the currents induced by single electrons released from the various locations. The second example makes a contour plot of the ion drift time.)

9.12.1: functions

All functions in the description of the PLOT-FIELD command (f1, f2 ... f6) may depend on the following set of variables:

Symbol Meaning Note
X, Y, Z Position R, PHI for polar cells
EX, EY, EZ, E E-field at (x,y,z) ER, EPHI for polar cells
EWX, EWY, EWZ, EW Weighting at (x,y,z) EWR, EWPHI for polar cells
BX, BY, BZ, B B-field at (x,y,z) only if there is a B-field
VDX, VDY, VDZ, VD Local e- drift velocity VDR, VDPHI for polar cells
TIME_E Drift time for electrons -
TIME_ION Drift time for ions -
STATUS_E Drift status for electrons a number, not a string
STATUS_ION Drift status for ions a number, not a string
Q_E Charge induced by an e- -
Q_ION Charge induced by an ion -

Other variables can be added on request.

9.12.1.1: charges

The induced charges are computed by first calculating a drift line of the requested type and then integrating the internal product of drift velocity and weighting field over the drift line. The charge thus obtained is multiplied with the charge of the particle that has been drifted.

The charge should be +1 or -1 for a particle drifting from the read-out electrode to another conductor and 0 for a particle that drifts between conductors that are not read out.

The charge induced over a given path should, apart from the sign, should not depend on the type of particle that drifts. However, in the presence of a magnetic field, electrons and ions will in general follow different paths, may therefore end up at different points, and hence induce different charges.

Charges are expressed in multiples of the electron charge.

The electrode whose weighting field is to be used can be set with the GROUP keyword. You can limit the charge integration to a time window by means of the TIME-WINDOW keyword.

9.12.1.2: status

The status codes are the numeric status codes as listed in the status section of the drift section background.

9.12.1.3: times

The times are the total drift time for particles of the selected type from the position at which the function is to be evaluated until the particle leaves the AREA, hits an electrode, exceeds the maximum number of steps, is abandoned etc.

The times are expressed in microsec.

9.12.1.4: weighting_field

The weighting field is the field with which the drift velocity of a moving charge is multiplied to obtain the current induced in the various electrodes.

There is one such field per electrode or per group of sense wires.

This field is computed by setting the read-out electrode to unit voltage and earthing all other conductors.

The unit of the weighting field is 1/cm.

9.12.2: contour

Produces a plot of the lines of equal function values.

Contours are drawn in the part of the viewing plane that is located within the current AREA box.

The contours are labeled with the function value if the LABEL option is on (which is by default the case).

If you request AUTOMATIC scaling of the range, contours are drawn at decent function heights covering the range of the function on the AREA. The number of contours is used to compute a rough distance between two contours; the distance is rounded downwards. The number of contours actually drawn may therefore be larger than the number you request.

The contours are drawn with the representation CONTOUR-NORMAL and are labeled with CONTOUR-LABELS.

[The default function is Q_E, the charge induced on the read-out electrode by an electron drifting from (x,y,z). The contour range is by default adjusted automatically. By default, about 20 contours are plotted.]

9.12.3: graph

The function is evaluated on the track or on the curve specified with the ON keyword.

The geometric aspects of the track, if used, should be set by means of the TRACK command before calling PLOT-FIELD. Other aspects of the track, such as the clustering model, are not used in the present context.

A curve should be parametrised in terms of T which will run from 0 to 1. All 3 coordinates of the curve should be specified. Note that ON expects only one argument, the parametrisation should therefore be enclosed in quotes, e.g.

'cos(pi*t),sin(pi*t),0'
would be appropriate to describe a semi-circle in the z=0 plane.

The SCALE option can be used to force a vertical scale in the plot, this can for instance be useful if you intend to overlay various graphs.

If you select the PRINT option, then the values plotted in the graph will also be printed out. Rerouting of the output (> file) can be used to write the values to a file.

The number of sampling points can be set with N.

[The default function is Q_E, the charge induced on the read out electrode by an electron drifting from (x,y,z). The default number of sampling points is MXLIST, 200 or 1000 depending on the compilation parameters.]

9.12.4: histogram

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are entered in an histogram.

This kind of plot can be useful to estimate for instance the spread in drift time over a given region.

The automatic search for proper binning (AUTOMATIC) uses the first few entries to set the range. Since the grid is scanned in a regular sequence, these entries are not necessarily representative for the entire sample, in particular if the number of bins is small compared to the grid size. See AUTOSCALE for details on the automatic binning procedure.

[The default function is Q_E, the charge induced on the read out electrode by an electron drifting from (x,y,z). The default preset to 100 and the range is by default chosen automatically.]

9.12.5: surface

The function is sampled over a GRID of points in the part of the current viewing plane that is located inside the AREA box. The function values are presented as a three dimensional plot.

The plot is first rotated by phi degrees around the z-axis and then tilted by theta degrees from the z-axis.

This plot is decorative but it is generally agreed upon that it is hard to extract any meaningful information from it ...

[The default function is Q_E, the charge induced on the read out electrode by an electron drifting from (x,y,z). The default viewing angles are 30 and 60 degrees. The viewing angles are remembered from one call to the next.]

9.12.6: vector

This plot shows the flow of a 3-vector sampled on a GRID of points in the part of the current viewing plane that is located inside the AREA box. The vectors are projected onto the current viewing plane.

The z-component is set to 0, if not explicitely specified. For other than (x,y) views, this may give incorrect impressions.

The vectors are normalised in 3 dimensions when they are plotted - the length of the vectors shown does not contain information on the magnitude of the quantity that is plotted. A vector that appears point like has no component in the viewing plane.

It is advisable to have roughly equal ranges in view of the scaling that is performed on the vectors.

The vectors are plotted using the FUNCTION-1 representation. The appearance of the arrow is influence by the ARROW-TIP-ANGLE and ARROW-TIP-LENGTH settings.

[The default functions are EWX, EWY, EWZ, i.e. the weighting field.]

9.12.7: GROUP

This is followed by the number of a read-out group. Signals are summed over the elements that compose a read-out group - signals for the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[By default, all sense wire groups are plotted.]

9.12.8: TIME-WINDOW

Specifies the time window over which the charges Q_E and Q_ION are to be integrated.

The lower time limit may be specified as START, the upper time limit as END (or INFINITY).

[When no time window is given, the charge is integrated from the moment the particle starts to drift until the moment it stops. The time window is reset each time PLOT-FIELD is called.]

9.12.9: RUNGE-KUTTA-DRIFT

Requests the use of the Runge_Kutta_Fehlberg algorithm for computing drift lines.

Runge Kutta integration is easier to use than Monte Carlo stepping in that the integration parameters are more tolerant.

The parameters controling the accuracy are adjusted for chambers that are several centimeters large. When studying much smaller structures, at the micron scale, one may wish to request more accuracy.

The Runge Kutta algorithm is well suited for smooth fields, such as those obtained with analytic potentials. The field computed from field maps is sometimes not even continuous, and one should in such cases prefer the Monte Carlo algorithm.

[The initial default is RUNGE-KUTTA-DRIFT.]

9.12.10: MONTE-CARLO-DRIFT

Requests Monte_Carlo calculation of a drift path, instead of a Runge_Kutta_Fehlberg integration.

This option is particularly interesting used in conjuction with drifting from a TRACK and on which clusters are generated with HEED.

When using this option, care has to be taken that the step size has been set to a value appropriate to the chamber, see in particular the step_size as set with the INTEGRATION-PARAMETERS command.

[The initial default is RUNGE-KUTTA-DRIFT.]

Section 9.13: PLOT-SIGNALS

Plots the signals. The graphs contain either one or two curves, depending on whether cross induced currents have been computed or not.

Format:

PLOT-SIGNALS [TIME-WINDOW {AUTOMATIC | tmin tmax}] ...
             [RANGE {AUTOMATIC | smin smax}] ...
             [WIRES {ALL | ACTIVE | numbers, labels}] ...
             [CROSS-INDUCED-SIGNALS | NOCROSS-INDUCED-SIGNALS] ...
             [DIRECT-SIGNALS | NODIRECT-SIGNALS]

Example:

pl-sig time 2.7 3.1 wire 1

Plots the signal on wire 1 in the time window [2.7,3.1] microsec.

9.13.1: TIME-WINDOW

Sets the time window within which you wish to look at the signals.

If you select AUTOMATIC, then only the part of the signals that is non-zero will be plotted.

By default: the entire time range is shown.

9.13.2: RANGE

Sets the vertical scale of the graphs.

[By default, the signal within the time window establishes the full scale of the graphs. This is also what is done if you ask for AUTOMATIC.]

9.13.3: WIRES

Normally, all non-zero currents on the SELECTed wires are shown.

If you're interested in only a subset of these, then list them either by wire number or by wire label after WIRES.

9.13.4: CROSS-INDUCED

Requests that the cross induced currents, if available, are shown.

[By default, these currents are shown if available.]

9.13.5: DIRECT-SIGNALS

Requests that the direct currents are shown.

[This is the case, by default.]

9.13.6: representations

The direct current is shown with representation FUNCTION-1, the cross induced current with representation FUNCTION-2.

Section 9.14: PREPARE-TRACK

Track preparation is a required step when using the INTERPOLATE-TRACK option of the SIGNAL command.

Format:

See PREPARE-TRACK in the drift section.

Section 9.15: REPEAT

+---------------------+
| Statement withdrawn |
+---------------------+

The REPEAT statement used to tell the SIGNAL command that you wish to repeat the calculation several times.

Old format:        New format:

REPEAT 100 For i From 1 To 100 Do SIGNAL SIGNAL Enddo

Section 9.16: RESOLUTION

Enters the size and granularity of time window in which you want to study the signals.

By default, signals start at t=0 and are sampled every 0.01 microsec. The number of samples is by default MXLIST, usually 200 or 1000 depending on the compilation flags that were selected.

The ADD option of the SIGNAL command can not be used on the first signal that is computed after a RESOLUTION command.

Format:

RESOLUTION t_start t_step  [n_step]

Example:

RES 0.5 0.01 200

(This is a proper setting if your signals never start before 0.5 microsec and decay almost fully before 0.5+200*0.01=2.5 microsec.)

Section 9.17: SELECT

Selects and groups the electrodes which are to be handled specially. The selection is common to all sections, but the interpretation of the selection is left to the individual instructions.

The signals for electrodes in a single group are summed.

The ADD option of the SIGNAL command can not be used on the first signal that is computed after a SELECT command.

Format:

See SELECT

Example:

SEL (1 S) 2 F

(Put wire 1 together with all S wires in one group, make wire 2 a group of its own and do the same for each of the F wires.)

Section 9.18: SIGNAL

This instruction computes the signals on the electrodes in the chamber that result from the passage of a charged particle.

These signals can be further processed externally with electronics simulation programs (WRITE-SIGNALS). Inside Garfield, one can do basic signal manipulations such as convolution with transfer functions (CONVOLUTE-SIGNALS), adding noise (ADD-NOISE) and determining threshold crossings (THRESHOLD_CROSSING).

Garfield distinguishes two kinds of signals: the "direct" and the "cross induced" signals. Direct signals arise from an avalanche on a read-out electrode. These signals are always computed. Cross induced (or indirect) signals are all other currents induced by moving charges anywhere in the chamber. These signals are only computed on request.

Before issuing a SIGNAL instruction, one has to

Further, it is advisable to use the CLUSTER-PLOT option for the first few signals to verify that the AREA is sufficiently large, and that the INTEGRATION-PARAMETERS are properly set.

Format:

SIGNAL [ANGULAR-INTEGRATION-POINTS n_angle] ...
       [ANGULAR-SPREAD {f_angle | FLAT} | NOANGULAR-SPREAD] ...
       [ATTACHMENT | NOATTACHMENT] ...
       [AVALANCHE | NOAVALANCHE] ...
       [AVERAGE-SIGNAL n_average | SAMPLE-SIGNAL] ...
       [DIFFUSION | NODIFFUSION] ...
       [ELECTRON-PULSE | NOELECTRON|PULSE] ...
       [INTERPOLATION-ORDER n_order] ...
       [ION-ANGLES {n_ion | NOSAMPLING}] ...
       [ION-TAIL | DETAILED-ION-TAIL | ...
        NONSAMPLED-ION-TAIL | NOION-TAIL] ...
       [ION-THRESHOLD thr] ...
       [RUNGE-KUTTA-DRIFT-LINES | MONTE-CARLO-DRIFT-LINES] ...
       [NEW | ADD] ...
       [NOCROSS-INDUCED | CROSS-INDUCED] ...
       [NOINTERPOLATE-TRACK | INTERPOLATE|TRACK]

Example:

SIGNAL CROSS-INDUCED

9.18.1: ADD

Signals from repeated simulations will be summed, electrode by electrode. This option is the reverse of NEW.

This option can for instance be used to study two-track resolution.

The ADD option can not be used after:

[By default, signals are not summed.]

9.18.2: ANGULAR-INTEGRATION-POINTS

When computing the weight assigned by the ANGULAR-SPREAD function to each of the ION-ANGLES, the function is integrated using the Newton-Raphson technique with 2*n_angle+1 points.

Use of this keyword implies the ION-TAIL model of ion tail calculation.

[By default, n_angle is set to 2.]

9.18.3: ANGULAR-SPREAD

In the ION-TAIL model, you have the possibility to spread the ions that are produced in the avalanche, around the wire.

The spread is to be provided as a probability distribution in terms of the angle PHI (in radians) between the incidence angle of the electron and the angle at which the ions start to drift away from the wire.

In the ION-TAIL model, ions start only from discrete angles around the wire. The number of such angles can be set with ION-ANGLES. The function that you specify is integrated around the nearest angles using Newton-Raphson integration with ANGULAR-INTEGRATION-POINTS sampling points.

The spread function may be specified as FLAT, in which case the avalanche is assumed to wrap uniformly around the wire. You may also specify NOANGULAR-SPREAD, in which case the ions will be drifted back from the nearest angular sampling point only.

Use of this keyword implies the ION-TAIL model of ion tail calculation.

Example:

Global sigma 30
signal cross ion-angles 1000 ang-spread 'exp(-((phi*180/(pi*{sigma}))**2))'

This example assumes a Gaussian angular spread with a sigma of 30 degrees. The number of discretisation points is set to 1000 in this example.

References:

[1]
G. Charpak et al., NIM 148 (1978) 471-482
[2]
T.J. Harris & E. Mathieson, NIM 154 (1978) 183-188
[3]
E. Mathieson & T.J. Harris, NIM 159 (1979) 483-187
[4]
Harry van der Graaf, PhD thesis, TU Delft (1986)

9.18.4: ATTACHMENT

Attachment coefficients will be taken into account for signal calculations. They occur at two instances:

9.18.5: AVALANCHE

Enables the avalanche setting chosen with AVALANCHE. NOAVALANCHE leads to a fixed multiplication factor of 1.

Both ELECTRON-PULSE and DETAILED-ION-TAIL require Townsend coefficients. They use these coefficients, provided they are available, regardless of the setting of this option.

9.18.6: AVERAGE-SIGNAL

Switching on this option makes that the total induced charge corresponds closely to the integral of the signal that is output by the program. This is less trivial than it may sound since signals can contain structure on a much smaller time scale than the binning of the signal.

The averaging is done with an 2*n_average+1 point Newton- Raphson integration over a time bin centered at the point in time indicated in the output.

[By default, 5 points are used, i.e. n_average is set to 2.]

9.18.7: CROSS-INDUCED

Requests the computation of the signal induced in all electrodes that are currently SELECTed for read-out, by all ionisation electrons and avalanche ions that drift in the chamber.

The part of the signal that is due to ionisation electrons that hit the electrode and avalanche ions that are drifting away from the electrode is called the "direct" component, the remainder of the signal is called "indirect". The two components are shown separately by e.g. PLOT-SIGNALS.

If CROSS-INDUCED is off, then Garfield computes only the direct signals. If the field is derived from a field map, the classification of signals is based on the solids. In the absence of solids, there can not be direct signals.

The option can be used in conjunction with DETAILED-ION-TAIL.

[The option is initially switch off.]

9.18.8: DETAILED-ION-TAIL

Adds an ion tail to the computed signal according to a more detailed model in which the ions do not necessarily start at the wire surface or in the vicinity of other electrodes. Rather, they start where they are produced during the electron avalanche.

This model is to be prefered in case the avalanche region is substantial or when the integrated charge is important. This model must also be used in case the electrons hit other electrodes than wires (planes, tube, solids). Otherwise, the simpler ION-TAIL and NONSAMPLED-ION-TAIL models will be faster.

Ion tail calculation requires the possibility of drifting ions from the vicinity of electrodes. To enable this, one may have to switch CHECK-ALL-WIRES off.

[The default is ION-TAIL.]

9.18.9: DIFFUSION

Varies the arrival times of the individual electrons from the clusters according to a Gaussian distribution.

[Diffusion is included by default, if diffusion data is present.]

9.18.10: ELECTRON-PULSE

Adds an electron pulse to the computed signal.

The electron pulse is computed by following the avalanche process along the electron drift line, this option therefore requires the presence of Townsend coefficients. Attachment coefficients, if present, will also be taken into account. Also the INTERPOLATE-TRACK option is not compatible with ELECTRON-PULSE.

[An electron pulse is by default not included.]

9.18.11: INTERPOLATE-TRACK

Enables the use of the prepared track, see PREPARE-TRACK.

This option can not be used together with ELECTRON-PULSE nor with DETAILED-ION-TAIL.

[Default: Even if a prepared track is available, it will by default not be used for the signal calculation.]

9.18.12: INTERPOLATION-ORDER

In order to average the signal over a time bin, the signal is interpolated with polynomials of order n_order, and then integrated using the Newton-Raphson technique over 2*n_average+1 points.

The parameter n_order should not be chosen large since especially electron pulses rise very fast. This can easily give rise to interpolated values of the wrong sign.

[A value of 1 is therefore recommended, and is also default.]

9.18.13: ION-ANGLES

When the ION-TAIL model has been selected, then the shape of the ion tail is stored for a series of electron incidence angles. For many applications, this is reasonable since:

The number of electron incidence angles for which a separate ion tail is calculated can be chosen with this keyword. A value of 1 would be suitable for cylindrically symmetric detectors, while a value of order 10-50 would be appropriate if one wishes to study stereo effects.

You may specify the number of angles as NOSAMPLING (or INFINITE) to indicate that ions should start from the point where the electron hit the wire. This choice implies the use of the NONSAMPLED-ION-TAIL model. Otherwise, using this keyword implies the use of the ION-TAIL model.

Separate ion tails are kept for the different wires on which avalanches are occuring and for the different wires on which the induced current is measured. A large setting therefore implies that a large volume of data has to be stored.

[Default: 50]

9.18.14: ION-TAIL

Adds an ion tail to the computed signal according to a simplified model in which the ions are assumed to come from the wire surface rather than from the area near the wire in which the avalanche is developing.

You may in this model choose to spread the ions that are produced in the avalanche around the wire of. This can be achieved via the ANGULAR-SPREAD keyword.

This model, for efficiency reasons, keeps ion tails from a set of angles in memory. The number of such angles can be set with ION-ANGLES. If such sampling is not desired, then you should opt for the NONSAMPLED-ION-TAIL model, which however does not offer the possibility of spreading the avalanche around a wire.

Only electrons that hit a wire and some selected solids generate a current (direct or cross induced) in this model. DETAILED-ION-TAIL should be used if the electrons hit other electrodes such as planes, the tube and solids in general.

Ion tail calculation requires the possibility of drifting ions from the vicinity of electrodes. To enable this, one may have to switch CHECK-ALL-WIRES off.

[This is the default.]

9.18.15: ION-THRESHOLD

In the detailed ion tail model, the ions are traced from the point where they were produced. This is done on a step-by-step basis of the electron drift line that generated the ions.

To save CPU time, only steps are considered in which at least a certain fraction of the total number of ions is produced.

This fraction should be set to 0 for chambers filled with, for instance, liquid Helium where the avalanche develops over a large part of the electron drift line.

For conventional gaseous counters, 10**-3 to 10**-4 would be a more appropriate choice.

Using this keyword implies the use of the DETAILED-ION-TAIL model.

[The fraction is initially set to 0.]

9.18.16: MONTE-CARLO-DRIFT

Uses the Monte_Carlo drifting routines rather the the default Runge_Kutta_Fehlberg integration routines. This option is useful if diffusion can cause electrons starting from the same starting point to reach significantly different end points.

Since all electrons from a cluster are treated independently, and since options like INTERPOLATE-TRACK can not be used in conjunction with MONTE-CARLO-DRIFT, use of this option tends to make the computations longer.

You may have to adjust the Monte Carlo parameters in the INTEGRATION-PARAMETERS statement when using this option.

[Default is RUNGE-KUTTA-DRIFT]

9.18.17: NEW

Means that summing of signals over repeated simulations does not take place.

This option is the reverse of ADD.

[This is default.]

9.18.18: NONSAMPLED-ION-TAIL

A variant of the ION-TAIL model, in which the ions start drifting from the point where the electrons hit the wire.

This model does not take the spatial extent of the avalanche into account, for which the DETAILED-ION-TAIL model should be used, nor does it provide angular spread of the ions around a wire.

Ion tail calculation requires the possibility of drifting ions from the vicinity of electrodes. To enable this, one may have to switch CHECK-ALL-WIRES off.

[The default is ION-TAIL.]

9.18.19: RUNGE-KUTTA-DRIFT

Requests the use of the Runge_Kutta_Fehlberg integration technique for drift lines.

Runge Kutta integration is easier to use than Monte Carlo stepping in that the integration parameters are more tolerant.

The parameters controling the accuracy are adjusted for chambers that are several centimeters large. When studying much smaller structures, at the micron scale, one may wish to request more accuracy.

The Runge Kutta algorithm is well suited for smooth fields, such as those obtained with analytic potentials. The field computed from field maps is sometimes not even continuous, and one should in such cases prefer the Monte Carlo algorithm.

[The initial default is RUNGE-KUTTA-DRIFT.]

9.18.20: SAMPLE-SIGNAL

If this option is switched on, the signal that the program returns corresponds to the current at the point in time indicated in the output. Any fine structure smaller than the binning is lost.

[By default, AVERAGE-SIGNAL is used with 5-point integration.]

Section 9.19: THRESHOLD

This instruction is withdrawn, use the ARRIVAL-TIME-DISTRIBUTION instruction from the drift section instead.

Section 9.20: TRACK

Specifies the kind of particle and the place where it traverses the chamber.

The track is shared between commands from nearly all sections.

Please verify both the location and the clustering model before starting a signal calculation. Some clustering models used elsewhere, e.g. a fixed number of single-electron deposits on each track, are not meaningful in the signal section.

Format:

See TRACK

Examples:

track 0 1 2 0 2 4 exp
track 0 1 2 0 2 4 muon energy 10 GeV

The track in both examples runs from (0,1,2) to (0,2,4). In the first example, the cluster spacing will be exponential and the cluster size will be derived from the data entered in the gas section. In the second example, Heed takes care of generating the clusters.

Section 9.21: WRITE-SIGNALS

Writes the current set of signals to a dataset for further processing with programs like Spice (see http://wwwcae.cern.ch/Pspice/Pspice.html).

Writing is done when the command is executed, not while the SIGNAL command runs as in versions of Garfield prior to 5.20.

Format:

WRITE-SIGNALS [DATASET dsname [member]] [REMARK remark] ...
              [FORMAT {SPICE|SCEPTRE}] ...
              [WRITE-IF condition] ...
              [UNITS units]

If you don't manage to fit all this on a single line, remember that lines that end on an ellipsis are continued on the next.

Example:

WR-SIG 'disk$scratch:[pubzh.work.garfield]signal.dat'

9.21.1: FORMAT

By default, the signals are written in a Spice readable format as a Piece Wise Linear (PWL) input signal. Information about the use of Spice at CERN can be found in http://wwwcae.cern.ch/Pspice/Pspice.html

The alternative is the Sceptre format, i.e. a comma between time and current but neither a heading nor a closing line.

In both cases, the file contains records indicating the wires on which the signal was induced and the number of records that have been written out.

Other formats can be added - please contact the author.

9.21.2: condition

Enables the user to write selectively a part of the signal to a dataset.

The condition is an expression in terms of the following variables:

Variable Meaning
SAMPLE the sample number, 1 to MXLIST
SIGNAL in case of a pure signal, the current in microAmp
TIME the time corresponding to the sample in microsec

The condition must evaluate to a Logical.

The condition is remembered, and re-used, by default from one call to the next - the initial default is 'True'.

Examples:

wr-if 'time>0.5&time<1'

wr-if 'signal<-0.02'

Call threshold_crossing(1,-0.02,`falling,plot`,n1,t1_fall) Call threshold_crossing(1,-0.02,`rising,plot`,n2,t1_rise) If 'n1<1 | n2<1' Then Say "Didn't find both a falling and a rising edge." Elseif 't1_fall > t1_rise' Then Say "Rising edge precedes falling edge." Else write-signal dataset signal.list ... write-if 'time>{t1_fall}&time<{t1_rise}' Say "Writing out the signal for {t1_fall} < t < {t1_rise}" Endif

The first 2 examples are simple applications of the write condition: writing out only the signal within a fixed time range and writing out only the portions of the signal that are below a threshold of -0.02 microAmp.

The 3rd example illustrates how one can obtain the times at which the signal passes a threshold in a given direction and to write out the signal between the rising and falling edges.

9.21.3: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

9.21.4: member

An identification string of at most 8 characters. This string is used by the various dataset commands and it is also needed if you keep more than one object (member) of the same type (cell, gas, track etc) in the same dataset.

9.21.5: remark

A string of at most 29 characters that serves as a comment helping you to recognise a member in a dataset.

9.21.6: units

By default, the time is written to the dataset in units of micro second and the current in micro Ampere. You can change this via the UNITS keyword followed by the SI units you wish:

Keyword Meaning Keyword Meaning
- - KILO-AMPERE 10^3 A
SECOND sec AMPERE A
MILLI-SECOND 10^-3 sec MILLI-AMPERE 10^-3 A
MICRO-SECOND 10^-6 sec MICRO-AMPERE 10^-6 A
NANO-SECOND 10^-9 sec NANO-AMPERE 10^-9 A
PICO-SECOND 10^-12 sec PICO-AMPERE 10^-12 A
FEMTO-SECOND 10^-15 sec FEMTO-AMPERE 10^-15 A
ATTO-SECOND 10^-18 sec ATTO-AMPERE 10^-18 A

Some commonly abbreviations of these units are recognised (e.g. nsec).

Section 9.22: WRITE-TRACK

Writes the prepared track to a dataset.

Format:

See the WRITE-TRACK command in the drift section.


Chapter 10: &STOP

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

Chapter 11: 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 | 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.

Section 11.1: DEBUG

Switches on debugging mode. Make sure you have a program listing at hand ! This may vastly increase the amount of output being produced.

This option can be set from the command line on most systems.

[Initially off by default.]

Section 11.2: IDENTIFICATION

Prints the names of a few selected subroutines when they are called.

This option can be set from the command line on most systems.

[Initially off by default.]

Section 11.3: INPUT-LISTING

Echos input lines to output.

This option can be set from the command line on most systems.

[This option is initially on by default in batch and initially off in interactive mode.]

Section 11.4: RECORDING

Requests recording all terminal input in a file, called GARFLAST.DAT, GARFLAST INPUT or garflast.dat depending on the operating system.

This option can be set from the command line on most systems.

[This option is initially off by default in batch and initially on in interactive mode.]

Section 11.5: PROGRESS-PRINT

Switching this option on, enables you to follow the progress of a few CPU intensive instructions (such as ARRIVAL and TIMING).

This option can be set from the command line on most systems.

[This option is initially off by default in batch and initially on in interactive mode.]

Section 11.6: ON-ERROR-CONTINUE

In case an input error is detected (unknown arguments, wrong syntax, invalid number etc), the command is executed using (partial) defaults.

In case repairable execution time errors are detected, whatever action needed to complete the command is taken. The command is aborted if no fix can be applied but program execution continues.

[This option is default.]

Section 11.7: ON-ERROR-SKIP

In case an input error is detected (unknown arguments, wrong syntax, invalid number etc), the command is skipped.

In case of an execution time error, the command is aborted but program execution continues. Thus for instance a cell that contains 2 wires that overlap, is flagged as not useable - and subsequent sections using cell data are skipped.

This setting is useful in batch and also interactively on machines that do not allow control-C type interrupts (stopping a command but not the program).

Note that this option has effect on some CPU intensive instructions only - the effect can, on demand, be extended to other instructions.

[ON-ERROR-CONTINUE is default.]

Section 11.8: ON-ERROR-TERMINATE

In case an input error (unknown arguments, wrong syntax etc) or an execution time error is detected, program execution is terminated.

Note that this option has effect on some CPU intensive instructions only - the effect can, on demand, be extended to other instructions.

[ON-ERROR-CONTINUE is default.]

Section 11.9: DUMP-ON-GRAPHICS-ERROR

Produces a dump when encoutering certain errors while projecting planes and removing hidden parts. Program execution is terminated after the dump has been created.

The dump for PLASPL is written to a file called "plaspl.dat" and contains the following pieces of information:

The dump for GRAREA is written to a file called "grarea.dat" and contains the following pieces of information:

The dumps for BUTFLY and BUTFLD are written to files called "butfly.dat" and "butfld.dat". These files are written after elimination of multiply occuring points. The files contain the following pieces of information:

This is a debugging option.

[This option is switched off initially.]

Section 11.10: WARN-BUT-WRITE

If an attempt is made to write a member to a dataset that already contains a member with the same name and of the same type, then a warning message will be issued but the member will be written.

Attempts to read such a member will in general lead to unexpected results: the member that already existed will be seen first and will be read instead of the newly written member.

[This is default.]

Section 11.11: WARN-AND-NOWRITE

If an attempt is made to write a member to a dataset that already contains a member with the same name and of the same type, then a warning message will be issued and the member will not be written.

Moreover, an error condition is raised and certain instructions that generate dataset output as they proceed, such as ARRIVAL and MINIMISE, will not be executed if the ON-ERROR-SKIP option is active. Program execution will be terminated if ON-ERROR-TERMINATE has been selected.

[WARN-BUT-WRITE is default.]

Section 11.12: DELETE-OLD-MEMBER

If an attempt is made to write a member to a dataset that already contains a member with the same name and of the same type, then the already existing member(s) will be marked for deletion and the new member is appended at the end.

As a result, a read will be successful.

The members marked for deletion are not physically removed from the file and can be recovered with the RECOVER dataset command. They can be removed from the file with the PURGE dataset command.

This option requires more extensive dataset access and is therefore slower than its alternatives. Use of this option is nevertheless recommended since dataset access in Garfield is usually a marginal CPU time consumer.

[WARN-BUT-WRITE is default.]


Chapter 12: Call

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 used as input, must have (one of) the types shown in the description. Input arguments can be Global variables but also expressions that result in an object of the required type. Arguments that are 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.

Variable names in the argument list of procedure calls should obey the naming conventions.

Some procedures can accept arguments of different 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.

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.

Section 12.1: overview

Service calls:

Procedure name Purpose
INQUIRE_FILE Tells whether a file exists
INQUIRE_MEMBER Tells whether a member of a library exists
INQUIRE_TYPE Returns the type of a global variables
PRINT Prints its arguments
TIME_LOGGING Enters a timing record

Numeric procedures:

Procedure name Purpose
CARTESIAN_TO_POLAR Converts Cartesian to polar coordinates
CARTESIAN_TO_INTERNAL Converts Cartesian to internal coordinates
EXTREMUM Searches for an extremum of a function
INTERNAL_TO_CARTESIAN Converts internal to Cartesian coordinates
INTERNAL_TO_POLAR Converts internal to polar coordinates
POLAR_TO_CARTESIAN Converts polar to Cartesian coordinates
POLAR_TO_INTERNAL Converts polar to internal coordinates
PREPARE_RND_FUNCTION Prepares random number generation for functions
ZEROES Searches for zeroes of a function

Cell related procedures:

Procedure name Purpose
GET_CELL_DATA Returns # of wires, coordinate system etc
GET_CELL_SIZE Returns the size of the cell
GET_PERIODS Returns the periodicities
GET_X_PLANE_DATA Returns the x-plane descriptions
GET_Y_PLANE_DATA Returns the y-plane descriptions
GET_WIRE_DATA Returns information on a wire

Gas related procedures:

Procedure name Purpose
ATTACHMENT Returns the attachment coeff. for a given E/p
DRIFT_VELOCITY Returns the drift velocity for a given E/p
GAS_AVAILABILITY Tells which gas description elements are present
GET_GAS_DATA Returns pressure, temperature and gas identifier
GET_E/P_TABLE Returns the list of E/p values in the table
ION_MOBILITY Returns the ion mobility for a given E/p
LONGITUDINAL_DIFFUSION Returns sigma_L for a given E/p
LORENTZ_ANGLES Returns the Lorentz angle for a given E/p
TOWNSEND Returns the Townsend coefficient for a given E/p
TRANSVERSE_DIFFUSION Returns sigma_T for a given E/p

Electric field calculation:

Procedure name Purpose
ELECTRIC_FIELD Computes the electric field for a given (x,y)
ELECTRIC_FIELD_3 Computes the electric field for a given (x,y,z)
FORCE_FIELD Electrostatic force component (debugging only)
INTEGRATE_CHARGE Integrates the charge contained in an area.
INTEGRATE_FLUX Integrates the E flux over a parallelogram
MAGNETIC_FIELD Computes the magnetic field for a given (x,y)
MAGNETIC_FIELD_3 Computes the magnetic field for a given (x,y,z)
MAP_ELEMENT Returns a field map element description
MAP_INDEX Returns a field map element index
MAP_MATERIAL Returns a field map material reference
PLOT_FIELD_AREA Plots the current field area

Drift line related procedures:

Procedure name Purpose
AVALANCHE Simulates an electron induced avalanche
DRIFT_ELECTRON Drifts an electron from a given (x,y)
DRIFT_ELECTRON_3 Drifts an electron from a given (x,y,z)
DRIFT_INFORMATION Returns information about the current drift line
DRIFT_ION Drifts a positive ion from a given (x,y)
DRIFT_ION_3 Drifts a positive ion from a given (x,y,z)
DRIFT_MC_ELECTRON MC drift of an electron from a given (x,y,z)
DRIFT_MC_ION MC drift of a positive ion from a given (x,y,z)
DRIFT_MC_NEGATIVE_ION MC drift of a negative ion from a given (x,y,z)
DRIFT_MC_POSITRON MC drift of a positron from a given (x,y,z)
DRIFT_NEGATIVE_ION Drifts a negatvie ion from a given (x,y)
DRIFT_NEGATIVE_ION_3 Drifts a negative ion from a given (x,y,z)
DRIFT_POSITRON Drifts a positron from a given (x,y)
DRIFT_POSITRON_3 Drifts a positron from a given (x,y,z)
ELECTRON_VELOCITY Returns the electron velocity vector at (x,y,z)
ION_VELOCITY Returns the ion velocity vector at (x,y,z)
GET_CLUSTER Returns a new cluster position
GET_DRIFT_LINE Copies the current drift line to vectors
INTERPOLATE_TRACK Performs interpolation on prepared tracks
NEW_TRACK Reinitialises the track
PLOT_DRIFT_AREA Plots the current drift area
PLOT_DRIFT_LINE Plots projections of the current drift line
PLOT_TRACK Plots the current track with clusters
RND_MULTIPLICATION Simulates multiplication over a drift line

Signal related procedures:

Procedure name Purpose
GET_RAW_SIGNAL Stores a raw signal in a 1-dimensional matrix
GET_SIGNAL Copies a signal to a 1-dimensional matrix
INDUCED_CHARGE Computes total charges induced in electrodes
LIST_RAW_SIGNALS Lists the raw signals currently in store
STORE_SIGNAL Copies a 1-dimensional matrix to a signal
THRESHOLD_CROSSING Returns threshold crossings in a signal
WEIGHTING_FIELD Computes single electrode ("weighting") fields
WEIGHTING_FIELD_3 Same as WEIGHTING_FIELD for (x,y,z) coordinates

Histogramming:

Procedure name Purpose
BARYCENTRE Computes the barycentre of an histogram
BOOK_HISTOGRAM Books an histogram
CONVOLUTE Convolutes two histograms
CUT_HISTOGRAM Returns a sub-range of an histogram
DELETE_HISTOGRAM Deletes an histogram
FILL_HISTOGRAM Fills an histogram
GET_HISTOGRAM Retrieves an histogram from a file
INQUIRE_HISTOGRAM Returns information about an histogram
LIST_HISTOGRAMS Lists the histograms currently in memory
PLOT_HISTOGRAM Plots an histogram
PRINT_HISTOGRAM Prints an histogram
REBIN_HISTOGRAM Rebins an histogram
RESET_HISTOGRAM Resets the contents of an histogram
WRITE_HISTOGRAM Writes an histogram to a Garfield library
WRITE_HISTOGRAM_RZ Writes an histogram to an RZ file
HISTOGRAM_TO_MATRIX Copies an histogram to a matrix
MATRIX_TO_HISTOGRAM Copies a matrix to an histogram

Matrix manipulation:

Procedure name Purpose
ADJUST_MATRIX Modifies on or more dimensions of a matrix
BOOK_MATRIX Creates a new matrix
DELETE_MATRIX Deletes a matrix
DERIVATIVE Computes numerically a derivative
DIMENSIONS Returns the dimensions of a matrix
EXTRACT_SUBMATRIX Returns a sub-matrix of a matrix (internal)
GET_MATRIX Retrieves a matrix from a file
INTERPOLATE Linear interpolation in an n-dimensional matrix
INTERPOLATE_i Local polynomial interpolation in a vector
LIST_MATRICES Lists the matrices currently in memory
MULTIPLY_MATRICES Multiplies 2 matrices
PRINT_MATRIX Prints a matrix
RESHAPE_MATRIX Changes the format of a matrix
SOLVE_EQUATION Solves a matrix equation
STORE_SUBMATRIX Stores a sub-matrix in a matrix (internal)
WRITE_MATRIX Writes a matrix to a file

Fitting:

Procedure name Purpose
FIT_EXPONENTIAL Fits a exponential to an histogram or to vectors
FIT_FUNCTION Fits an arbitrary function
FIT_GAUSSIAN Fits a Gaussian to an histogram or to vectors
FIT_MATHIESON Fits a Mathieson distribution to an histogram
FIT_POLYA Fits a Polya distribution
FIT_POLYNOMIAL Fits a polynomial to an histogram or to vectors

String manipulation:

Procedure name Purpose
STRING_DELETE Deletes a portion from a string
STRING_INDEX Returns the start position of a sub-string
STRING_LENGTH Returns the length of a string
STRING_LOWER Converts a string to lower case
STRING_MATCH Tells whether 2 strings match
STRING_PORTION Returns a sub-string
STRING_UPPER Converts a string to upper case
STRING_WORDS Counts the number of words in a string
STRING_WORD Returns a selected word from a string

Graphics:

Procedure name Purpose
GKS_AREA Plots an area
GKS_POLYLINE Plots a polyline
GKS_POLYMARKER Plots a polymarker
GKS_SELECT_NT Selects a normalisation transformation
GKS_SET_CHARACTER_EXPANSION Sets the character expansion factor
GKS_SET_CHARACTER_HEIGHT Sets the character height
GKS_SET_CHARACTER_SPACING Sets the character spacing
GKS_SET_CHARACTER_UP_VECTOR Sets the character up vector
GKS_SET_TEXT_ALIGNMENT Sets the text alignment
GKS_SET_TEXT_COLOUR Sets the text colour index
GKS_SET_TEXT_FONT_PRECISION Sets the text font and precision
GKS_TEXT Plots a text string
GKS_VIEWPORT Sets a viewport
GKS_WINDOW Sets a window
PLOT_AREA Plots a fill-area
PLOT_ARROW Plots an arrow
PLOT_COMMENT Places a comment on the current plot
PLOT_CONTOURS Plots 2-matrix as a set of contours
PLOT_END Closes the current plot
PLOT_ERROR_BAND Plots an error band
PLOT_ERROR_BAR Plots a series of error bars
PLOT_FRAME Plots a set of coordinate axes
PLOT_GRAPH Plots a graph
PLOT_LINE Plots a line
PLOT_MARKER Plots a series of markers
PLOT_START Starts a plot
PLOT_SURFACE Plots 2-matrix as a 3-dimensional surface plot
PLOT_TEXT Plots a text string
PROJECT_LINE Projects a line
PROJECT_MARKERS Projects a set of markers
SET_LINE_ATTRIBUTES Selects the representation to use next
SET_MARKER_ATTRIBUTES Selects the representation to use next
SET_TEXT_ATTRIBUTES Selects the representation to use next
SET_AREA_ATTRIBUTES Selects the representation to use next

Section 12.2: ADJUST_MATRIX

ADJUST_MATRIX is one of two procedures that modify the shape of an existing matrix.

ADJUST_MATRIX changes the size of a matrix in one or more dimensions, without changing the place the elements occupy. If you wish to change the number of dimensions of a matrix, then use RESHAPE_MATRIX.

ADJUST_MATRIX operates by creating a new matrix of the requested dimensions, then copying the elements from the old matrix to the same place in the new matrix. If the new matrix is smaller in any dimension, some elements are lost, even if the overall size of the matrix is larger. If a dimension of the new matrix is larger than the corresponding dimension of the old matrix, then the new elements are filled with PAD (the last argument).

Format:

CALL ADJUST_MATRIX(matrix, size_1, size_2, ... size_n, pad)

Example:

Global n=3
Call book_matrix(a,2,n)
For i From 1 To 2 Do
   Say "How many elements to initialise in row {i} ?"
   Global n_new=n
   Parse terminal n_new
   If n_new>n Then
      Call adjust_matrix(a,2,n_new,pi)
      Global n=n_new
   Endif
   For j From 1 To n Do
      Global a[i;j]=i*j
   Enddo
Enddo
Call print_matrix(a)

A matrix is initially booked as 2x3, but since the amount of data to be stored in the matrix is not a priori known, the matrix may have to be extended. This is the approach followed by the Vector command. The PAD argument is compulsory in ADJUST_MATRIX, and is likely to be used in this example.

12.2.1: matrix

The Matrix to be acted upon.

The adjusted matrix replaces the matrix given as input. This argument should therefore be modifiable, i.e. a simple name of a matrix, not an expression.

[This is a mandatory argument, no default is supplied.]

12.2.2: size

A set of Numbers, each of which specifies the length of the adjusted matrix along a dimension.

These arguments should in principle be integers, if they are not, then they are rounded to the nearest integer.

The number of dimensions of the adjusted matrix is equal to the number of size arguments.

[These are mandatory arguments, there must at least be one of them and there can be at most MXMDIM, usually 10, dimensions. No defaults are supplied.]

12.2.3: pad

A Number used to fill elements of the matrix that did not exist before the matrix was adjusted.

[This argument is mandatory, even if the adjusted matrix is smaller than the original matrix. No default is supplied.]

Section 12.3: ATTACHMENT

Returns the attachment coefficient, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the attachment coefficient is returned in 1/cm.

Format:

CALL ATTACHMENT(ex, ey, ez, attachment)

Section 12.4: AVALANCHE

Simulates an electron induced avalanche, taking diffusion, multiplication and attachment into account. A simplified version of this procedure, which neglects the spatial development of the avalanche, is available as RND_MULTIPLICATION.

An initial electron is drifted, at your choice, using either the Monte_Carlo technique or using Runge_Kutta_Fehlberg integration. When using the Monte Carlo method, care has to be taken that the step size is set properly (see INTEGRATION-PARAMETERS).

Runge Kutta Fehlberg integration is faster because diffusion is not taken into account, as a result of which far fewer drift lines have to be computed.

At each step, a number of secondary electron and ions is drawn according to the local Townsend and attachment coefficients. Newly produced electrons are traced like the initial one. The ions are drifted and their end point is recorded.

This procedure can produce a graphical representation of the avalanche, and can also return statistical information.

Format:

CALL AVALANCHE(x, y, z, option, n_electron, n_ion, ...
   formula_1, histogram_1, formula_2, histogram_2 ...)

Example:

&DRIFT
area -0.02 -0.02 0.02 0.02
int-par m-c-dist-int 0.0002
Call book_histogram(elec,50,0,2500)
Call book_histogram(ion,50,0,2500)
Call book_histogram(created,50,-0.02,+0.02)
Call book_histogram(lost,50,-0.02,+0.02)
Call book_histogram(end_e,50,-0.02,+0.02)
Call book_histogram(end_ion,50,-0.02,+0.02)
For i From 1 To 100 Do
   Call plot_drift_area
   Call avalanche(0.010,0.019,0,`plot-electron,plot-ion`,ne,ni,...
      `y_created`,created,`y_lost`,lost,`y_e`,end_e,`y_ion`,end_ion)
   Say "Electrons: {ne}, ions: {ni} (avalanche {i})"
   Call fill_histogram(elec,ne)
   Call fill_histogram(ion,ni)
   Call plot_end
Enddo
Call fit_exponential(elec,a,b,ea,eb,`plot`)
Say "Slope: {-1/b}"
!opt log-y
Call hplot(elec,`Electrons`,`Number of electrons after avalanche`)
Call plot_end
Call hplot(ion,`Ions`,`Number of ions produced in avalanche`)
Call plot_end
Call hplot(created,`y [cm]`,`Production point of electrons`)
Call plot_end
Call hplot(lost,`y [cm]`,`Absorption point of electrons`)
Call plot_end
Call hplot(end_e,`y [cm]`,`End point of electrons`)
Call plot_end
Call hplot(end_ion,`y [cm]`,`End point of ions`)
Call plot_end

After setting the AREA, the parameters for Monte Carlo drift line integration are set such that there are about 100 steps on each drift line. The output histograms are booked beforehand so as to ensure they have a common scale. Then, 100 avalanches are produced, all of which are fully plotted, after which the overview statistics are shown.

12.4.1: option

A string that can contain one or more of the following options:

Option Meaning Default
ATTACHMENT Include attachment If present
MONTE-CARLO Monte Carlo drifting Yes
NOATTACHMENT Don't include attachment If not present
NOPLOT-ELECTRON Don't plot electron drift lines Yes
NOPLOT-ION Don't plot ion drift lines Yes
NOTOWNSEND Don't include multiplication If not present
PLOT-ELECTRON Plot electron drift lines No
PLOT-ION Plot ion drift lines No
RUNGE-KUTTA Runge Kutta Fehlberg integration No
TOWNSEND Include multiplication If present

The TOWNSEND and ATTACHMENT options can only be selected if the corresponding data has been entered in the gas section.

A plot frame (e.g. with PLOT_DRIFT_AREA) has to be opened before the call to AVALANCHE if you wish to use the PLOT-ELECTRON or PLOT-ION options.

12.4.2: n_electron

The number of electrons produced in the avalanche minus the number of electrons lost via attachment.

This is an optional output parameter and should therefore be modifiable. The value assigned to this parameter on entry is not used.

12.4.3: n_ion

The number of ions produced in the avalanche.

This is an optional output parameter and should therefore be modifiable. The value assigned to this parameter on entry is not used.

12.4.4: formula

A formula that states the quantity that should be entered in the histogram. Each formula can make use of the quantities from one (and only one !) of the following sets:

If you wish to have an histogram filled only under certain conditions, then use format: `value,condition` where "value" is the quantity to be entered in the histogram and "condition" the condition under which the quantity should be entered. "value" Should evaluate to a Number while "condition" should be a Logical.

This argument should be provided in the form of a String. The string is not modified in the call.

12.4.5: histogram

A reference to the Histograms that are to receive the statistics on the avalanche process.

If this argument is of a type other than Histogram, then any storage associated with it is liberated and a new histogram is created with 100 bins and an automatically adjusted range.

You may also give an existing histogram as argument, in which case new entries will be added to it.

This is an optional parameter. Since it is used for output, it should be modifiable.

Section 12.5: BARYCENTRE

Returns the barycentre of the area around the highest peak in the histogram.

The procedure works by sliding a window of width NBIN over the histogram to locate a maximum (if several peaks have the same maximum, then the first peak is taken). Then, the weighted mean of the entries within the window is computed and returned.

If the calculation fails (no maximum), then the global variable OK will be set to False, otherwise to True.

Format:

CALL BARYCENTRE(histogram, barycentre [, nbin])

12.5.1: histogram

The Histogram of which the barycentre is to be computed.

Histograms are normally linked to global variables, they can be created via BOOK_HISTOGRAM, read from a file with GET_HISTOGRAM, by operations between other existing histograms, or obtained from some commands with a KEEP-HISTOGRAM option.

[No default]

12.5.2: barycentre

On successful completion of the procedure, this variable, a Number, is set to the barycentre of the histogram.

This argument must be a modifiable global variable, not an expression, a constant etc. If the variable exists prior to the procedure call, then the associated value will be lost.

12.5.3: nbin

An optional argument of type Number that specifies the window width used both for searching the peak and for computing the barycentre.

[Default is 3]

Section 12.6: BOOK_HISTOGRAM

This procedure is the principal means of creating a new Histogram.

Histograms can be filled with FILL_HISTOGRAM, plotted with PLOT_HISTOGRAM, fitted with a variety of functions (e.g. FIT_POLYA) and written to a file with WRITE_HISTOGRAM. One can also apply arithmetic to them.

Garfield histograms can either be created with a user determined range, or can be declared with the AUTOSCALE option. In the latter case, the first few entries are used to set a range.

Only the histogram reference argument is mandatory, all other arguments are optional.

Format:

CALL BOOK_HISTOGRAM(reference, [number of bins, ...
     [minimum, maximum]] [, options]])

Example:

Call book_histogram(ref,10,2,3)
Call book_histogram(ref,10,`integer`)

The first example books an histogram of 10 bins for the range [2,3]. The second example books an histogram with 10 bins each spanning an integer range with an automatically chosen scale.

See also FILL_HISTOGRAM.

12.6.1: reference

The histogram that is created is assigned to a global variable. The global variable should be seen as the histogram itself.

This parameter should have the format of a variable (e.g. A, REF, B_1) not of a number or a string. This parameter can either be a new, unused, variable or one that is already in use. In the latter case, the object related to the global variable will be deleted.

This parameter is used in calls to e.g. FILL_HISTOGRAM, and can also be used to perform arithmetic, e.g. one can add two histograms via a simple + operation between the references of the two histograms.

12.6.2: bins

Number of bins in the histogram.

[Default: 100]

12.6.3: range

The range of the histogram can be set explicitly with the minimum and maximum arguments. If the range arguments are omitted, then the AUTOSCALE option is implied.

If the range is specified, but autoscaling is requested, then the specified range is ignored.

12.6.4: options

A character String that can contain the following options:

Option Meaning
AUTOSCALE Requests automatic scaling, ignoring min and max
INTEGER Entries will be integers
MANUAL Manual scaling, minimum and maximum respected
REAL Entries will be reals or integers

12.6.4.1: AUTOSCALE

Requests automatic computation of the histogram range.

When this option is in effect, a rough range is set to

     [mean - 3*RMS, mean + 3*RMS]

where the mean and the RMS are computed from the first n_bin/2 entries, with n_bin is the number of bins.

The range is then enlarged a bit by rounding the limits to 1, 2 or 5 times a power of 10. If in addition the INTEGER option has been set, then the range limits are rounded to integer numbers.

An histogram can not be used in arithmetic operations as long as the range has not been set.

The options MANUAL and AUTOSCALE are mutually exclusive.

[Default: The automatic range option is off by default but is implied if minimum and maximum are not specified.]

12.6.4.2: INTEGER

Requests the bin width of the histogram to be an integer value. The smallest possible bin size is therefore 1. The bins will be aligned such that integer numbers fall in the middle of the bins.

The INTEGER/REAL setting only has effect when the range is established automatically.

[Default is REAL]

12.6.4.3: MANUAL

Requests the histogram range as specified in the argument list be respected, i.e. the range is not automatically computed and the specified range is not rounded.

When MANUAL is in effect, the histogram can be used in arithmetic expressions from the moment it has been booked.

The options MANUAL and AUTOSCALE are mutually exclusive.

[This is default if a range is specified.]

12.6.4.4: REAL

Allows the bin width to be a non-integer number. The automatic scaling algorithm rounds the range limits to multiples 1, 2 or 5 times a power of 10.

The INTEGER/REAL setting only has effect when the range is established automatically.

[This is default.]

Section 12.7: BOOK_MATRIX

Creates a Matrix of specified dimensions, and associates it with a Global variable.

If the global variable is already in use, anything attached to it at the moment BOOK_MATRIX is called will be deleted. In particular, if the global variable is already a matrix, then the matrix is first deleted before a newly created matrix is associated with the global variable.

Format:

CALL BOOK_MATRIX(global, size_1, size_2, ...)

Example:

Call book_matrix(cube,3,3,3)

Books a 3x3x3 matrix which can be accessed via the global variable CUBE.

Section 12.8: CARTESIAN_TO_INTERNAL

Applies the conformal mapping of Cartesian (x,y) coordinates to internal (rho,phi) coordinates. The (rho,phi) coordinates are used internally in the program when the cell is described in polar coordinates. The internal coordinates are defined by:

     rho = 0.5*log(x**2+y**2)     [dimension not defined]
     phi = arctan(y/x)            [phi in radians]

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name CTR is also accepted.

Format:

CALL CARTESIAN_TO_INTERNAL(x,y,rho,phi)

Section 12.9: CARTESIAN_TO_POLAR

Converts Cartesian (x,y) coordinates to polar (r,phi) coordinates. The angle phi is in degrees.

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name CTP is also accepted.

Format:

CALL CARTESIAN_TO_POLAR(x,y,r,phi)

Section 12.10: CONVOLUTE

Computes the convolution of 2 histograms (ref1 and ref2) and stores the result (ref3) in a new histogram. The 2 input histograms must have the same bin width.

The range of the output histogram is chosen as the combined range of the two input histograms. The bin width of the output histogram is the same as the bin width of the input histograms.

If the calculation fails (different bin widths, not enough memory), then the global variable OK will be set to False, otherwise to True.

Format:

CALL CONVOLUTE(ref1, ref2, ref3)

Section 12.11: CUT_HISTOGRAM

Returns the part of an histogram for which the abscissa are located in the range [xmin,xmax].

This procedure does not change the bin width - use the REBIN_HISTOGRAM for that purpose.

This procedure may be called while filling is in progress, but should not be called for AUTOSCALE histograms before the range has been established.

If the calculation fails (sub-range doesn't overlap with the histogram, input histogram doesn't exist etc), then the global variable OK will be set to False, otherwise to True.

Format:

CALL CUT_HISTOGRAM(ref_in, xmin, xmax, ref_out)

Example:

Call book_histogram(gauss,500,-50,50)
For i From 1 To 500 Do
   Call fill_histogram(gauss,rnd_gauss)
Enddo
Call plot_histogram(gauss)
Call plot_end

Call cut_histogram(gauss,-5,5,new) Call hplot(new) Call plot_end

Gaussian random numbers are entered in an histogram which is much wider than the spread of the entries. Using the CUT_HISTOGRAM procedure, the central part of the histogram is isolated.

12.11.1: ref_in

The Histogram of which you wish to cut a part.

This histogram is not modified by the procedure.

[No default, this is a mandatory argument.]

12.11.2: xmin

The first bin of the output histogram will be the bin of the input histogram that contains the coordinate xmin.

If xmin is located outside the range of the histogram, then the first bins of the output and input histograms coincide.

This argument should be of type Number.

[No default, this is a mandatory argument]

12.11.3: xmax

The last bin of the output histogram will be the bin of the input histogram that contains the coordinate xmax.

If xmax is located outside the range of the histogram, then the last bins of the output and input histograms coincide.

This argument should be of type Number.

[No default, this is a mandatory argument]

12.11.4: ref_out

On successful completion, this argument is set equal to an Histogram which contains the data of the requested range.

The value that ref_out has when the procedure is called, is lost after the procedure call.

This argument must be modifiable, i.e. this must be a simple variable name, not an expression.

Section 12.12: DELETE_HISTOGRAM

Deletes a histogram. The memory associated with the histogram is only released at the next histogram garbage collect, usually only carried out when there are no free histogram slots left.

If the histogram was known via a global variable, as is usually the case, then the global variable will still exist after this call. However, the type of such a global variable changes to Undefined.

Format:

CALL DELETE_HISTOGRAM(reference)

12.12.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM.

Section 12.13: DELETE_MATRIX

The DELETE_MATRIX procedure frees the memory occupied by matrices and returns the associated global variables to type Undefined.

If a DELETE_MATRIX call is issued without arguments, then all existing matrices are deleted, whether associated with a global variable or not, whether in use as a constant of an active instruction or not. The use of this procedure in a loop is therefore not recommended.

Format:

CALL DELETE_MATRIX(matrix_1, matrix_2, ...)

Example:

Call book_matrix(a,2,3,4,5)
Call delete_matrix(a)

Section 12.14: DERIVATIVE

Computes an approximation of the derivative y'(x) at x_int where x and y are given as matrices and where x_int is a number.

The calculation is using an interpolation between y and x of an order that can be specified with the OPTION argument, and which is by default 2.

Format:

CALL DERIVATIVE(x, y, x_int, dy [, option])

Example:

Read-vector x
-3,-2.3,-1,0,1,2,5,7,8,12

Global y=x**2 Say "Please enter a value" Parse terminal xint Call derivative(x,y,xint,dy) Say "Derivative: {dy} should be {2*xint}."

This example verifies that the derivative is approximately correct. If y had been set to x**3, the derivative would be inaccurate unless one adds the option `cubic`.

12.14.1: x

A 1-dimensional array of ordinates.

This array must be strictly in increasing order. This array must have the same length as y.

12.14.2: y

A 1-dimensional array of function values.

This array must have the same length as x.

12.14.3: x_int

A number, the value of x at which y'(x) is to be computed.

12.14.4: dy

On return, a number approximately equal to y'(x)

12.14.5: option

A character string that can contain the following keywords:

Keyword Meaning Notes
LINEAR Linear interpolation Rarely useful
PARABOLIC Quadratic interpolation Default
CUBIC Cubic interpolation Risk of oscilation

Section 12.15: DIMENSIONS

Returns the number of dimensions (n_dimensions) of the matrix and a vector with the size of the matrix in each of the dimensions.

Format:

CALL DIMENSIONS(matrix, n_dimensions, dimension_vector)

Example:

Call get_matrix(abc,`abc.mat`)
Call dimensions(abc,n_dim,dim_abc)
Global nx=number(dim_abc[1])
Global ny=number(dim_abc[2])
Say "Matrix abc has {n_dim} dimensions, shape is {nx}x{ny}x..."
Call delete_matrix(dim_abc)

A matrix is read from a file, and the example shows how one can find out what the dimensions of the object are. The NUMBER function is used to convert the 1-matrices dim_abc[1] and dim_abc[2] into numbers - this is purely esthetic since Say would place parentheses around the values of nx and ny.

Section 12.16: DRIFT_ELECTRON

Calculates a electron drift line from the point (x, y, 0) and returns the drift time, the status (hit a wire, left the area etc) and optionally also the integrated diffusion, the multiplication and the losses through attachment.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

The integrated diffusion, the multiplication and the attachment losses can only be computed if resp. longitudinal diffusion, Townsend and attachment data have been supplied in the &GAS section. The integrated diffusion takes the transverse diffusion into account if both transverse and longitudinal diffusion coefficients have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_ELECTRON(x, y, status, time [,diffusion ...
     [, multiplication [,attachment]]])

12.16.1: coordinates

The starting point of the drift line should be specified in internal coordinates.

Internal coordinates coincide with the user coordinates when a Cartesian reference system is used. If polar coordinates are used, then the POLAR_TO_INTERNAL procedure should be used for the conversion.

The coordinates should be specified as constants, variables or expressions that are or evaluate to Numbers.

12.16.2: status

See status.

12.16.3: time

Contains, on successful completion, the total drift time.

The time is expressed in microsec.

This parameter should be a global variable, not a constant nor an expression. The global may exist prior to the call, but doesn't have to. If the global exists, the value it has before the call will be lost.

12.16.4: diffusion

Contains, on successful completion, the integrated diffusion.

The diffusion is integrated over the trajectory using a method described under diffusion.

The diffusion is expressed in microsec.

This parameter should be a global variable, not a constant nor an expression. The global may exist prior to the call, but doesn't have to. If the global exists, the value it has before the call will be lost.

12.16.5: multiplication

Contains, on successful completion, the exponentiated integral of the Townsend coefficient over the drift path.

The integration technique of the Townsend coefficient is described under multiplication.

The multiplication is a dimensionless number.

This parameter should be a global variable, not a constant nor an expression. The global may exist prior to the call, but doesn't have to. If the global exists, the value it has before the call will be lost.

12.16.6: attachment

Contains, on successful completion, the exponentiated integral of the attachment coefficient over the drift path.

The integration technique of the attachment coefficient is described under attachment.

The attachment is a dimensionless number.

This parameter should be a global variable, not a constant nor an expression. The global may exist prior to the call, but doesn't have to. If the global exists, the value it has before the call will be lost.

Section 12.17: DRIFT_ELECTRON_3

Calculates a electron drift line from the point (x, y, z) and returns the drift time, the status (hit a wire, left the area etc) and optionally also the integrated diffusion, the multiplication and the losses through attachment.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

The integrated diffusion, the multiplication and the attachment losses can only be computed if resp. longitudinal diffusion, Townsend and attachment data have been supplied in the &GAS section. The integrated diffusion takes the transverse diffusion into account if both transverse and longitudinal diffusion coefficients have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_ELECTRON_3(x, y, z, status, time [,diffusion ...
     [, multiplication [,attachment]]])

12.17.1: coordinates

See coordinates.

12.17.2: status

See status.

12.17.3: time

See time.

12.17.4: diffusion

See diffusion.

12.17.5: multiplication

See multiplication.

12.17.6: attachment

See attachment.

Section 12.18: DRIFT_ION

Calculates a drift line for a positively charged ion from the point (x, y) and returns the drift time and the status (hit a wire, left the area etc).

The integrated diffusion, the multiplication and the attachment losses are not computed.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_ION(x, y, status, time)

12.18.1: coordinates

See coordinates.

12.18.2: status

See status.

12.18.3: time

See time.

Section 12.19: DRIFT_ION_3

Calculates a drift line for a positively charged ion from the point (x, y, z) and returns the drift time and the status (hit a wire, left the area etc).

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

The integrated diffusion, the multiplication and the attachment losses are not computed.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_ION_3(x, y, z, status, time)

12.19.1: coordinates

See coordinates.

12.19.2: status

See status.

12.19.3: time

See time.

Section 12.20: DRIFT_MC_ELECTRON

Performs a Monte-Carlo calculation of an electron drift line, taking diffusion into account on a step-by-step basis. The drift line starts from the point (x,y,z). The procedure returns the drift time, the status (hit a wire, left the area etc) and optionally also the multiplication and the losses through attachment.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure can only meaningfully be used if both the transverse and the longitudinal diffusion have been supplied in the &GAS section. The multiplication and the attachment losses can only be computed if Townsend and attachment data have been entered.

The Monte Carlo integration method is described in the drift section under Monte_Carlo.

Format:

CALL DRIFT_MC_ELECTRON(x, y, z, status, time ...
     [, multiplication [,attachment]])

12.20.1: coordinates

See coordinates.

12.20.2: status

See status.

12.20.3: time

See time.

12.20.4: multiplication

See multiplication.

12.20.5: attachment

See attachment.

Section 12.21: DRIFT_MC_ION

Performs a Monte-Carlo calculation of a drift line for a positively charged ion, taking diffusion into account on a step-by-step basis. The drift line starts from the point (x,y,z). The procedure returns the drift time and the status (hit a wire, left the area etc).

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

It should be noted that MC drift of electrons and ions uses the same set of integration parameters (step size in particular). Care should be taken to set these parameters to reasonable values for ions before this procedure is called.

Diffusion coefficients for ions can be set with the PARAMETERS statement in the gas section (see sigma).

Multiplication and attachment losses are not evaluated.

The Monte Carlo integration method is described in the drift section under Monte_Carlo.

Format:

CALL DRIFT_MC_ION(x, y, z, status, time)

12.21.1: coordinates

See coordinates.

12.21.2: status

See status.

12.21.3: time

See time.

Section 12.22: DRIFT_MC_NEGATIVE_ION

Performs a Monte-Carlo calculation of a drift line for a negatively charged ion, taking diffusion into account on a step-by-step basis. The drift line starts from the point (x,y,z). The procedure returns the drift time and the status (hit a wire, left the area etc).

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

It should be noted that MC drift of electrons and ions uses the same set of integration parameters (step size in particular). Care should be taken to set these parameters to reasonable values for ions before this procedure is called.

Diffusion coefficients for ions can be set with the PARAMETERS statement in the gas section (see sigma).

Multiplication and attachment losses are not evaluated.

The Monte Carlo integration method is described in the drift section under Monte_Carlo.

Format:

CALL DRIFT_MC_NEGATIVE_ION(x, y, z, status, time)

12.22.1: coordinates

See coordinates.

12.22.2: status

See status.

12.22.3: time

See time.

Section 12.23: DRIFT_MC_POSITRON

Performs a Monte-Carlo calculation of an positron drift line, taking diffusion into account on a step-by-step basis. The drift line starts from the point (x,y,z). The procedure returns the drift time and the status (hit a wire, left the area etc). Identical drift properties for positrons and electrons are assumed, apart from the charge.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure can only meaningfully be used if both the transverse and the longitudinal diffusion have been supplied in the &GAS section.

The Monte Carlo integration method is described in the drift section under Monte_Carlo.

Format:

CALL DRIFT_MC_POSITRON(x, y, z, status)

12.23.1: coordinates

See coordinates.

12.23.2: status

See status.

12.23.3: time

See time.

Section 12.24: DRIFT_POSITRON

Calculates a positron drift line from the point (x, y, 0) and returns the drift time and the status (hit a wire, left the area etc). This procedure assumes identical drift properties for electrons to those for positrons, apart from the charge.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_POSITRON(x, y, status, time)

12.24.1: coordinates

See coordinates.

12.24.2: status

See status.

12.24.3: time

See time.

Section 12.25: DRIFT_POSITRON_3

Calculates a positron drift line from the point (x, y, z) and returns the drift time and the status (hit a wire, left the area etc). This procedure assumes identical drift properties for electrons to those for positrons, apart from the charge.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_POSITRON(x, y, z, status, time)

12.25.1: coordinates

See coordinates.

12.25.2: status

See status.

12.25.3: time

See time.

Section 12.26: DRIFT_NEGATIVE_ION

Calculates a drift line for a negatively charged ion from the point (x, y) and returns the drift time and the status (hit a wire, left the area etc).

The integrated diffusion, the multiplication and the losses through attachment are not computed.

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_NEGATIVE_ION(x, y, status, time)

12.26.1: coordinates

See coordinates.

12.26.2: status

See status.

12.26.3: time

See time.

Section 12.27: DRIFT_NEGATIVE_ION_3

Calculates a drift line for a negatively charged from the point (x, y, z) and returns the drift time and the status (hit a wire, left the area etc).

This procedure should be called only from within the drift or signal sections, after the cell and the gas have been entered.

The integrated diffusion, the multiplication and the losses through attachment are not computed.

This procedure uses the Runge_Kutta_Fehlberg integration method.

Format:

CALL DRIFT_NEGATIVE_ION_3(x, y, z, status, time)

12.27.1: coordinates

See coordinates.

12.27.2: status

See status.

12.27.3: time

See time.

Section 12.28: DRIFT_INFORMATION

Returns the various pieces of information about the current drift line, such as the number of steps and the numeric status code.

This procedure can be called after any of the drift line computation procedures has been called (e.g. DRIFT_ELECTRON).

Format:

CALL DRIFT_INFORMATION(               ...
     [ `CHARGE`, q ] ,              ...
     [ `DRIFT-TIME`, time ] ,       ...
     [ `ELECTRODE`, electrode ] ,   ...
     [ `PARTICLE`, particle ] ,     ...
     [ `PATH-LENGTH`, path ] ,      ...
     [ `STATUS-CODE`, istat ] ,     ...
     [ `STATUS-STRING`, status ] ,  ...
     [ `STEPS`, nsteps ] ,          ...
     [ `X-START`, coord ] ,         ...
     [ `Y-START`, coord ] ,         ...
     [ `Z-START`, coord ] ,         ...
     [ `X-END`, coord ] ,           ...
     [ `Y-END`, coord ] ,           ...
     [ `Z-END`, coord ])

Example:

Call plot_drift_area
Call drift_electron_3(2.5,3.5,4.5,status,time)
Call plot_drift_line
Call plot_end
Say "Status: {status}"
Call string_index(status,`wire`,index1)
Call string_index(status,`replica`,index2)
If 'index1>0 & index2=0' Then
   Call drift_information('status-code',wire)
   Say "The particle hit wire {wire}."
Endif

An electron drift line is computed using the Runge Kutta method with DRIFT_ELECTRON_3 which returns a formatted status string. This string has, if the electron hits a wire, the format "Hit X wire n" or "Hit a replica of X wire n". With the help of the STRING_INDEX procedure, we search for the strings "wire" and "replica" to determine whether an original copy of a wire has been hit. If so, DRIFT_INFORMATION is called to find the number of the wire that has been hit.

12.28.1: q

Contains, on return, the charge of the last particle that has been drifted.

12.28.2: time

Contains, on return, the total drift time in microsec of the last drift line that has been computed.

12.28.3: electrode

The read-out group number of the electrode that was hit by the last drift line.

Read-out group numbers are assigned by the SELECT statement.

12.28.4: particle

Contains, on return, one of the following strings:

particle Meaning
electron An electron or a positron has been drifted
ion An ion with charge +1 or -1 has been drifted
vacuum An electron has been drifted in vacuum

12.28.5: path

Contains on return the length of the current drift line, estimated as the sum of the linear distances between the successive steps of the drift line.

The path is expressed in cm.

12.28.6: istat

This argument contains on return the numeric status code for the last drift line.

The numeric status code is explained in the introduction of the drift section, under the status header.

12.28.7: status

This argument contains on return a string with the status of the last drift line.

The status strings are explained in the introduction of the drift section, under the status header.

12.28.8: nsteps

Contains on return the number of steps in the last drift line that has been computed.

12.28.9: coord

Contains on return a coordinate of the starting or the end point of the current drift line.

The internal coordinate system is used - for Cartesian cells, this system coincides with the user coordinates, for polar cells, the INTERNAL_TO_POLAR procedure can be used to convert the coordinates.

Section 12.29: DRIFT_VELOCITY

Returns the drift velocity, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the drift velocity is returned in cm/microsec.

Format:

CALL DRIFT_VELOCITY(ex, ey, ez, drift)

Example:

&GAS
magboltz argon 92 co2 8 e/p-range 0.05 8

&MAIN Global emin=60 Global emax=7000 Global n=200 Global e=emin*(emax/emin)**((row(n)-1)/(n-1)) Call drift_velocity(0,0,e,v) !opt log-x Call plot_graph(e,v,`E [V/cm]`,`Drift velocity [cm/microsec]`, ... `Magboltz vs Zhao et al.`) Read-vector ezhao 0.07 0.14 0.21 0.28 0.35 0.42 0.49 0.559 0.629 0.699 0.769 0.839 0.909 0.979 1.049 1.119 1.189 1.259 1.329 1.399 1.573 1.748 1.923 2.098 2.448 2.797 3.147 3.497 3.846 4.196 4.545 4.895 5.245 5.735

Read-vector vzhao 0.52 1.15 1.89 2.77 3.56 4.18 4.57 4.78 4.82 4.79 4.71 4.62 4.53 4.43 4.35 4.3 4.26 4.23 4.2 4.2 4.2 4.24 4.29 4.36 4.49 4.57 4.59 4.58 4.56 4.5 4.47 4.44 4.4 4.4

Call plot_error_bar(ezhao*1000,vzhao,`circle`) Call plot_end

Magboltz is used to compute the drift velocity in a mixture of 92 % Argon and 8 % CO2. The results are compared with the measurements of T. Zhao et al., NIM A340 (1994) 485. The E > 3000 V/cm region is controversial, apart from that the two are in good agreement. This is an abridged version of http://consult.cern.ch/writeup/garfield/examples/gas/ArCO2_detail.html

Section 12.30: ELECTRIC_FIELD

Returns the electric field vector and the potential at a given point.

The arguments ex, ey, ez, e, v and status are optional.

Format:

CALL ELECTRIC_FIELD(x, y, ex, ey, ez, e, v, status)

Example:

&CELL
plane x=-1
plane y=-1
rows
s * * 1 1 1000

&FIELD Global n=6 Call book_matrix(x,n,n) Call book_matrix(y,n,n) For i From 1 To n Do For j From 1 To n Do Global x[i;j]=(i-1)/(n-1) Global y[i;j]=(j-1)/(n-1) Enddo Enddo Call efield(x,y,ex,ey,ez,e,v,stat) Call print_matrix(x,y,ex,ey,ez,e,v,stat) area 0 0 1 1 grid {n} print ex ey e v

In a simple chamber, one uses on the one hand the ELECTRIC_FIELD procedure to compute the field on a 6x6 grid, on the other hand the PRINT command is used to verify the result.

12.30.1: coordinates

This procedure accepts input arguments of types Number and Matrix.

If at least one of the input arguments x and y is of type Matrix, then all output arguments are of type Matrix, with the dimensions of the first input argument of type Matrix. If one input argument is of type Number and the other of type Matrix, then the Number type argument is "expanded" to become a Matrix filled uniformly with the value of the Number.

The coordinates system expected by ELECTRIC_FIELD is the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If polar coordinates are used however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians

These mappings can be performed with the POLAR_TO_INTERNAL procedure.

12.30.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Er = Ex/r
Ephi = Ey/r
Ez is invariant

12.30.3: status

Indicates where the point is located, if only scalar arguments are used as coordinates, then the status is returned in the form of a string. If at least one coordinate is a Matrix, then a matrix filled with numeric location codes is returned.

Status Location Code
In a material Inside the mesh, but not in a drift medium -5
In an X wire Inside a wire of type X > 0
Normal In the active part of the cell 0
Outside mesh Not in any mesh triangle or tetrahedron -6
Outside plane On the side of a plane where no wires are -4 to -1
Unknown potential Unknown potential type (shouldn't occur) -10
Unknown Other cases (shouldn't occur) other

Section 12.31: ELECTRIC_FIELD_3

Returns the electric field vector and the potential at a given point. This routine is to be used in case the field has structure along the z-axis, for instance because of the presence of space charge.

The arguments ex, ey, ez, e, v and status are optional.

Format:

CALL ELECTRIC_FIELD_3(x, y, z, ex, ey, ez, e, v, status)

Example:

See ELECTRIC_FIELD.

12.31.1: coordinates

This procedure accepts input arguments of types Number and Matrix.

If at least one of the input arguments x, y, z is of type Matrix, then all output arguments are of type Matrix, with the dimensions of the first input argument of type Matrix. If one or more input arguments are of type Number and one or more others of type Matrix, then the Number type arguments are "expanded" to become Matrices filled uniformly with the value of the Numbers.

The coordinates system expected by ELECTRIC_FIELD_3 is the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If polar coordinates are used however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: z

The z-coordinate is not affected by any of the conformal mappings currently in use by the program.

These mappings can be performed with the POLAR_TO_INTERNAL procedure.

12.31.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Er = Ex/r
Ephi = Ey/r
Ez is invariant

12.31.3: status

See status.

Section 12.32: ELECTRON_VELOCITY

Returns the electron velocity vector at a point.

This procedure needs electron drift velocity data, which can be computed with the MAGBOLTZ gas section command. The magnetic field, if present, is taken into account. Diffusion data is not used, even if present - the vector that is returned represents the mean electron drift velocity at a given point.

This procedure provides functionality similar to the SPEED command.

Format:

CALL ELECTRON_VELOCITY(x, y, z, vx, vy, vz [, status])

Example:

Call electron_velocity(2,3,0,vx,vy,vz,status)
Say "Velocity: ({vx,vy,vz}), Status: {status}"

12.32.1: coordinates

This procedure accepts coordinates of type Number only.

The coordinates are expected to refer to the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If polar coordinates are used however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: z

The z-coordinate is not affected by any of the conformal mappings currently in use by the program.

These mappings can be performed with the POLAR_TO_INTERNAL procedure.

12.32.2: velocity

The velocity is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

vr = vx/r
vphi = vy/r
vz is invariant

12.32.3: status

See status.

Section 12.33: EXTRACT_SUBMATRIX

Extracts a submatrix from a (larger) matrix.

The matrix from which elements are to be extracted should exist prior to the call, the receiving matrix should not exist prior to the call.

This procedure is used to process array indexing on the right hand side of formulae, in procedure calls etc. This procedure is not meant to called by the user. It is much simpler to get sub-matrices using indexing expressions.

Format:

CALL EXTRACT_SUBMATRIX(ndim, nsel_1, nsel_2, ... , ...
     isel_1_1, isel_1_2, ..., isel_2_1, isel_2_2, ... , ...
     isel_n_1, isel_n_2, ref_submatrix, ref_matrix)

Section 12.34: EXTREMUM

Searches for an extreme value of a function varying 1 parameter over a given range. Whether a minimum or a maximum will be searched for depends on the setting of the options.

When the search is successful, the global variable OK is set to True, otherwise to False. The following conditions can lead to un unsuccssful search:

This procedure works by parabolic iteration over a set of 3 near-extreme values, which is initialised with a random search. If the boundary values are better, than the result of the random search, then the parabolic search is skipped.

Format:

CALL EXTREMUM(function, variable, minimum, maximum, ...
     [ options [, eps_loc [, eps_fun [, itermax ]]]])

Examples:

Call extremum(`1+5*x-(x-2)**3`,x,-1,4,`plot,print,minimum`)
Global min=x
Call extremum(`1+5*x-(x-2)**3`,x,-1,4,`plot,print,maximum`)
Global max=x
Say "Extrema: {min,max}"

The function 1+5*x-(x-2)**3 has a local minimum near x=0.7 and a local maximum near x=3.3. The first call will indeed find the local minimum, while the second call will set x to -1 since the function value on this boundary is higher than in the local maximum.

Global a=2
Global b=3
Call extremum(`1+cosh(a-b)`,b,-1,4,`plot,print,minimum`)
Say "Minimum found is {b}, should be {a}."

This example shows a function of two global variables, A and B. The function is minimised as function of B in this example. During the minimisation, A retains its value.

12.34.1: function

The function may depend on all of the currently defined Global variables, it must depend on the variable as function of which the extremum is to be searched. The function should return a single variable of type Number.

This argument is mandatory and should be of the type String.

12.34.2: variable

One of the current Global variables. The name can be chosen freely.

The variable doesn't have to have a value before the procedure is called. Any value associated with it before the procedure is called will be lost, if the search is successful.

On successful completion, the value of the variable is set to the abscissa of the extremum and it will then have the type Number.

The variable is not modified if the search fails.

This argument should be a global variable, not an expression nor a constant.

12.34.3: minimum

The lower end of the parameter range to be searched for an extremum.

This argument is mandatory and must be of the type Number.

12.34.4: maximum

The upper end of the parameter range to be searched for an extremum.

This argument is mandatory and must be of the type Number.

12.34.5: options

A String that can contain zero or more of the following options, separated by commas or blanks:

Option Effect Notes
MAXIMUM Searches for a maximum Not default
MINIMUM Searches for a minimum Default
NOPLOT No plot of the function Default
NOPRINT No printout Default
PLOT Makes a plot of the function Not default
PRINT Prints a progress report Not default

12.34.6: eps_loc

Specifies the location convergence criterion.

The search is declared to have converged when, between 2 iterations, the location of the extremum changes relatively by less than a fraction eps_loc or absolutely by less than an amount eps_loc.

This is an optional parameter of type Number.

Since the function is evaluated in single precision arithmetic, values less than 1e-6 are not meaningful on most computers.

[By default 1e-4.]

12.34.7: eps_fun

Specifies the function value convergence criterion.

The search is declared to have converged when, between 2 iterations, the extreme function value changes relatively by less than a fraction eps_fun or absolutely by less than an amount eps_fun.

This is an optional parameter of type Number.

Since the function is evaluated in single precision arithmetic, values less than 1e-6 are not meaningful on most computers.

[By default 1e-4.]

12.34.8: itermax

Maximum number of parabolic search loops.

The search is abandoned if it has not converged on the basis of eps_loc or eps_fun within the specified number of iterations,

This is an optional parameter of type Number.

[By default 20.]

Section 12.35: FILL_HISTOGRAM

This procedure adds an entry to an existing histogram.

Format:

CALL FILL_HISTOGRAM(reference, entry [, weight])

Example:

Call book_histogram(ref,100)
For i From 1 To 10000 Do
   Call fill_histogram(ref,rnd_landau)
Enddo
Call plot_histogram(ref,`Energy loss`,`Landau distribution`)
Call plot_end

This example could be used to check that the Landau random number generator does indeed work.

12.35.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM.

You may also read a histogram from a file with GET_HISTOGRAM and continue filling it.

This argument should not be an expression.

12.35.2: entry

One value for the quantity that you wish to histogram.

12.35.3: weight

The weight to be assigned to "entry". The "weight" parameter is optional and defaults to 1.

Section 12.36: FIT_EXPONENTIAL

Fits an exponential of a polynomial to an histogram or to 1-dimensional matrices.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format for histograms:

CALL FIT_EXPONENTIAL(reference, a0, a1, a2, ..., an, ...
     err_a0, err_a1, err_a2, ..., err_an [, options])

Format for matrices:

CALL FIT_EXPONENTIAL(x, y, err_y, a0, a1, a2, ..., an, ...
     err_a0, err_a1, err_a2, ..., err_an [, options])

Example:

&SIGNAL
aval polya-town 0.5
check avalanche from 0 0.5 range 0.1 10000 keep-histograms
Call fit_exponential(avalanche,a0,a1,ea0,ea1,`print,plot`)
Say "a0 = {a0}+/-{ea0}, a1 = {a1}+/-{ea1}."

In this example, the user wishes to see how well a Polya distribution with parameter theta=0.5, can be reproduced by an exponential.

12.36.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or GET_HISTOGRAM. This argument may also be an expression that results in a histogram.

The argument is not modified on return.

12.36.2: x

A 1-dimensional array that contains the ordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

Not changed on exit.

12.36.3: y

A 1-dimensional array that contains the coordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

In the initial estimate, the data points where y <= 0 are skipped. If there are many such points which should be taken into account for the fit, then convergence is not guaranteed.

Not changed on exit.

12.36.4: err_y

A 1-dimensional array that contains the errors on the coordinates of the points to be fitted.

This argument can also be a scalar, which is then used as error for all points. If this argument is a vector, then it must have the same length as x and y.

Not changed on exit.

12.36.5: a

The function that is fitted to the data points is given by

function = exp(polynomial)

where

polynomial = a0 + a1*x + a2*x**2 + a3*x**2 + ... + an*x**n

The arguments a0, a1 etc are the terms in this expansion.

The input values for the terms are not used in the fitting procedure. Initial values are obtained from an unweighted maximum likelihood fit neglecting the data points where y=0.

This argument must be modifiable, i.e. it can not be a constant nor an expression.

12.36.6: err_a

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

These arguments must be modifiable, that is, they can neither be constants nor expressions.

12.36.7: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
EQUAL Assume equal weight of all points Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Default
PRINT Print details during the fit Not default

Notes:

  1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitely provided in that case.
  2. The plot is always made on a linear-logaritmic scale.

Section 12.37: FIT_FUNCTION

Fits an arbitrary function to an histogram or to 1-dimensional matrices. Fitting a Landau distribution to an histogram, seems to be a common application of this procedure.

This procedure, unlike the other fitting procedures, does not try to find suitable starting values for the fitting parameters. A starting value for each parameter must therefore be supplied by the user.

Since this procedure uses the symbolic evaluation procedures of Garfield, the fit works essentially in single precision. In order to have a chance to be successful, the problem must therefore be well conditioned.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format for histograms:

CALL FIT_FUNCTION(reference, function, ...
     par1, par2, par3, ... , err1, err2, err3, ... [, options])

Format for matrices:

CALL FIT_FUNCTION(x, y, err_y, function, ...
     par1, par2, par3, ... , err1, err2, err3, ... [, options])

Example:

Call book_histogram(ref,50,-1,3)
For i From 1 To 500 Do
   Global x=-1+4*rnd_uniform
   Global w=x**2+1
   Call fill_histogram(ref,x,w)
Enddo
Global c=100
Global a=2
Global b=1
Call fit_function(ref,`c+a*(1+b*x**2)`,a,b,ea,eb,`plot,print`)
Say "Function: {c}+{a}*(1+{b}*x**2), errors {ea,eb}"
Say "{a+c} +/- {abs(ea)} should be equal to"
Say "{a*b} +/- {a*b*sqrt((ea/a)**2+(eb/b)**2)}"

(This is a simple test of the FIT_FUNCTION procedure in which the function depends on 3 global variables A, B and C of which A and B are varied while C is kept fixed.)

12.37.1: function

The function that should be fitted is entered as a character string. The function depends on the current set of global variables, and has X as ordinate variable. The function should only depend on global variables that are of type Number.

The global variables that are to be varied are those that appear in the argument list of the procedure call. The other globals are not changed.

12.37.2: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or to GET_HISTOGRAM. This argument may also be an expression that results in a histogram.

The argument is not modified on return.

12.37.3: x

A 1-dimensional array that contains the ordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

Not changed on exit.

12.37.4: y

A 1-dimensional array that contains the coordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

In the initial estimate, the data points where y <= 0 are skipped. If there are many such points which should be taken into account for the fit, then convergence is not guaranteed.

Not changed on exit.

12.37.5: err_y

A 1-dimensional array that contains the errors on the coordinates of the points to be fitted.

This argument can also be a scalar, which is then used as error for all points. If this argument is a vector, then it must have the same length as x and y.

Not changed on exit.

12.37.6: parameters

The global variables for which optimum values are to be determined have to appear in the argument list of the procedure call.

These parameters must be given a suitable initial value of type Number, for instance by using the Global statement.

On return of a successful fit, the global variables are set equal to the optimum value found. The global variables are of type Undefined if the fit fails.

12.37.7: errors

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

These arguments must be modifiable, that is, they can neither be constants nor expressions.

12.37.8: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
EQUAL Assume equal weight of all points Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Default
PRINT Print details during the fit Not default

Note:

  1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitely provided in that case.
  2. The plot is always made on a linear-logaritmic scale.

Section 12.38: FIT_GAUSSIAN

Fits a Gaussian to a set of 1-dimensional matrices or to an histogram.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format for histograms:

CALL FIT_GAUSSIAN(reference, integral, mean, sigma ...
     [, err_int [, err_mean [, err_sigma [, options]]]])

Format for matrices:

CALL FIT_GAUSSIAN(x, y, err_y, integral, mean, sigma ...
     [, err_int [, err_mean [, err_sigma [, options]]]])

Example 1:

Call get_histogram(sel_5,`arrival.hist`,`sel_5`)
Call fit_gaussian(sel_5,dum,dum,sigma,dum,dum,esigma,`PLOT`)
Say "Gaussian width is {sigma} +/- {esigma}."

(The ARRIVAL-TIME-DISTRIBUTION instruction only returns the RMS of the arrival time distributions. To obtain Gaussian fits in addition, you can specify the KEEP-HISTOGRAMS option and then use FIT_GAUSSIAN. You can also do the fit in a separate job as explained in http://consult.cern.ch/writeup/garfield/examples/)

Example 2:

Call book_histogram(hist)
For i From 1 To 10000 Do
   Global sum=0
   For j From 1 To 12 Do
      Global sum=sum+rnd_uniform
   Enddo
   Call fill_histogram(hist,sum)
Enddo
Call fit_gaussian(hist,a,b,c,ea,eb,ec,`print,plot`)

(This verifies the approximation of a Gaussian distribution by the sum of 12 uniformly distributed random numbers.)

12.38.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or to GET_HISTOGRAM. This argument may also be an expression that results in a histogram.

The argument is not modified on return.

12.38.2: x

A 1-dimensional vector that contains the abscissa of the points on which the fit is to be performed.

This vector should have the same size as y.

12.38.3: y

A 1-dimensional vector that contains the function values of the points on which the fit is to be performed.

This vector should have the same size as x.

12.38.4: err_y

Either a scalar which is interpreted as a common error on all function values (y) or a 1-dimensional vector of the same length as x and y and which contains for each point the error in the function value.

12.38.5: integral

The contents of the fitted Gaussian.

There is no need to initialise this argument - the initial value for the fitting procedure is set to the sum of the histogram or Y array.

This argument must be modifiable, i.e. it can not be a constant nor an expression.

12.38.6: mean

The central value of the fitted Gaussian.

There is no need to initialise this argument - the initial value for the fitting procedure is set to the mean of the histogram or arrays.

This argument must be modifiable, i.e. it can not be a constant nor an expression.

12.38.7: sigma

The standard deviation of the fitted Gaussian.

There is no need to initialise this argument - the initial value for the fitting procedure is set to the RMS of the histogram or arrays.

This argument must be modifiable, i.e. it can not be a constant nor an expression.

12.38.8: errors

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

Errors are only returned upon request. The corresponding arguments must be modifiable, that is, they can neither be constants nor expressions.

12.38.9: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
EQUAL Assume equal weight of all points Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Default
PRINT Print details during the fit Not default

Section 12.39: FIT_MATHIESON

Fits a integrated Mathieson distribution to an histogram. This distribution is intended to describe the signal induced in a cathode plane that is segmented into strips.

The Mathieson distribution depends on a shape parameter, called K3, which is a function of the geometrical structure of the chamber, and on the ratio of strip width and anode-cathode distance. The distribution assumes that the avalanche is localised on anode wires placed centrally with respect to the cathode strips.

The procedure derives the strip width from the bin width of the input histogram, the anode-cathode distance has to be entered as an argument. The K3 parameter can be fitted, but may optionally also be kept constant during the fit at a user-specified value.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format:

CALL FIT_MATHIESON(reference, distance, norm, centre, k3, ...
     err_norm, err_centre, err_k3, [, options])

Example:

Call book_histogram(ref_m,50)
Call book_histogram(ref_b,50)
For i From 1 To 65 Do
   Call get_histogram(hist,`profile.hist`,string(i))
   Global k3=0.1
   Global s=0.254
   Call fit_mathieson(hist,s,f,xc,k3,ef,exc,ek3,...
      `noplot,noprint,equal,fitk3`)
   Call fill_histogram(ref_m,xc)
   Call barycentre(hist,b,5)
   Call fill_histogram(ref_b,b)
   Say "Centre:     {xc} +/- {exc}"
   Say "Barycentre: {b}"
   Say "K3:         {k3} +/- {ek3}"
Enddo
Call plot_histogram(ref_m,`Reconstructed x [cm]`,`Mathieson fits`)
Call plot_end
Call plot_histogram(ref_b,`Reconstructed x [cm]`,`Barycentre`)
Call plot_end

(We have already produced a file that contains for 65 events a distribution of induced charges in the pads, and now we fit each of these with a Mathieson distribution and compare these fits with barycentres. The K3 parameter is left free.)

References:

[1]
J.S. Gordon & E. Mathieson, NIM 227 (1984) 267-276
[2]
E. Mathieson & J.S. Gordon, NIM 227 (1984) 277-282
[3]
E. Mathieson, NIM A270 Letter to the Editor (1988) 602-603

12.39.1: distance

The distance between anode and cathode. The anode is assumed to be the place where the avalanches take place. The strip width is derived from the bin width of the input histogram.

This parameter is mandatory, and should be entered in cm.

12.39.2: centre

If the fit is successful, then this parameter contains on return the reconstructed track location in cm. The coordinate system is the same as the horizontal axis of the input histogram.

This parameter should be modifiable and its value prior to the call is not used. Any matrix, histogram or string associated with it before the call is lost.

12.39.3: norm

Contains on return, if the fit is successful, the normalisation of the fitted Mathieson distribution.

This parameter should be modifiable and its value prior to the call is not used. Any matrix, histogram or string associated with it before the call is lost.

12.39.4: k3

If the FITK3 option is specified, then this argument contains on return of a successful fit the K3 parameter that matches best the histogram. If a value is given on entry, then this value will be used as starting point for the fit. Otherwise, an initial value of 0.5 is taken.

The argument must in this case be modifiable. Any matrix, histogram or string associated with it before the call is lost.

If the NOFITK3 option is specified, then this argument must contain on entry your prefered value of K3. The argument is then not modified and the corresponding error is set to 0.

12.39.5: errors

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

These arguments must be modifiable, that is, they can neither be constants nor expressions.

12.39.6: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
EQUAL Assume equal weight of all points Default
FITK3 Fits the K3 parameter Default
NOFITK3 Keep the K3 parameter fixed Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Not default
PRINT Print details during the fit Not default

Section 12.40: FIT_POLYA

Fits a Polya distribution to an histogram or to 1-dimensional matrices. The Polya distribution is a special case of a gamma distribution and is sometimes used, as a semi-empiric formula, to describe avalanche fluctuations around wires.

This procedure optionally tries to determine the a linear horizontal scale correction for which the fit is optimal. But, fitting a Polya distribution with a free scale is a numerically poorly conditioned problem because of the high correlation between the Polya parameter and the scale parameters. If the scale is known, then it is preferable to fix the scale.

Similarly, the routine will make an attempt to estimate the Polya parameter if no starting value is known, but it is better to provide a starting value if one is known with reasonable accuracy.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format for histograms:

CALL FIT_POLYA(reference, factor, offset, slope, theta, ...
     err_factor, err_offset, err_slope, err_theta [, options])

Format for matrices:

CALL FIT_POLYA(x, y, err_y, factor, offset, slope, theta, ...
     err_factor, err_offset, err_slope, err_theta [, options])

Example:

Call book_histogram(ref,100,0,10)
For i From 1 To 2000 Do
   Call fill_histogram(ref,1+2*rnd_polya(1))
Enddo
Global o=-1/2
Global s=1/2
Global t=500
Global f=200
Call fit_polya(ref,f,o,s,t,ef,eo,es,et,`plot,print,poisson,auto`)
Say "Scaling X={o}+{s}*x, theta={t}+/-{et}, contents={f}."

(First we fill a histogram with a Polya distribution of which we know the theta parameter and the scale, then we check whether the fit finds the input values back. We don't need to give initial values in this case since the AUTO option is specified.)

12.40.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or GET_HISTOGRAM. This argument may also be an expression that results in a histogram.

The argument is not modified on return.

12.40.2: x

A 1-dimensional array that contains the ordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

Not changed on exit.

12.40.3: y

A 1-dimensional array that contains the coordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

In the initial estimate, the data points where y <= 0 are skipped. If there are many such points which should be taken into account for the fit, then convergence is not guaranteed.

Not changed on exit.

12.40.4: err_y

A 1-dimensional array that contains the errors on the coordinates of the points to be fitted.

This argument can also be a scalar, which is then used as error for all points. If this argument is a vector, then it must have the same length as x and y.

Not changed on exit.

12.40.5: parameters

The function that is fitted to the data points is given by

function = factor*slope *
           ((theta+1)**(theta+1)/Gamma(theta+1) *
           (offset+slope*X)**theta *
           exp(-(theta+1)*(offset+slope*X))

i.e. a Polya distribution with argument offset+slope*X and with Polya parameter theta.

The input values for the terms are used as initial values for the fit if the MANUAL option is used (this is not default). The parameters "offset" and "slope" are fitted if the option FIT is specified, otherwise the values have to be specified on input.

Parameters of which the value on input is to be used, must be of type Number.

All arguments except "offset" and "slope" when using the FIX option, must be modifiable, i.e. it can not be a constant nor an expression.

12.40.6: errors

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

These arguments must be modifiable, that is, they can neither be constants nor expressions.

12.40.7: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
AUTO Determine suitable starting values Default
EQUAL Assume equal weight of all points Not default
FIT Fit the scale of the distribution Default
FIX Don't modify the scale parameters Not default
MANUAL Start from given initial values Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Default
PRINT Print details during the fit Not default

Notes:

  1. The EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitely provided in that case.
  2. The plot is always made on a linear-logaritmic scale.

Section 12.41: FIT_POLYNOMIAL

Fits a polynomial to an histogram or to 1-dimensional matrices.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True is the fit converged, and False otherwise.

Format for histograms:

CALL FIT_POLYNOMIAL(reference, a0, a1, a2, ..., an, ...
     err_a0, err_a1, err_a2, ..., err_an [, options])

Format for matrices:

CALL FIT_POLYNOMIAL(x, y, err_y, a0, a1, a2, ..., an, ...
     err_a0, err_a1, err_a2, ..., err_an [, options])

Example:

Call hdelete(ref)
Call hbook(ref,100,-2,2)
For i From 1 To 10000 Do
   Global x=(rnd_uniform-0.5)*4
   Global dy=0.01*(rnd_uniform-0.5)
   Call hfill(ref,x,1+2*x+x**2+dy)
Enddo
Call fit_polynomial(ref,a0,a1,a2,ea0,ea1,ea2,`print,plot`)
Say "a0 = {a0}+/-{ea0}, a1 = {a1}+/-{ea1}, a2 = {a2}+/-{ea2}."

This example is a test to verify that the fit works.

12.41.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or GET_HISTOGRAM. This argument may also be an expression that results in a histogram.

The argument is not modified on return.

12.41.2: x

A 1-dimensional array that contains the ordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

Not changed on exit.

12.41.3: y

A 1-dimensional array that contains the coordinates of the points to be fitted.

The vectors x, y and err_y must have the same length, unless err_y is given as a scalar.

Not changed on exit.

12.41.4: err_y

A 1-dimensional array that contains the errors on the coordinates of the points to be fitted.

This argument can also be a scalar, which is then used as error for all points. If this argument is a vector, then it must have the same length as x and y.

Not changed on exit.

12.41.5: a

Terms in the polynomial expansion:

polynomial = a0 + a1*x + a2*x**2 + a3*x**2 + ... + an*x**n

The input values for the terms are not used in the fitting procedure. Initial values are obtained from an unweighted maximum likelihood fit.

This argument must be modifiable, i.e. it can not be a constant nor an expression.

12.41.6: err_a

The errors returned are the square roots of the diagonal elements of the covariance matrix, multiplied by a correction factor equal to:

     sqrt(chi**2/(#points - #parameters))

This correction factor is equal to 1 if the errors to the data points have been assigned correctly.

These arguments must be modifiable, that is, they can neither be constants nor expressions.

12.41.7: options

The options string may contain the keywords listed in the table below. The keywords should be separated by blanks or commas. Additional text may be added - no error message will be issued if unrecognised keywords are used.

Option Meaning Defaults
EQUAL Assume equal weight of all points Not default
NOPLOT Don't plot the histogram and fit Default
NOPRINT Don't print details during the fit Default
PLOT Plot the histogram with fit Not default
POISSON Assume Poisson errors Default
PRINT Print details during the fit Not default

Note: the EQUAL and POISSON options are ignored for matrix fits since the errors on the points are explicitely provided in that case.

Section 12.42: FORCE_FIELD

Returns the electrostatic component of the force experienced by a wire that would have been located at the specified position. The field still has to be multiplied by a charge to get a force.

This procedure is only of use for debugging, and must be used with caution since it is on purpose not protected for locations inside wires (the call can result in a division by zero).

Format:

CALL FORCE_FIELD(x, y, ex, ey)

12.42.1: coordinates

The coordinates system expected by FORCE_FIELD is the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If use polar coordinates however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians

12.42.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Er = Ex/r
Ephi = Ey/r

Section 12.43: GAS_AVAILABILITY

Returns the status of the gas data.

Format:

CALL GAS_AVAILABILITY(object, available)

12.43.1: object

A String that describes the quantity of which you wish to know whether it is available.

Can be any of the following:

Object GASOK bit
ATTACHMENT-COEFFICIENT 6
CLUSTERING-DATA 5
DRIFT-VELOCITY 1
ION-MOBILITY 2
LONGITUDINAL-DIFFUSION-COEFFICIENT 3
LORENTZ-ANGLE 7
TOWNSEND-COEFFICIENT 4
TRANSVERSE-DIFFUSION-COEFFICIENT 8

12.43.2: available

Is, on return, a Logical which is set to True or False depending on whether the object is available or not.

Section 12.44: GET_CELL_DATA

Informs about the number of wires in the cell, the potential function used to compute the fields and the coordinate system in which the cell has been described. The procedure also returns the cell indentifier.

All arguments are optional.

Format:

CALL GET_CELL_DATA([number_of_wires [, cell_type [, ...
     coordinates [, identifier]]]])

12.44.1: number_of_wires

Is set to the Number of wires present in the chamber.

12.44.2: cell_type

Is, on return, a String which describes the potential_function which is used to compute the field in the chamber.

12.44.3: coordinates

Is, on return, a String which explains the coordinate_system used in the chamber.

12.44.4: identifier

Is, on return, a String which contains the identifier that you may have assigned to the chamber with the CELL-IDENTIFIER command.

Section 12.45: GET_CELL_SIZE

Returns the dimensions of the cell.

If the cell has been entered in polar coordinates, then the dimensions are returned in internal coordinates. These can be converted to Cartesian or polar coordinates with the INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.

If 4 arguments are provided, only the (x,y) part of the cell dimensions is returned. If 6 arguments are present, also the z part is set.

Formats:

CALL GET_CELL_SIZE(xmin, ymin, zmin, xmax, ymax, zmax)
CALL GET_CELL_SIZE(xmin, ymin, xmax, ymax)

Example: see GET_WIRE_DATA

Section 12.46: GET_CLUSTER

Once cluster generation has been initialised by means of a call to NEW_TRACK, one can repeatedly call GET_CLUSTER to get one cluster at the time.

In addition to the parameters, the global variable OK is set by this procedure. Its value is True if generating the clusters worked properly, otherwise it will be set to False. Note that OK is also set to False if DONE has been set to True.

Before using the cluster location and energy, the value of DONE and OK should be checked. The parameters should not be used if either of these two has been set to True.

Format:

CALL GET_CLUSTER(xcls, ycls, zcls, npair, ecls, done)

Example:

track 0 1 1 1 muon energy 10000 nodelta
Call book_histogram(size,100)
For i From 1 To 100 Do
   Call new_track
   Until done Do
      Call get_cluster(xcls,ycls,zcls,npair,ecls,done)
      If done Then Iterate
      Call fill_histogram(size,npair)
   Enddo
Enddo
!opt log-y
Call plot_histogram(size,`Cluster size`,...
   `Cluster size distribution`)
Call plot_end

This example shows how one can obtain the cluster size distribution for tracks generated by the Heed program. Since Heed doesn't generate clusters but always delta electrons (they usually have a very short range), we use the NODELTA-ELECTRONS option on the TRACK command. This compresses the delta electrons into clusters.

12.46.1: xyz

The coordinates at which the cluster is produced. The cluster location is returned in Cartesian coordinates also if the cell has been entered in polar coordinates. The INTERNAL_TO_POLAR procedure can be used for the conversion.

These arguments should not be used if DONE has been set to True or OK to False.

This 3 arguments should be a simple global variables, not formulas or constants. The global variables may already exist before the procedure is called, in which case their contents will be lost, but they may also be an variables that have sofar not been used.

The coordinates are returned as numbers with unit cm.

12.46.2: ecls

The energy deposited in the cluster.

This argument should not be used if DONE has been set to True or OK to False.

These energies only have a meaning when using Heed to generate clusters. If the mean energy to create an electron-ion pair has been entered in the gas section, then for certain track types the energy will be set to npair * Epair.

This argument should be a simple global variable, not a formula or a constant. The global variable may already exist before the procedure is called, in which case its contents will be lost, but it may also be an variable that has sofar not been used.

The energy is expressed in MeV.

12.46.3: npair

The number of electrons (and ions) present in the cluster.

This argument should not be used if DONE has been set to True or OK to False.

This argument should be a simple global variable, not a formula or a constant. The global variable may already exist before the procedure is called, in which case its contents will be lost, but it may also be an variable that has sofar not been used.

12.46.4: done

This variable is set to True if the present call didn't result in a cluster, further calls will not result in clusters either.

Reasons for this to occur are

Note the difference between this parameter and OK, the latter is set to False if an error has been detected generating the clusters, for instance because of buffer overflow in Heed.

DONE is set to False if a cluster has been generated successfully.

This argument should be a simple global variable, not a formula or a constant. The global variable may already exist before the procedure is called, in which case its contents will be lost, but it may also be an variable that has sofar not been used.

Section 12.47: GET_DRIFT_LINE

Returns the (x,y,z,t) coordinates of the current drift line. Each of the 4 arguments receives a 1-dimensional Matrix. Any value these arguments may have before the procedure is called, is lost after the procedure call.

If you wish to retrieve e.g. the length or the coordinates of the end point of the drift path, then DRIFT_INFORMATION provides easier access to the information.

The drift time is expressed in microsec and the z-component of the drift path in cm. Also the (x,y) part of the path is in cm if Cartesian or tube coordinates are used. If the cell has been described in polar coordinates, then (x,y) is represented in internal coordinates:

     (rho,phi)=(log(sqrt(x**2+y**2),arctan(y/x))

These can be converted to Cartesian or polar coordinates with the INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.

Format:

CALL GET_DRIFT_LINE(x, y, z, t)

Example:

Say "Please enter (x,y) of the starting point"
Parse terminal x_start y_start
Call drift_electron(1,1,status,time)
Call get_drift_line(x,y,z,t)
Call plot_graph(t,x,`Time [microsec]`,`x [cm]`,`x vs time`)
Call plot_comment(`UP-LEFT`,`Status: `/status)
Call plot_comment(`DOWN-LEFT`,`Drift time: `/string(time)/` [microsec]`)
Call plot_comment(`UP-RIGHT`, `From (x,y)=(`/string(x_start)/`,`/...
   string(y_start)/`)`)
Call plot_end

A way to plot the relation between the x-coordinate of a drift line and the drift time.

Section 12.48: GET_E/P_TABLE

Returns the list of E/p points which are currently used to interpolate electron and ion transport properties. One can use the GET_GAS_DATA procedure to obtain the pressure in order to convert ep to an electric field.

After the call, the argument is a 1-dimensional Matrix. Any value this argument has before the procedure call, is lost after the call.

Format:

CALL GET_E/P_TABLE(ep)

Example:

Call get_e/p_table(ep)
Call get_gas_data(p)
Call townsend(ep*p,0,0,a)
Call plot_graph(ep*p,a,`E [V/cm]`,`&alpha; [1/cm]`, ...
   `Townsend coefficient`)
Call plot_error_bar(ep*p,a,0,0.1*a)
Call plot_end

Retrieves the set of E/p points, the pressure and the Townsend coefficients, and then makes a plot showing 10 % error bars for the values.

Section 12.49: GET_GAS_DATA

Returns the pressure, temperature and identifier of the gas.

Format:

CALL GET_GAS_DATA(pressure, temperature, identifier)

Example:

Call get_gas_identifier(p, t, gasid)
Say "Gas identifier is {gasid}."

Section 12.50: GET_HISTOGRAM

Retrieves an Histogram which has been written to disk by WRITE_HISTOGRAM. After retrieval, the histogram can further be filled etc.

Format:

CALL GET_HISTOGRAM(reference, file [, member])

12.50.1: reference

This is the name by which you want to reference the histogram when performing fits on it (e.g. with a call to FIT_GAUSSIAN) and when performing arithmetic on it.

This argument plays the same role as the reference argument of BOOK_HISTOGRAM.

If this variable is already associated with a string, histogram or matrix, then this string, histogram or matrix is lost after the call to GET_HISTOGRAM.

12.50.2: file

The name of the Garfield library from which the histogram should be read.

12.50.3: member

The name that has been given to the member in the Garfield library that contains the histogram. If the member name is omitted, then the a member with the name of the global variable to which the histogram is to be assigned, will be searched for.

This is in many cases a meaningful default and there is therefore rarely a need to specify a member.

Section 12.51: GET_MATRIX

GET_MATRIX is used to recover a Matrix from a disk file to which it has been written with the WRITE_MATRIX procedure.

Format:

CALL GET_MATRIX(matrix, file [, member])

Example:

See WRITE_MATRIX.

12.51.1: matrix

This argument is a global variable to which the matrix will be associated. This can not be an expression. If the global variable is already in use, then any string, matrix or histogram linked to it, will be deleted.

12.51.2: file

The name of the Garfield library from which the matrix is to be read.

12.51.3: member

The name of the member in the Garfield library that contains the matrix. If the member name is omitted, then the name of the global variable to which the matrix is to be assigned, will be searched for.

Section 12.52: GET_PERIODS

Returns information periodicities. The first and third argument are logicals that are set to True if the corresponding periodicity is present in the cell. The second and fourth argument are set to the length of one period, if existing, and in internal coordinates.

Format:

CALL GET_PERIODS(yn_x, s_x, yn_y, s_y)

Section 12.53: GET_RAW_SIGNAL

Copies a raw signal to a 1-dimensional matrix. Raw signals serve as ingredient to compute actual signals and are mainly of use if you wish to do such calculations outside Garfield.

Format:

CALL GET_RAW_SIGNAL(type, electrode, avalanche_wire, angle,...
     time, signal)

12.53.1: type

Can be either ELECTRON or ION, for respectively electron and ion induced currents.

12.53.2: electrode

This is the number of a read-out group. Signals are summed over the elements that compose a read-out group - signals for the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[No default, this is a mandatory parameter.]

12.53.3: avalanche_wire

This is the wire number, as shown in the print-out generated in response to CELL-PRINT option, of the wire on which the avalanche takes place.

This wire can be the same as the sense wire but this is not necessarily the case. Note that you must have asked for cross-induced signals in order to have signals computed that are due to avalanches on other wires than the sense wire.

The avalanche wire doesn't have to be SELECT'ed.

12.53.4: angle

The incidence angle of the electron or the ion.

Section 12.54: GET_SIGNAL

Copies a signal to a (set of) 1-dimensional matrices.

Format:

CALL GET_SIGNAL(electrode, time, direct [, cross])

Example:

12.54.1: electrode

This is the number of a read-out group. Signals are summed over the elements that compose a read-out group - signals for the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[No default, this is a mandatory parameter.]

12.54.2: time

On return, this argument is a 1-dimensional Matrix that contains the sampling points in microsec of the signals.

This argument should be a global variable, not a constant or an expression. The global may exist before the call is issued, but doesn't have to. If it exists, then its contents will be lost.

12.54.3: direct

Contains, on return, the direct component of the signal in the form of a 1-dimensional Matrix.

Signals are in microAmp when they are computed, but their units can change as a result of convolutions.

This argument should be a global variable, not a constant or an expression. The global may exist before the call is issued, but doesn't have to. If it exists, then its contents will be lost.

12.54.4: cross

Contains, on return, the cross induced component of the signal in the form of a 1-dimensional Matrix.

This argument is optional.

Signals are in microAmp when they are computed, but their units can change as a result of convolutions.

This argument should be a global variable, not a constant or an expression. The global may exist before the call is issued, but doesn't have to. If it exists, then its contents will be lost.

Section 12.55: GET_X_PLANE_DATA

Returns information on all planes at constant x or r present in the cell.

Internal coordinates are used for the plane locations. Use the INTERNAL_TO_POLAR procedure to convert to, for instance, polar coordinates.

All arguments are mandatory.

Format:

CALL GET_X_PLANE_DATA(yn_1, x_1, V_1, label_1, ...
                      yn_2, x_2, V_2, label_2)

Example:

Call get_cell_data(wires,type,coord,id)
Call get_x_plane_data(yn1,x1,V1,lab1, yn2,x2,V2,lab2)
If 'coord="Polar"' Then
   If yn1 Then Say "There is a plane at r={exp(x1)} and with V={V1}."
   If yn2 Then Say "There is a plane at r={exp(x2)} and with V={V2}."
Else
   If yn1 Then Say "There is a plane at x={x1} and with V={V1}."
   If yn2 Then Say "There is a plane at x={x2} and with V={V2}."
Endif

Section 12.56: GET_Y_PLANE_DATA

Returns information on all planes at constant y or phi present in the cell.

Internal coordinates are used for the plane locations, use the INTERNAL_TO_POLAR procedure to convert to polar coordinates.

All arguments are mandatory.

Format:

CALL GET_Y_PLANE_DATA(yn_1, y_1, V_1, label1, ...
                      yn_2, y_2, V_2, label2)

Example:

Call get_cell_data(wires,type,coord,id)
Call get_y_plane_data(yn1,y1,V1,lab1, yn2,y2,V2,lab2)
If 'coord="Polar"' Then
   If yn1 Then Say "There is a plane at phi={180*y1/pi} and with V={V1}."
   If yn2 Then Say "There is a plane at phi={180*y2/pi} and with V={V2}."
Else
   If yn1 Then Say "There is a plane at y={y1} and with V={V1}."
   If yn2 Then Say "There is a plane at y={y2} and with V={V2}."
Endif

Section 12.57: GET_WIRE_DATA

Returns information about a wire: the location in internal coordinates, the potential, the diameter, the charge, the wire label, the length, the stretching weight and the density.

All arguments are optional.

Format:

CALL GET_WIRE_DATA(wire, x, y, V, d, q, label, ...
   length, weight, density)

Example:

Call get_cell_data(nwire,dummy,dummy,id)
Say "List of wires with a negative charge:"
For i From 1 To nwire Do
   Call get_wire_data(i,xw,yw,vw,dw,qw,labelw)
   If qw>0 Then Iterate
   Say "Wire {i} at (x,y)=({xw,yw}), type {labelw}"
Enddo

This example shows how one can produce a list of the wires that have a negative charge. One could also select a sense wire and store its coordinates using this technique.

12.57.1: wire

Should contain the number of the wire when the procedure is called.

This argument is mandatory and is not modified.

[No default.]

12.57.2: x

Contains, on return, the x- or rho-location of the wire in cm for x, and log(cm) for rho.

If the cell has been entered in polar coordinates, then the wire location is returned in internal coordinates. These can be converted to Cartesian or polar coordinates with the INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.3: y

Contains, on return, the y- or phi-location of the wire in cm for y, and in radians for phi.

If the cell has been entered in polar coordinates, then the wire location is returned in internal coordinates. These can be converted to Cartesian or polar coordinates with the INTERNAL_TO_CARTESIAN and INTERNAL_TO_POLAR procedures.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.4: V

Contains, on return, the potential at the wire surface as entered with the ROWS statement in the &CELL section. The potential is returned in Volts.

The CHECK instruction can display the potential that is computed for the neighbourhood of the wire.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.5: q

Contains, on return, the charge that has been computed for the wire. The unit of charge in Garfield is 1/Volt.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.6: label

Contains, on return, a character string with the label of the wire.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.7: length

Contains, on return, the length of the wire, in cm.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.8: weight

Contains, on return, the weight with which the wire has been pulled during assembly, in grams.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

12.57.9: density

Contains, on return, the density of the material of which the wire is made, in g/cm3.

This argument is optional. The argument should be a global variable, not a constant nor an expression. The global may have been declared prior to the call, but doesn't have to. The value an existing variable had before the call will be lost.

Section 12.58: GKS_AREA

Plots a fill area.

This procedure is a direct interface to the GKS routine GFA. The first argument of GFA, the vector length, is absent.

The area is plotted with the area attributes, and using the normalisation transformation that are in effect at the time the procedure is called.

Format:

CALL GKS_AREA(x,y)

12.58.1: coordinates

The arguments of this procedure are 1-dimensional vectors (i.e. of type Matrix) of equal length.

The vectors should have a minimum length of 3.

[No defaults, these are mandatory parameters.]

Section 12.59: GKS_POLYLINE

Plots a polyline.

This procedure is a direct interface to the GKS routine GPL. The first argument of GPL, the vector length, is absent.

The polyline is plotted with the polyline attributes, and using the normalisation transformation that are in effect at the time the procedure is called.

Format:

CALL GKS_POLYLINE(x,y)

12.59.1: coordinates

The arguments of this procedure are 1-dimensional vectors (i.e. of type Matrix) of equal length.

The vectors should have a minimum length of 2.

[No defaults, these are mandatory parameters.]

Section 12.60: GKS_POLYMARKER

Plots a polymarker.

This procedure is a direct interface to the GKS routine GPM. The first argument of GPM, the vector length, is absent.

The polymarker is plotted with the polymarker attributes, and using the normalisation transformation that are in effect at the time the procedure is called.

Format:

CALL GKS_POLYMARKER(x,y)

12.60.1: coordinates

The arguments of this procedure are 1-dimensional vectors (i.e. of type Matrix) of equal length.

The vectors should have a minimum length of 1.

[No defaults, these are mandatory parameters.]

Section 12.61: GKS_SELECT_NT

Selects the normalisation transformation.

This procedure is equivalent to the GKS routine GSELNT.

Format:

CALL GKS_SELECT_NT(nt)

12.61.1: nt

The Number) of the normalisation transformation you wish to select.

A normalisation transformation is composed of a window and a viewport, and is referenced via an integer number.

Normalisation transformation 0 is pre-defined by GKS and corresponds to window limits of (0,0) and (1,1).

[No default, this is a mandatory parameter.]

Section 12.62: GKS_SET_CHARACTER_EXPANSION

Sets the character expansion factor.

This procedure is an interface to the GKS routine GSCHXP.

Format:

CALL GKS_SET_CHARACTER_EXPANSION(expansion)

12.62.1: expansion

A Number which is used to expand or shrink the horizontal extent of a letter with respect to the vertical extent.

An expansion of 1 corresponds to normal text.

Section 12.63: GKS_SET_CHARACTER_HEIGHT

Sets the character height

This procedure is an interface to the GKS routine GSCHH.

Format:

CALL GKS_SET_CHARACTER_HEIGHT(height)

Section 12.64: GKS_SET_CHARACTER_SPACING

Sets the character spacing

This procedure is an interface to the GKS routine GSCHSP.

Format:

CALL GKS_SET_CHARACTER_SPACING(spacing)

12.64.1: spacing

A Number which is used to increase the spacing between the letters of a piece of text.

A spacing of 0 corresponds to normal text.

Section 12.65: GKS_SET_CHARACTER_UP_VECTOR

Sets the character up vector

This procedure is an interface to the GKS routine GSCHUP.

Format:

CALL GKS_SET_CHARACTER_UP_VECTOR(x, y)

12.65.1: vector

A set of 2 Numbers that form a vector perpendicular to the path of the text while the text flows from left to right when looking along the vector.

Section 12.66: GKS_SET_TEXT_ALIGNMENT

Sets the text alignments.

The text alignments specify where a piece of text is to placed with respect to its anchor point.

This procedure is an interface to the GKS routine GSTXAL.

Format:

CALL GKS_SET_TEXT_ALIGNMENT(hor, vert)

12.66.1: alignments

The horizontal and vertical alignments are Strings which can have the following values:

Alignment Numeric Meaning Notes
NORMAL 0 Depends on system Usually LEFT
LEFT 1 Left aligned -
CENTRE 2 Centre aligned -
RIGHT 3 Right aligned -

and v one of the vert

Alignment Numeric Meaning Notes
NORMAL 0 Depends on system Usually BASE
TOP 1 Highest point of "l" -
CAP 2 Highest point of "o" -
HALF 3 Centre aligned -
BASE 4 Lowest point of "o" Not in HIGZ
BOTTOM 5 Lowest point of "y" Not in HIGZ

[No defaults, these are mandatory arguments.]

Section 12.67: GKS_SET_TEXT_COLOUR

Sets the text colour index.

This procedure is a direct interface to the GKS routine GSTXCI.

Format:

CALL GKS_SET_TEXT_COLOUR(colour)

12.67.1: colour

The colour is specified with a String that contains the name of the colour.

Colour names are established with the COLOUR command.

Section 12.68: GKS_SET_TEXT_FONT_PRECISION

Sets the text font and precision.

This procedure is a direct interface to the GKS routine GSTXFP.

CALL GKS_TEXT_FONT_PRECISION(font, precision)

12.68.1: font

The Number of the HIGZ fonts or of the GTS-GRAL/GKS fonts that you wish to use.

12.68.2: precision

A Number with one of the text precisions in GKS:

Precision Meaning
STROKE Highest precision, all attributes respected
CHARACTER Standard precision
STRING Low precision, suited for fast rendering

Section 12.69: GKS_TEXT

Plots a text string.

This procedure is a direct interface to the GKS routine GTX.

The text is plotted with the polyline attributes, the alignment, the up-vector and using the normalisation transformation that are in effect at the time the procedure is called. These attributes can either be set at the GKS level by calling GKS_SET_CHARACTER_EXPANSION, GKS_SET_CHARACTER_HEIGHT, GKS_SET_CHARACTER_SPACING, GKS_SET_CHARACTER_UP_VECTOR, GKS_SET_TEXT_ALIGNMENT, GKS_SET_TEXT_COLOUR and GKS_SET_TEXT_FONT_PRECISION, or at the Garfield level by calling SET_TEXT_ATTRIBUTES.

Format:

CALL GKS_TEXT(x,y,text)

12.69.1: coordinates

The arguments of this procedure are 2 Numbers that specify the anchor point of the text that is to be plotted.

Where the text will appear with respect to the anchor point depends on the text alignment.

[No defaults, these are mandatory parameters.]

12.69.2: text

A text String.

[No default, this is a mandatory parameter.]

Section 12.70: GKS_VIEWPORT

Sets the viewport for a normalisation transformation.

Specifying a window doesn't entail an automatic change of normalisation transformation.

This procedure is equivalent to the GKS routine GSVP.

Format:

CALL GKS_VIEWPORT(nt, xmin, xmax, ymin, ymax)

12.70.1: nt

The normalisation transformation for which you wish to set the viewport.

A normalisation transformation is composed of a window and a viewport, and is referenced via an integer number.

Normalisation transformation 0 is pre-defined by GKS and corresponds to window limits of (0,0) and (1,1).

[No default, this is a mandatory parameter.]

12.70.2: limits

The limits of the viewport, i.e. the part of the workstation window that you wish to occupy with the plot.

The limits are expressed in normalised device coordinates, i.e. the system in which (0,0) is the lower left hand corner and (1,1) the upper right hand corner.

Note the order of the arguments, which is different from the usual order of window specifications in Garfield.

[No default, these are mandatory parameters.]

Section 12.71: GKS_WINDOW

Sets the window for a normalisation transformation.

Specifying a window doesn't entail an automatic change of normalisation transformation.

This procedure is equivalent to the GKS routine GSWN.

Format:

CALL GKS_WINDOW(nt, xmin, xmax, ymin, ymax)

12.71.1: nt

The normalisation transformation for which you wish to set the window.

A normalisation transformation is composed of a window and a viewport, and is referenced via an integer number.

Normalisation transformation 0 is pre-defined by GKS and corresponds to window limits of (0,0) and (1,1).

[No default, this is a mandatory parameter.]

12.71.2: limits

The limits of the window, i.e. the part of your coordinate system that should be mapped onto the viewport.

The limits are expressed in the coordinate system in which you perform your calculations.

Note the order of the arguments, which is different from the usual order of window specifications in Garfield.

[No default, these are mandatory parameters.]

Section 12.72: HISTOGRAM_TO_MATRIX

Makes a matrix copy of an histogram, optionally returning the range of the histogram. The histogram is not affected by this operation.

Format:

CALL HISTOGRAM_TO_MATRIX(hist, matrix [, min [, max]])

Example:

Call book_histogram(ref1,10,0,1)
For i From 1 To 1000 Do
   Call fill_histogram(ref1,rnd_uniform)
Enddo
Call plot_histogram(ref1)
Call plot_end
Call histogram_to_matrix(ref1,a,min,max)
Call matrix_to_histogram(a,min,max,ref2)
Call plot_histogram(ref2)
Call plot_end

First, we book an histogram and fill it with uniformly distributed random numbers. The histogram is then copied to a matrix A, and then copied back to a histogram. Both histograms are plotted to check they are indeed the same.

Section 12.73: INDUCED_CHARGE

Integrates the charge induced over a given time interval in an electrode by an electron or an ion released from a given point.

To take the effect of electronics into account, one should calculate signals instead (see SIGNAL), process them (see CONVOLUTE-SIGNALS) and recuperate the results (see GET_SIGNAL) to integrate them as matrices.

The procedure first drifts a particle of the desired kind from the starting point. Next, the routine integrates the internal product of the weighting field for the electrode that is read out and the drift velocity between the time limits over the drift path. The result is multiplied with minus the charge of the particle that has been drifting.

Contrary to appearances, the total induced charge (i.e. integrated over the entire drift path) thus computed is a surprisingly boring quantity. A charged particle that moves from one electrode to another can only induce a total charge of +1, 0 or -1. The total charge is +1 or -1 in case the particles moves from an electrode that is read out to one that is not, or vv. The total charge is 0 if the particle moves between electrodes which are both read out or are both not read out.

The sum of charges induced on all electrodes vanishes: the effect of a moving charge in a chamber is a reshuffling of the charges on the conductors, charges are not created and do not vanish.

The charge between

Format:

CALL INDUCED_CHARGE(x, y, z, particle, electrode ...
   [, tmin, tmax], q)

Example:

&CELL
pl y -1 label p
pl y +1 label q
rows
a * * +0.5 0 -1000
s * *  0   0  1000
b * * -0.5 0 -1000

&GAS co2

&SIG area -1.1 -1.1 1.1 1.1 sel (pq)s(ab) Call induced_charge(-0.4,-0.5,0,`e-`,2,q1) Call induced_charge(-0.4,-0.5,0,`e+`,2,q2) Say "Status e-: {stat1}, e+: {stat2}" Say "Charge between wire and plane: {q1+q2}"

Verifies that the total charge induced by a particle moving between two conductors (the B wire and a plane) other than the one that is read out (the S wire), is indeed 0.

A more elaborate application of this procedure can be found in http://consult.cern.ch/writeup/garfield/examples/charge

12.73.1: particle

A string that specifies the particle that you wish to drift.

Value Meaning
`E-` electron
`E+` positron
`ION-` negatively charged ion
`ION+` positively charged ion

[No default, this is a mandatory parameter.]

12.73.2: electrode

This is the number of a read-out group. The charges are summed over the elements that compose a read-out group, the charges on the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[No default, this is a mandatory parameter.]

12.73.3: tmin_tmax

The time limits of the integration.

These arguments are optional. If they are omitted, the charge is integrated over the entire drift path.

12.73.4: q

On return, this parameter contains the integrated charge.

This argument should be a global variable, not an expression nor a constant. The variable doesn't have to be declared. Any value the variable has before the call, is lost after the call.

The charge is expressed in multiples of the electron charge.

Section 12.74: INQUIRE_FILE

Tells whether a file exists or not.

The file does not have to be a Garfield library. If you wish to test the presence of, for instance, a gas description is a given library, then you should use INQUIRE_MEMBER.

Format:

CALL INQUIRE_FILE(file_name, exist)

Example:

&CELL
Call inquire_file(`new_cell`,exist)
If exist Then
   % del "dc1.lib" cell
   < new_cell
   write "dc1.lib" cell
Else
   get "dc1.lib" cell
Endif

In this example a cell description is retrieved from a library called dc1.lib, unless a file called new_cell is found. In that case, the cell description is deleted from the library, the new description is read and stored in compact format in the library.

Section 12.75: INQUIRE_HISTOGRAM

Returns some information on a histogram that must be in storage.

Calling this procedure does not interfere with the filling process.

The first 2 arguments are mandatory, the rest is optional.

Format:

CALL INQUIRE_HISTOGRAM(reference, exists, set, channels,
     minimum, maximum, entries, average, rms)

12.75.1: reference

The Histogram about which you wish to obtain information.

[No default, this is a mandatory argument.]

12.75.2: exists

Contains on return a Logical which has the value True if the histogram exists, and the value False if it doesn't.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.3: set

Contains on return a Logical which has the value True if the range of this histogram has been established, and False if this is an AUTOSCALE histogram which has collected too few entries sofar to have its range set.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.4: channels

Contains on return the Number of bins of the histogram.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.5: minimum

Contains on return the coordinate of the lower edge of the first bin.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.6: maximum

Contains on return the coordinate of the upper edge of the last bin.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.7: entries

Contains on return the Number of entries sofar collected in the histogram. The weight of an entry doesn't have an incidence on the entry count. Entries outside the range of the histogram are counted.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.8: average

Contains on return the average of the entries collected sofar in the histogram. The average is computed from all entries, whether inside or outside the range of the histogram, respecting the weight of each entry. Binning has no incidence on the way the average is computed.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

12.75.9: rms

Contains on return the RMS of the entries collected sofar in the histogram. The RMS is computed from all entries, whether inside or outside the range of the histogram, respecting the weight of each entry. Binning has no incidence on the way the RMS is computed.

This argument must me modifiable, i.e. it must be a simple variable name and not an expression. The argument is optional.

The value of this argument on entry is not used, and is lost after the procedure call.

Section 12.76: INQUIRE_MEMBER

Tells whether a member in a library exists or not, approximately equivalent to the INDEX dataset command.

The return flag EXIST is set to True only if all of the following conditions are fulfilled:

Otherwise EXIST is set to False and the arguments MEMBER, REMARK, DATE and TIME are not touched.

Use the INQUIRE_FILE procedure if you only wish to find out whether a file exists.

Format:

CALL INQUIRE_MEMBER(file, member, type, exist ...
     [,remark [, date [, time]]])

Example:

&GAS
Call inquire_member(`GAS.DAT`,`XE50E50`,`GAS`,exist)
If exist Then
   get gas.dat xe50e50
Else
   pressure 500
   temperature 300
   magboltz xenon 50 ethane 50
   write gas.dat xe50e50
Endif

In this example the existence of a member called XE50E50 in a library called GAS.DAT is checked. Since the type is set to GAS, only compact gas descriptions are considered. If the member exists, the data is read, otherwise a new table is prepared and is then written to the file.

12.76.1: file

The name of the library in which the member is to be searched.

This parameter should be a String or an expression that evaluates to a character string.

[This argument is mandatory, no default is supplied.]

12.76.2: member

The name of the member to be searched for.

This parameter can be a wildcard, for instance `*` would search for the first occurence of a member of the given type. If this argument is modifiable, it will be overwritten by the member type found.

This argument should be a String or an expression that evaluates to a character string.

[This argument is mandatory, no default is supplied.]

12.76.3: type

The type of the member to be searched for.

This argument can not be a wildcard.

The argument should be a String of up to 8 characters, and may also be an expression that evaluates to such a string.

[This argument is mandatory, no default is supplied.]

12.76.4: exists

Is set, on return, to a String which tells whether the member exists or not.

This argument should be modifiable, any object associated with it at the time the call is made, will be deleted. The value of the variable on input, if any, is not used.

[This is a mandatory argument.]

12.76.5: remark

This argument is set to the remark string that was given to the member when it was created.

This argument should be modifiable, any object associated with it at the time the call is made, will be deleted.

The argument is on return a String of up to 29 characters.

[This is an optional argument.]

12.76.6: date

This argument is set to the date on which the member was created, in the form of a character string.

This argument should be modifiable, any object associated with it at the time the call is made, will be deleted.

The argument is on return a String of up to 8 characters.

[This is an optional argument.]

12.76.7: time

This argument is set to the time when the member was created, in the form of a character string.

This argument should be modifiable, any object associated with it at the time the call is made, will be deleted.

The argument is on return a String of up to 8 characters.

[This is an optional argument.]

Section 12.77: INQUIRE_TYPE

The INQUIRE_TYPE procedure can be used to determine whether a given global variable exists and, if it does, what type it has. The procedure also accepts expressions as first argument.

The return parameter, type, can have the following values: `String`, `Number`, `Logical`, `Histogram`, `Matrix`, `Undefined` and `# Invalid`.

This procedure provides a functionality which is similar to that of the TYPE function.

Format:

CALL INQUIRE_TYPE(variable, type)

Example:

Call book_histogram(hist,10,0,10)
Call inquire_type(hist,type)
Say "Type is {type}"

Section 12.78: INTEGRATE_CHARGE

Integrates, depending on the format that is used, the charge in

In the 2-dimensional case, the charge is normalised such that a line charge with potential

        1       2   2
   V = --- log(x + y )
       2pi

would return a charge of 1. In the 3-dimensional case, a point charge with potential

              __________ -1
        1    /  2   2  2
   V = --- \/ x + y + z
       4pi

would also yield a total charge of 1. These normalisations should match the fields that are used for wires and space charges.

Integration is performed using 6-point Gaussian quadrature over 50 equal intervals for the 2-dimensional case, and over 20 equal intervals both in phi and in theta for the 3-dimensional case.

Format:

CALL INTEGRATE_CHARGE(x, y, [z,] r, q)

Example:

&CELL
rows
s * * 1 1 1000
s * * -1 -1 -1000

opt cell-print

&OPT charges 2 2 2 1 3 2 3 4.5

&FIELD Call integrate_charge(1.1, 0.5, 0.8, q) Say "One wire: {q}" Call integrate_charge(5, 2, 2.5, 3.5, q) Say "Both point charges together: {q}"

(Verifies the line and point charges.)

Section 12.79: INTEGRATE_FLUX

Integrates the flux of the E field over a parallelogram. The parallelogram has (x0,y0,z0) as one of its edges while the adjacent edges are (x0+dx1,y0+dy1,z1+dz1) and (x0+dx2,y0+dy2,z1+dz2). The flux is returned in Volt.cm.

Integration is performed using 6-point Gaussian quadrature over (nu x nv) equal intervals along the two sides of the reactangle. The arguments nu and nv are optional. They are by default set to 20.

This procedure is used to investigate transmission losses.

Format:

CALL INTEGRATE_FLUX(x0,y0,z0, dx1,dy1,dz1, dx2,dy2,dz2, flux
     [, nu [, nv]])

Example:

&CELL
plane x=-1 v=-1000
plane x=+1 v=+1000
rows
s * * 20 20 0

&FIELD Call flux(0,-1,-1, 0,2,0, 0,0,2, flux) Say "Flux={flux} [V.cm]"

In a parallel plate chamber, with a field of 1 kV/cm, we compute the flux through a rectangle of 2 cm by 2 cm. The flux is equal to 1000 V/cm x 4 cm^2 = 4000 V.cm

Section 12.80: INTERNAL_TO_CARTESIAN

Applies the conformal mapping of internal (rho,phi) coordinates to Cartesian (x,y) coordinates. The (rho,phi) coordinates are used internally in the program when the cell is described in polar coordinates.

Internal coordinates are related to Cartesian coordinates by:

     x = cos(phi)*exp(rho)        [phi in radian, x in cm]
     y = sin(phi)*exp(rho)        [phi in radian, y in cm]

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name RTC is also accepted.

Format:

CALL INTERNAL_TO_CARTESIAN(rho,phi,x,y)

Section 12.81: INTERNAL_TO_POLAR

Converts internal (rho,phi) coordinates to polar (r,phi') coordinates. The (rho,phi) coordinates are used internally in the program when the cell is described in polar coordinates.

Internal coordinates are related to polar coordinates by:

     r    = exp(rho)       [dimensions not defined]
     phi' = 180*phi/pi     [phi' in degrees]

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name RTP is also accepted.

Format:

CALL INTERNAL_TO_CARTESIAN(rho,phi,x,y)

Section 12.82: INTERPOLATE

The INTERPOLATE procedure performs linear interpolation in matrices of up to 5 dimensions for an arbitrary number of points.

This procedure is intended for interpolations in multi-dimensional matrices for a series of points at the time. For single-point interpolations in 1-dimensional arrays, it is easier to use the INTERPOLATE_i (i = 1, 2, 3 or 4) procedures which furthermore permit higher order polynomial interpolation.

Format:

CALL INTERPOLATE(matrix, ord_1, ... ord_n, points, out)

Example:

Call get_matrix(time,`transfer.mat`)
Call get_matrix(z,`transfer.mat`)
Call get_matrix(delta,`transfer.mat`)

Say "Please enter the value of z for which you wish the transfer function:" Global OK=False Global z_hit=-1 While ^OK Do Parse terminal z_hit Global OK=z_hit>=0 & z_hit<=6 If ^OK Then Say "Please enter a value between 0 and 6 m." Enddo

Call dimensions(time,ndim_time,dim_time) Call book_matrix(point,2,dim_time[1]) Call delete_matrix(dim_time) Global point[1;]=z_hit Global point[2;]=time

Call interpolate(delta,z,time,point,trans) Call delete_matrix(point)

The matrix delta contains the delta-responses of a tube measured at various points along the tube (written z) and as function of time (written time). The purpose of the example is to show how one can compute the delta- response for intermediate values of z by interpolation.

12.82.1: matrix

A global variable associated with a matrix, or an expression that results in a matrix.

In the description of this routine, n is used for the number of dimensions of this matrix.

12.82.2: ord

Vectors of ordinates, one vector is required along each of the dimensions of the matrix.

12.82.3: points

An n-matrix or an nxm-matrix, where n is the number of dimensions of the matrix to be interpolated in. The value of m, the number of points for which interpolation is requested, is limited only by available storage.

12.82.4: out

The result of the interpolation is stored in the matrix out. This is an m-matrix where m is the number of points for which interpolation is requested.

This argument should be a global variable. If the variable is already in use, then any string, histogram or matrix associated with it will be deleted.

Section 12.83: INTERPOLATE_i

A series of 4 procedures (INTERPOLATE_1, INTERPOLATE_2, INTERPOLATE_3 and INTERPOLATE_4) which perform 1-dimensional local linear, parabolic, cubic and quartic polynomial interpolations.

For (linear) interpolation in higher-dimensional matrices, use the INTERPOLATE procedure.

Format:

CALL INTERPOLATE_i(x_vector, y_vector, x, y)

Example:

sel 1
check wire keep-results
Call interpolate_2(phi_1, e_1, pi/2, e90)
Call interpolate_2(phi_1, e_1, 3*pi/2, e270)
Say "Electric field at 90 degrees is {e90} and at 270 degrees {e270}."

In this example, one computes the field at the surface of wire 1 and asks to save the results in a series of vectors. Since the values at 90 and 270 degrees are not present in these vectors, one uses one of the INTERPOLATE_i procedures to interpolate for these angles.

12.83.1: vectors

Both x_vector and y_vector should be a 1-dimensional Matrix. They should have the same length, and the length should be at least equal to the order of interpolation + 1. If the length is less, then the order of interpolation is lowered accordingly.

The vector x_vector should be in strictly increasing order, i.e. each element should be larger than, and not equal to, the one preceding it.

[These are mandatory arguments, no defaults are supplied.]

12.83.2: coordinate

The coordinate at which interpolation is to be performed should be a Number larger than or equal to the first element of x_vector and smaller than or equal to the last element.

If the coordinate is outside this range, then 0 is returned. No error condition is raised in this case.

[This is a mandatory argument, no default is supplied.]

Section 12.84: INTERPOLATE_TRACK

Performs an interpolation, at a given location, of a track that has been prepared with PREPARE-TRACK.

Track preparation is a means to obtain rapidly, mainly for the sake of Monte Carlo calculations, numerous drift times, integrated diffusions and multiplications for a single track.

Format:

CALL INTERPOLATE_TRACK(x, y, z, status [, time [, ...
   diffusion [, multiplication [, attachment [, angle]]]]])

Example:

Global n 20
track 0.5 -0.9 0.5 0.9 lines {n}
prepare-track
Call book_matrix(yvec,n)
Call book_matrix(tvec,n)
Call book_matrix(dvec,n)
Call book_matrix(avec,n)
Call book_matrix(bvec,n)
Call new_track
For i From 1 To n Do
   Call get_cluster(x,y,z,npair,e,done)
   Call interpolate_track(x,y,z,status,time,diff,aval,loss)
   Say "From ({x,y,z}), t={time}, status={status}"
   Global yvec[i]=y
   Global tvec[i]=time
   Global dvec[i]=diff
   Global avec[i]=aval
   Global bvec[i]=loss
Enddo
Call plot_graph(yvec,tvec,`y [cm]`,`Time [microsec]`, ...
   `Drift time`)
Call plot_end
Call plot_graph(yvec,dvec,`y [cm]`,`Diffusion [microsec]`, ...
   `Diffusion`)
Call plot_end
Call plot_graph(yvec,avec*bvec,`y [cm]`,`Electron`, ...
   `Multiplication and loss`)
Call plot_end

A track is defined by its location and its clustering model. In this example, the clustering model is chosen to be a fixed number of regularly spaced points along the track, a convenient choice for making the drift time, diffusion and multiplication graphs.

12.84.1: status

See status.

12.84.2: time

See time.

12.84.3: diffusion

See diffusion.

12.84.4: multiplication

See multiplication.

12.84.5: attachment

See attachment.

12.84.6: angle

The incidence angle of the electron on the electrode that it reaches.

The incidence angle is defined for wires and cylindrical solids. The angle is set to 0 for all other electrodes. Electrons in principle hit planes perpendicularly, but the actual angle is not computed.

[Expressed in radians.]

Section 12.85: ION_MOBILITY

Returns the ion mobility, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the ion mobility is returned in cm2/V.microsec.

Format:

CALL ION_MOBILITY(ex, ey, ez, mobility)

Section 12.86: ION_VELOCITY

Returns the ion drift velocity vector at a point.

This procedure needs ion mobility data, which can for instance be entered with the TABLE and ADD gas section commands. The magnetic field, if present, is taken into account for the calculation of the vector. Diffusion data is not used, even if present - the vector that is returned represents the mean ion drift velocity at a given point.

This procedure provides functionality similar to the SPEED command.

Format:

CALL ION_VELOCITY(x, y, z, vx, vy, vz [, status])

Example:

Call ion_velocity(2,3,0,vx,vy,vz,status)
Say "Velocity: ({vx,vy,vz}), Status: {status}"

12.86.1: coordinates

This procedure accepts coordinates of type Number only.

The coordinates are expected to refer to the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If polar coordinates are used however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: z

The z-coordinate is not affected by any of the conformal mappings currently in use by the program.

These mappings can be performed with the POLAR_TO_INTERNAL procedure.

12.86.2: velocity

The velocity is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

vr = vx/r
vphi = vy/r
vz is invariant

12.86.3: status

See status.

Section 12.87: LIST_HISTOGRAMS

Prints a summary of all histograms currently in storage.

Format:

CALL LIST_HISTOGRAMS

Section 12.88: LIST_MATRICES

LIST_MATRICES prints an overview of matrices currently in memory and of the global variables associated with them.

Format:

CALL LIST_MATRICES

Example:

Call book_matrix(a,2,3,4,5)
Call list_matrices
Call delete_matrix(a)
Call list_matrices

Section 12.89: LIST_RAW_SIGNALS

Lists the raw signals that are currently in store.

Format:

CALL LIST_RAW_SIGNALS

Example:

&SIGNAL
track 0.5 -0.5 0.5 0.5
ava exp 10000
res 0 0.01 200
opt nocl-pr nocl-pl
sel 1
signal
Call list_raw_signals
Call get_raw_signal(`ion`,1,1,0,time,sig)
Call plot_frame(0,0,4,10,` `,` `,` `)
Call plot_line(time,sig)
Call plot_end

In this example, the LIST_RAW_SIGNALS call is used to determine which raw signals are currently available. Then, one of them is retrieved and plotted.

Section 12.90: LONGITUDINAL_DIFFUSION

Returns the longitudinal diffusion, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the diffusion is returned in sqrt(cm).

SIGMA_L can be typed as a synonym to LONGITUDINAL_DIFFUSION.

Format:

CALL LONGITUDINAL_DIFFUSION(ex, ey, ez, sigma_l)

Section 12.91: LORENTZ_ANGLES

Returns the Lorentz angles, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the Lorentz angles are returned in radians.

Format:

CALL LORENTZ_ANGLES(ex, ey, ez, angle)

Section 12.92: MAGNETIC_FIELD

Returns the magnetic field vector at a given point. This procedure assumes that the z-coordinate of the point is equal to 0.

Format:

CALL MAGNETIC_FIELD(x, y, bx, by, bz [, b])

12.92.1: coordinates

The coordinates system expected by MAGNETIC_FIELD is the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If use polar coordinates however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians

12.92.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Br = Bx/r
Bphi = By/r
Bz = Bz

Section 12.93: MAGNETIC_FIELD_3

Returns the magnetic field vector at a given point.

Format:

CALL MAGNETIC_FIELD_3(x, y, z, bx, by, bz [, b])

12.93.1: coordinates

The coordinates system expected by MAGNETIC_FIELD_3 is the internal frame. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If use polar coordinates however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: z

12.93.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Br = Bx/r
Bphi = By/r
Bz = Bz

Section 12.94: MAP_ELEMENT

Returns the coordinates of the vertices of an element of the field map.

The input argument is an element number which, for a given location, can be obtained with the related MAP_INDEX procedure. The dielectric constant of the element can be found with MAP_MATERIAL.

The output arguments depend on the elements used in the field map:

This procedure is meaningful only when the field is generated by a field map. This procedure is used for debugging such maps.

Formats:

CALL MAP_ELEMENT(element, x1, y1, x2, y2, x3, y3)
CALL MAP_ELEMENT(element, x1, y1, z1, x2, y2, z1, x3, y3, z3, ...
   x4, y4, z4)

Example:

Call plot_frame(-1.6,-1.6,1.6,1.6,`x [cm]`,`y [cm]`,`Mesh structure`)
For i From 1 Step 1 Until ^OK To 10000 Do
   Call map_element(i,x1,y1,x2,y2,x3,y3)
   If ^OK Then Leave
   Call plot_area(x1,y1,x2,y2,x3,y3,`material-2`)
Enddo
Call plot_end

This example assumes a triangular map of less than 10000 elements. It fetches one element at the time, then plots it.

Section 12.95: MAP_INDEX

Returns the index of the triangle or tetrahedron in which a point is located, and optionally also the local triangular, tetrahedron or isoparametric parallelepiped coordinates of the point.

The arguments to be provided depend on the elements used in the field map:

This procedure does not reduce the input coordinates to the elementary cell, even if the cell has been declared to have symmetries.

This procedure is meaningful only when the field is generated by a field map. This procedure is used for debugging such maps.

Format:

CALL MAP_INDEX(x, y [, z], index, [t1, t2, t3 [,t4]])

Section 12.96: MAP_MATERIAL

Returns the material index and the dielectric constant for a given field map element.

The first argument of the procedure is the element number which, for a given location, can be obtained with the MAP_INDEX procedure. The geometric aspects of the element can be found with MAP_ELEMENT.

Format:

CALL MAP_MATERIAL(element, material, epsilon)

Example:

Global xmin=-0.0100
Global xmax=+0.0100
Global ymin=-0.0180
Global ymax=+0.01800
Global z=0.0032
Global n=50
!rep function-1 polymarker-colour green marker-type circle marker-size 0.2
!rep function-2 polymarker-colour blue  marker-type circle marker-size 0.2
!rep function-3 polymarker-colour red   marker-type circle marker-size 0.2
Call plot_field_area
For i From 1 Step 1 To n Do
   Global x=xmin+(i-1)*(xmax-xmin)/(n-1)
   For j From 1 Step 1 To n Do
      Global y=ymin+(j-1)*(ymax-ymin)/(n-1)
      Call map_index(x,y,0,index)
      Call map_material(index,ieps,eps)
      If eps<4 Then Iterate
      Call efield3(x,y,z,ex,ey,ez,e)
      If ez<0 Then
         Call plot_marker(x,y,`function-1`)
      Elseif ez>5000 Then
         Call plot_marker(x,y,`function-3`)
      Else
         Call plot_marker(x,y,`function-2`)
      Endif
   Enddo
Enddo
Call plot_end

This example shows how one can find areas of a GEM foil that attract electrons, and thus can cause inefficiencies. A scan is made just above the foil (at z=32 micron). over a grid of n x n points. A green marker is plotted in places where the z-component of the field is negative (i.e. areas where the foil will not attract electrons), a red marker shows spots where electrons are attracted and a blue marker is used for the transition regions. To exclude the hole in the GEM, which should not be shown in red since this area attracts electrons when the GEM operates properly, the dielectric constant at z=0, i.e. in the middle of the kapton layer, is checked.

Section 12.97: MATRIX_TO_HISTOGRAM

Copies a matrix to a histogram, with the specified range. The range is a required parameter for this procedure. The matrix is not affected by this operation.

The matrix should be 1-dimensional, if you give a matrix with a higher number of dimensions, then it will be unfolded.

Format:

CALL MATRIX_TO_HISTOGRAM(matrix, min, max, hist)

Example:

See HISTOGRAM_TO_MATRIX.

Section 12.98: MULTIPLY_MATRICES

(Not yet available)

Section 12.99: NEW_TRACK

This procedure (re)initialises cluster generation along the current track.

The track location and the clustering model should be specified on beforehand with the TRACK command.

Once NEW_TRACK has been called, cluster positions and cluster sizes can be obtained from GET_CLUSTER.

Format:

CALL NEW_TRACK

Example:

See GET_CLUSTER.

Section 12.100: PLOT_AREA

Plots an area that is delineated by the series of points given as argument. At least 3 points should be present in the argument list, but many more can be specified.

This procedure should only be called after a call to PLOT_FRAME.

Format:

CALL PLOT_AREA(x1, y1, x2, y2, ..., x_n, y_n [, area_type])

Example:

!rep times-roman character-height 0.075 ch-exp {1.2/8.5}
!rep box polyline-col background
!rep grid polyline-col background
!rep numbers text-col background
Call plot_frame(0,0,1.2,8.5,` `,` `,` `)
For i from 0 to 1.01 step 0.2 do
   For j from 0 to 1.01 step 0.2 do
      For k from 0 to 1.01 step 0.2 do
         !colour a red {i} green {j} blue {k}
         !rep wires fill-area-colour a fill-area-int-style solid
         Call plot_area(j,7*i+k, j,7*i+k+0.2, j+0.2,7*i+k+0.2, ...
              j+0.2,7*i+k, j,7*i+k, `WIRES`)
         Call plot_text(j+0.1,7*i+k+0.1, ...
              `R=`/string(i)/`, B=`/string(k)/`, G=`/string(j), ...
              `TIMES-ROMAN`,`CENTRE-HALF`)
      Enddo
   Enddo
Enddo
Call plot_end

This example illustrates how one can generate an RGB colour map. The colour A is repeatedly redefined in the loop and is used to modify also the representation of WIRES (one of the few pre- defined FILL-AREA representations). In each box with a given colour, the RGB value is plotted in TIMES-ROMAN. You may have to change this name depending on the graphics system that you are using.

12.100.1: area_type

The fill area representation that should be used, see REPRESENTATION for further information.

Section 12.101: PLOT_ARROW

Plots an arrow from one point to another.

The appearance of the arrow is affected by the representation used to draw the lines, and also by the settings of ARROW-TIP-ANGLE and ARROW-TIP-LENGTH.

Format:

CALL PLOT_ARROW(x0, x1, y0, y1 [, type])

Example:

Call plot_arrow(0,0,1,1,`function-1`)

12.101.1: type

A polyline representation with which the arrow is to be drawn.

[By default, SOLID]

Section 12.102: PLOT_COMMENT

Each plot frame has room for 4 comments, placed beneath the title: 2 on the left, 2 on the right, in both cases 2 lines.

Format:

CALL PLOT_COMMENT(place, text)

Example:

Call plot_frame(1,1,2,2,`x`,`y`,`Title`)
Call plot_comment(`up-left`,`Made on `/machine)
Call plot_comment('down-right`,`Time left: `/string(time_left))
Call plot_end

Will place a comment string on the left in the top row that reads (on a Vax) "Made on Vax".

12.102.1: place

The location should be given in the format:

`h-v`

Where

h = LEFT or RIGHT
v = UP or DOWN

12.102.2: text

The string to be plotted, this string can be up to 80 characters long but shorters strings are recommened so as to avoid overflow of the comment areas on the left into those on the right.

The comment string is plotted with representation COMMENT.

Section 12.103: PLOT_CONTOURS

Plots a matrix as a set of contours. The rendering of the contours and the set of options that is honoured, depends on the underlying graphics package.

Format:

CALL PLOT_CONTOURS(matrix [, n_contour [, options
     [, x-vector [, y_vector
     [, x-label [, y-label [, title ]]]]]]])

Example:

Call book_matrix(a,30,30)
Call plot_contours(a)

12.103.1: matrix

The matrix to be plotted.

This matrix should be 2-dimensional, and have a length of at least 2 in both directions. In the descriptions, the first index of the matrix will be written x, the second y.

The overall size of the matrix is limited to an amount that depends on the graphics system used (NAG or HIGZ) but is in both cases very large (around 10000 words at least).

12.103.2: n_contours

Number of contours to be drawn. If the ROUND option is used, this number is used as an indication only - the actual number will usually be larger.

The permissible range depends on the underlying graphics system, but usually covers [2,50].

12.103.3: options

A string containing options chosen from the following list. Most options are only applicable to one graphics system and are neglected on the others.

Option Effect Notes
POLAR Polar coordinate system Not with HIGZ
CARTESIAN Cartesian coordinate system -
ROUND Select nearest round numbers for contour heights -
LABEL Labels the contours Not with HIGZ
COLOUR Produces a colour map, or colours the contours Not with NAG
TYPE Distinguish the contours by line type Not with NAG

12.103.4: x-vector

Vector with the x-coordinates of the matrix.

Only the first and last element are used to set the scale along the x-axis of the plot.

If omitted, a range of [0, 1] is assumed.

12.103.5: y-vector

Vector with the y-coordinates of the matrix.

Only the first and last element are used to set the scale along the x-axis of the plot.

If omitted, a range of [0, 1] is assumed.

12.103.6: x-label

A string to be placed along the x-axis.

If omitted, the name of the global variable associated with x-vector is used, if there is one, otherwise the string 'x-axis' is taken.

12.103.7: y-label

A string to be placed along the y-axis.

If omitted, the name of the global variable associated with y-vector is used, if there is one, otherwise the string 'y-axis' is taken.

12.103.8: title

A string to be placed above the plot.

If omitted, the name of the global variable associated with matrix is used, if there is one, otherwise the title is left blank.

Section 12.104: PLOT_DRIFT_AREA

Plots, using the current projection, the part of the chamber that falls within the drift AREA. The plot frame is left open after the call for further additions. Once the plot is complete, PLOT_END should be called to close the plot frame.

Use PLOT_FIELD_AREA to plot the field area.

Format:

CALL PLOT_DRIFT_AREA([title])

Example:

area -1 -1 -2 1 1 2 view x+2*y+3*z=5
call plot_drift_area

Section 12.105: PLOT_DRIFT_LINE

Plots a projection of the current drift line. The coordinate axes should have been plotted before, for instance with PLOT_DRIFT_AREA. If the cell is in polar coordinates, then the drift line will also be plotted in such a coordinate frame.

The desired projection should be set with the AREA command.

Format:

CALL PLOT_DRIFT_LINE

Example:

Global x0=0.001
Global y0=0.028
Call plot_drift_area
For i From 1 To 50 Do
   Call drift_mc_electron(x0, y0, 0, status, time)
   Call plot_drift_line
Enddo
Call plot_end

This examples would make a plot of 50 Monte Carlo integrated drift lines all starting from the same point (x0,y0). One can of course exand the example by adding histograms of the drift time and the arrival point.

Section 12.106: PLOT_END

This procedure should be called once your plot is ready.

The procedure empties the graphics buffer to ensure that the plot is complete. If the WAIT-AFTER-PLOT option is in effect, a prompt is displayed before proceeding with the next plot.

Yoy may optionally specify a string as argument. The string will be entered in the list of plots that is printed at the end of the job output.

Format:

CALL PLOT_END( [string] )

Section 12.107: PLOT_ERROR_BAND

Plots an error band, an area usually filled with a light colour, to indicate the uncertainty in a calculated curve, for instance due to uncertainty in the parameters used to compute the curve.

This call would typically be combined with PLOT_ERROR_BAR.

Format:

CALL PLOT_ERROR_BAND(x, y1, y2)

Example:

Call plot_frame(0,0,5,5,`x`,`y`,`title`)
Global x1=(row(51)-1)/10
Global y1=1+x1**2/10
Global y2=y1*1.2
Call plot_error_band(x1,y1,y2)
Call plot_end

First, we create a vector X1 that contains 50 numbers regularly spaced between 0 and 5. Using X1, an error band between Y1 and Y2 is constructed with 20 % uncertainty.

12.107.1: vectors

Each of the 3 argument should be a 1-dimensional Matrix. All vectors should have the same length.

The arguments should contain respectively the x-coordinate, the lower y of the band for this x and the higher y bound of the band for this x.

The minimum permissible length of the vectors is 2, the maximum depends on the compilation parameter MXLIST (usually set either to 200 or to 1000 depending on the Patchy flag LONGLIST) and is equal to (MXLIST-1)/2.

The vectors should be 1-dimensional; matrices with another number of dimensions are unfolded before use.

This procedure does not accept scalar arguments.

12.107.2: representations

The area is filled with a colour according to fill area representation ERROR-BAND, and then surrounded by a curve according to polyline representation ERROR-BAND.

Filling the area with yellow, gives good results when the plot is included in a black and white PostScript document: the area then appears as light grey.

Section 12.108: PLOT_ERROR_BAR

Plots a series of error bars. Only the (x,y) coordinates of the centre must be present, but one can specify both symmetric and asymmetric error bars. Optionally, one may also provide the size and appearance of the error bar.

Format:

CALL PLOT_ERROR_BAR(x, y [, ex-, ey- [, ex+, ey+]] [, type [, size]])

Example:

read-vector x y ex1 ey1 ex2 ey2
1 1 0.5 0.5 0.25 0.25
2 2 0.5 0.25 0.5 0.25

call plot_frame(0,0,5,5,`x`,`y`,`title`) call plot_error_bars(x,y,ex1,ey1,`circle`,0.02) call plot_error_bar(x+2,y,ex1,ey1,ex2,ey2,`square`) call plot_end

12.108.1: centre

Each of the coordinates of the centre (x,y) of the error bar can be of type Number or of type Matrix.

The 2 do not need to have the same type: if at least one of the coordinates of the centre or one of the error components is a Matrix, then all arguments of type Number are expanded to type Matrix.

All arguments of type Matrix must have the same length, but they do not have to be 1-dimensional.

[The location of the centre is a mandatory argument for which no default value is provided.]

12.108.2: errors

One can either specify only one set of error bars, in which case the error bar will be symmetric, or two sets, in which case the first set is taken to be the left resp. lower error whereas the second set becomes the right resp. upper error.

All components of the error bar can be of type Number or of type Matrix.

The components do not need to have the same type: if at least one of the coordinates of the centre or one of the error components is a Matrix, then all arguments of type Number are expanded to type Matrix.

All arguments of type Matrix must have the same length, but they do not have to be 1-dimensional.

[Error components that are missing default to 0. The error components may be omitted altogether.]

12.108.3: type

The following error bar types are currently available:

CIRCLE
A filled circle and a plus indicating the left, right, up and down errors.
CROSS
Like CIRCLE, but with a cross replacing the circle. This error bar is not filled.
DAVID
David's star, like a 6-STAR but fatter.
ELLIPSE
Each quadrant is a filled ellipse with half axes corresponding to the error components.
HEXAGON
Like CIRCLE, but using a hexagon instead of a circle.
PLUS
Only a + sign showing the 4 error components. This error bar is not filled.
4-STAR
A star with 4 points, in other respects like CIRCLE.
6-STAR
A star with 6 points, in other respects like CIRCLE.
8-STAR
A star with 8 points, in other respects like CIRCLE.
10-STAR
A star with 10 points, in other respects like CIRCLE.
SQUARE
Like CIRCLE, but using a square box instead of a circle.
TRIANGLE
Like CIRCLE, but using a triangle instead, 4 models can be used: LEFT-TRIANGLE, UP-TRIANGLE, DOWN-TRIANGLE and RIGHT-TRIANGLE, for triangles with a corner pointing to the left, up, down and to the right respectively.

More error bar types can be added on request.

[The default error bar type is CIRCLE.]

12.108.4: representations

All error bars contain line segments, which are drawn according to the polyline representation ERROR-BAR. Most error bars have in addition an area which is filled according to the fill area representation of ERROR-BAR and then outlined with the polyline representation.

By selecting a fill area interior style of HOLLOW one gets "empty" markers, while SOLID gives "filled" markers of a chosen colour. The colour of "empty" markers is determined by the colour of the polyline representation rather than the fill area representation since the polyline is drawn last.

12.108.5: size

The radius of the circle (type CIRCLE), the half-size of the cross and the box (types CROSS and SQUARE), the distance from the centre to the tips of the STARs, TRIANGLEs and HEXAGON. The size is also used for the "serifs" at the end of the + sign that indicates the error bars for all types with the exception of ELLIPSE.

The size is measured in the Normalised Device Coordinates, i.e. the coordinate system in which the plot has a range of (0,0) to (1,1).

[The default size is 1 % of the NDC frame.]

Section 12.109: PLOT_FIELD_AREA

Plots, using the current projection, the part of the chamber that falls within the field AREA. The plot frame is left open after the call for further additions. Once the plot is complete, PLOT_END should be called to close the plot frame.

Use PLOT_DRIFT_AREA to plot the drift area.

Format:

CALL PLOT_FIELD_AREA([title])

Example:

area -1 -1 -2 1 1 2 view x+2*y+3*z=5 cut
call plot_field_area

Section 12.110: PLOT_FRAME

Draws a set of Cartesian coordinate axes with labels.

Call PLOT_END to end the plot.

Format:

CALL PLOT_FRAME(xmin, ymin, xmax, ymax ...
     [, x_label [, y_label [, title]]])

12.110.1: xmin

The lower x limit of the frame.

This argument is should be a variable, constant or expression that evaluates to a Number.

[A mandatory parameter, no default.]

12.110.2: ymin

The lower y limit of the frame.

This argument is should be a variable, constant or expression that evaluates to a Number.

[A mandatory parameter, no default.]

12.110.3: xmax

The upper x limit of the frame.

This argument is should be a variable, constant or expression that evaluates to a Number.

[A mandatory parameter, no default.]

12.110.4: ymax

The upper y limit of the frame.

This argument is should be a variable, constant or expression that evaluates to a Number.

[A mandatory parameter, no default.]

12.110.5: x_label

The label to be placed along the x-axis.

This label will be shown using the text representation LABELS.

This argument is should be a variable, constant or expression that evaluates to a String.

[By default: `x`]

12.110.6: y_label

The label to be placed along the y-axis.

This label will be shown using the text representation LABELS.

This argument is should be a variable, constant or expression that evaluates to a String.

[By default: `y`]

12.110.7: title

The label to be placed along the top of the screen.

This label will be shown using the text representation TITLE.

This argument is should be a variable, constant or expression that evaluates to a String.

[By default left empty.]

Section 12.111: PLOT_GRAPH

Draws a graph of one vector against another vector.

The scales are chosen automatically on the basis of the range of the vectors and axes are plotted accordingly. The procedure PLOT_FRAME should not be called prior to PLOT_GRAPH.

The graph is left open after the call and further elements can be added to the plot. PLOT_END should be called to end the plot.

Format:

CALL PLOT_GRAPH(x_vector, y_vector [, x_label [, y_label, [,title]]])

Example:

Global n=20
Call book_matrix(x,n)
Call book_matrix(y,n)
Global m=3
For i From 1 To n Do
   Global x[i]=cos(m*2*pi*i/(n-1))
   Global y[i]=sin(m*2*pi*i/(n-1))
Enddo
Call plot_graph(x,y)
!rep circle polymarker-colour green
Call plot_marker(x,y,`circle`)
Call plot_end

The plot in this example is a kind of star pattern. The axis labels are omitted and will therefore be replaced by X and Y, the names of the variables that have been plotted.

12.111.1: vectors

The arguments x_vector and y_vector should both be of type Matrix, and they should have the same total size. The size should be at least 2.

If the arguments are not 1-dimensional, then they are unraveled. Use the PLOT_CONTOURS and PLOT_SURFACE procedures if you wish to plot 2-dimensional matrices.

[These arguments are mandatory. No default is supplied.]

12.111.2: labels

The x- and y-axis labels should be specified as String variables.

If they are omitted, they will be replaced by the name of the global variable that corresponds to x_vector and y_vector, if these vectors are simple variables. Otherwise, they are set to `x` and `y`.

To leave the label field blank, you need to specify ` ` as label.

12.111.3: title

The title is a String variable.

[The title is left blank if omitted.]

12.111.4: representations

The curve is drawn with polyline representation FUNCTION-1.

The labels are shown using the text representation LABELS.

The title is shown using the text representation TITLE.

Section 12.112: PLOT_HISTOGRAM

Plots an histogram with the specified label along the x-axis and with the given title.

Calling this procedure does not interfere with filling of the histogram but an autotange histogram will only be shown if the range has been set.

This procedure, by default, plots the histogram in a frame with dimensions adjusted to the the histogram. If you wish to control the axes yourself, then use the PLOT_FRAME procedure to plot the axes and use the NOFRAME option of PLOT_HISTOGRAM. This option can also be used to superimpose several histograms.

The procedure leaves the plot open for further additions, the PLOT_END procedure should be called when the plot is complete.

Format:

CALL PLOT_HISTOGRAM(histogram [, x_title [, title [, options]]])

Example:

!col red red 1 blue 0 green 0
!col blue red 0 blue 1 green 0
!col green red 0 blue 0 green 1
!rep function-1 polyline-colour green
Call hplot(all_1,`Time [microsec]`,`Arrival time spectrum`)
!rep function-1 polyline-colour red
Call hplot(sel_1,` `,` `,`noframe`)
!rep function-1 polyline-colour blue
Call hplot(sel_2,` `,` `,`noframe`)
Call plot_end

In this example, the overall arrival time spectrum is plotted together with the arrival time distributions for a number of selected electron. The 3 histograms are distinghuised by colour.

12.112.1: histogram

The Histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or to GET_HISTOGRAM.

[This argument is mandatory. No default is supplied.]

12.112.2: x_label

The String that should appear along the horizontal axis.

The label is shown using the text representation LABELS.

[By default, this will be `Coordinate`]

12.112.3: title

This should be a String that contains the title that you want to appear at the top of the plot.

The title is shown using the text representation TITLE.

If omitted or if specified as `*`, the name of the global variable associated with the histogram will be used as title. If the histogram is the result of an operation, the string `Title` will be used.

12.112.4: options

A string which can contain the following options:

Option Effect Notes
FRAME Plots the histogram with a frame Default
NOFRAME Reuses the existing frame Not default

[Default: True.]

12.112.5: representations

The histogram is drawn using the FUNCTION-1 representation, as illustrated in the example.

To superimpose several histograms, one therefore has to change this representation between calls to PLOT_HISTOGRAM.

Section 12.113: PLOT_LINE

Connects a series of points either by straight line segments, or by a cubic spline. Either two 1-dimensional matrices of equal length or at least two sets of (x, y) pairs should be given as argument. The two formats can not be mixed.

This procedure should only be called after a call to PLOT_FRAME.

If you wish to make a graph, then using the PLOT_GRAPH procedure is probably simpler.

Formats:

CALL PLOT_LINE(x1, y1, x2, y2, ..., x_n, y_n [, option])
CALL PLOT_LINE(x_vector, y_vector [, option])

Example 1:

!col cyan red 0.8 green 1 blue 1
!rep function-4 polyline-colour cyan
call plot_line(0,0, 1,0, 0,1, 1,1, 0,0, `function-4`)

A colour called CYAN is defined, this colour is used to modify the appearance of FUNCTION-4 polylines. This polyline representation is used to produce a figure on the screen.

Example 2:

call book_matrix(time,20)
read-vector time
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

Call plot_frame(0,-1.1,21,1.1,`Time`,`Sinus`,`A curve`) Call plot_line(time,sin(time/3),`FUNCTION-1`) Call plot_end

This example shows how one can plot a simple curve: the vector TIME is declared and initialised with the numbers 1 through 20. This is actually not necessary since a matrix has this contents when it is created. Then, a plot is made of TIME vs sin(TIME/3). A slightly simpler way to achieve this result would have been to use PLOT_GRAPH.

12.113.1: option

The option string is used to indicate which polyline representation is to be used, and also whether the line should be smoothened or not.

The following polyline representations can be used: SOLID, DASHED, DOTTED, DASH-DOTTED, FUNCTION-1, FUNCTION-2, FUNCTION-3, FUNCTION-4, FUNCTION-5, FUNCTION-6 and FUNCTION-7.

To obtain smoothened lines, add the option SMOOTH. Line smoothing is performed with cubic splines. Cubic splines tend to oscillate if there are jumps in the data points.

Default: representation SOLID and no smoothing.

Section 12.114: PLOT_MARKER

Plots a series of markers. This procedure should only be called after a call to PLOT_FRAME. This procedure can be used both with a series of (x, y) pairs as argument, and with a pair of 1-dimensional matrices.

Formats:

CALL PLOT_MARKER(x1, y1, x2, y2, x3, y3, ... [, marker_type])
CALL PLOT_MARKER(x_vector, y_vector [, marker_type])

Example:

Global n=50
Call book_matrix(x,n)
Call book_matrix(y,n)
For i From 1 To n Do
   Global x[i]=i
   Global y[i]=rnd_gauss
Enddo
Call plot_frame(number(x[1]),-3,number(x[n]),3,...
   `Time`,`Random`,`Scattered points`)
!rep circle polymarker-colour orange
Call plot_marker(x,y,`CIRCLE`)
Call plot_end

First, 2 matrices are created. One is filled with the numbers 1-n, the other with Gaussian distributed random numbers. Then, the pairs are plotted as orange circles.

12.114.1: marker_type

The kind of marker to be used. This is a string that refers to the graphics representation tables, see REPRESENTATION for further information.

Examples in the standard graphics representation tables are CROSS, DOT, PLUS and CIRCLE.

Please note that several more marker types are available with the PLOT_ERROR_BAR procedure. By giving errors of size zero to the latter procedure, or by omitting the error arguments, one gets the same appearance as with PLOT_MARKER.

Section 12.115: PLOT_START

Switches to graphics output.

You only need to call this procedure if you wish to set window, viewport and normalisation transformation manually. All plot routines do this automatically.

Format:

CALL PLOT_START

Section 12.116: PLOT_SURFACE

Plots a 3-dimensional surface. The precise way the surface is rendered and the set of options that is honoured, depends on the underlying graphics package.

Format:

CALL PLOT_SURFACE(matrix ...
     [, theta [, phi ...
     [, x-vector [, y_vector ...
     [, x-label [, y-label [, title]]]]]]])

Example:

Call book_matrix(a,30,30)
Call plot_surface(a)

12.116.1: matrix

The matrix to be plotted.

This matrix should be 2-dimensional, and have a length of at least 2 in both directions. In the descriptions, the first index of the matrix will be written x, the second y.

The overall size of the matrix is limited to an amount that depends on the graphics system used (NAG or HIGZ) but is in both cases very large (around 10000 words at least).

12.116.2: theta

Polar viewing angle, in degrees.

Default: 60 degrees.

12.116.3: phi

Azimuthal viewing angle, in degrees.

Default: 60 degrees.

12.116.4: x-vector

Vector with the x-coordinates of the matrix.

Only the first and last element are used to set the scale along the x-axis of the plot.

Whether a scale is actually plotted along the axes depends on the graphics system that is used.

If omitted, a range of [0, 1] is assumed.

12.116.5: y-vector

Vector with the y-coordinates of the matrix.

Only the first and last element are used to set the scale along the x-axis of the plot.

Whether a scale is actually plotted along the axes depends on the graphics system that is used.

If omitted, a range of [0, 1] is assumed.

12.116.6: x-label

A string to be placed along the x-axis.

Whether a label is actually plotted along the axes depends on the graphics system that is used.

If omitted, the name of the global variable associated with x-vector is used, if there is one, otherwise the string 'x-axis' is taken.

12.116.7: y-label

A string to be placed along the y-axis.

Whether a label is actually plotted along the axes depends on the graphics system that is used.

If omitted, the name of the global variable associated with y-vector is used, if there is one, otherwise the string 'y-axis' is taken.

12.116.8: title

A string to be placed above the plot.

If omitted, the name of the global variable associated with matrix is used, if there is one, otherwise the title is left blank.

Section 12.117: PLOT_TEXT

Plots a string in the frame that should previously have been opened with PLOT_FRAME.

On some graphics systems (provided that the graphics option DISPLAY-CONTROL-CHARACTERS is on, this is by default the case) special symbols are available through the following mechanisms:

  1. In units (recognised by the squared brackets that enclose them), the strings 'cm2', 'cm3', 'micron', 'microsec' and 'microamp', are shown in their usual way (superscript 2 for 'cm2', Greek mu for 'micron' etc.
  2. Some particle names (e.g. electron-, mu+, tau-) as well as some chemical compounds (e.g. CO2, C3H8) are shown the way they are normally printed with superscripts to indicate the charge and subscripts showing the number of atoms per molecule.
  3. Greek letters, diacritics and ligatures are accessible as SGML entities, e.g. &Ksi; &eacute; and &szlig; (for a list, see entities) For a list of SGML entities, see for instance: http://home.eclipse.net/~lionheart/html/entities.html

Format:

CALL PLOT_TEXT(x, y, string [, font [, alignment [, orientation]]])

Example:

Call plot_text(0.5, 0.5, `Some text`, `TIMES-ROMAN`, `LEFT-BASE`)

The string "Some text" will be plotted horizontally with its lower left corner at (0.5,0.5).

12.117.1: font

The font can be any of the text representations that are currently defined. These include representations that are reserved for elements of graphs (such as TITLE).

For convenience, a few text representations are been provided that are not used by the program and that can therefore be modified at will. These include some commonly used fonts: Times Roman (TIMES-ROMAN) and Prestige Elite (PRESTIGE), but also Greek characters (GREEK), gothic characters (GOTHIC) and the italics for most of these (e.g. GOTHIC-ITALIC). The precise choice of these fonts depends on the graphics system you are using.

The font should be specified with a variable of the type String.

[By default, the current text representation is used.]

12.117.2: alignment

The alignment determines which point of the text string has to be placed at the coordinate (x,y). The alignment should be specified as a String in the format `h-v` where h is one of the horizontal and v one of the vertical alignments.

[By default, the alignment is assumed to be `NORMAL-NORMAL`.]

12.117.3: orientation

Text is normally plotted horizontally, but you can ask to have the text plotted at an angle by giving this optional argument.

The orientation is a Number and should be specified in degrees.

[By default: 0 degrees.]

Section 12.118: PLOT_TRACK

This procedure plots a projection of the track according to the current settings of the AREA command of the drift section. The PLOT_DRIFT_AREA procedure should be called before invoking PLOT_TRACK and PLOT_END should be called once the plot is complete.

For most track models, this will simply be a line from the starting point of the track to the end point.

To plot a track that has been generated with Heed, you must first call NEW_TRACK and then at least once GET_CLUSTER, even if you don't use the data returned by the latter procedure.

Format:

CALL PLOT_TRACK

Example:

For i From 1 To nstat Do
   If 'i=10*entier(i/10)' Then Say "Iteration {i}"
   Call plot_drift_area
   Call new_track
   Do
      Call get_cluster(xcls,ycls,zcls,npair,done)
      If done Then
         Leave
      Else
         For n From 1 To npair Do
           Call drift_mc_electron(xcls, ycls, zcls, status, time)
           Call plot_drift_line
         Enddo
      Endif
   Enddo
   Call plot_track
   Call plot_end
Enddo

(This example shows how one can make the same kind of plot as DRIFT TRACK by calling procedures.)

12.118.1: representations

The representations used for showing the track are explained under TRACK.

Section 12.119: POLAR_TO_CARTESIAN

Converts polar (r,phi) coordinates to Cartesian (x,y) coordinates.

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name PTC is also accepted.

Format:

CALL POLAR_TO_CARTESIAN(r,phi,x,y)

Section 12.120: POLAR_TO_INTERNAL

Converts polar (r,phi) coordinates to (rho,phi') coordinates that are used internally when dealing with cells in polar coordinares. The internal coordinates a conformal mapping of (x,y) coordinates.

If the condition r>0 is not met, then the global variable OK is set to False, otherwise to True.

Internal coordinates are related to polar coordinates by:

     rho  = log(r)        [dimension not defined]
     phi' = pi*phi/180    [radians]

The input arguments of this procedure can be either of type Number or of type Matrix. If the input type is Matrix, then the two input matrices must have the same total number of elements. The output matrices will have the same structure as the first input matrix.

The abbreviated procedure name PTR is also accepted.

Format:

CALL POLAR_TO_INTERNAL(r,phi,rho,phi')

Section 12.121: PREPARE_RND_FUNCTION

Establishes the expression according to which the RND_FUNCTION function will generate random numbers.

RND_FUNCTION should be used only after PREPARE_RND_FUNCTION has been called.

If the distribution to be generated originates from an histogram, then the RND_HISTOGRAM function should be used.

RND_FUNCTION is based on the <A HREF="FUNLUX">http://wwwinfo.cern.ch/asdoc/shortwrupsdir/v152/top.html">FUNLUX routine from the CERN program library.

Format:

CALL PREPARE_RND_FUNCTION(function, min, max)

Example:

Call book_histogram(hist,100,-1,2)
Call prepare_rnd_function(`1.5+sin(6*x)`,-1,2)
For i From 1 To 10000 Do
   Call fill_histogram(hist,rnd_function)
Enddo
Call plot_histogram(hist)
Call plot_end

12.121.1: function

This argument, of type String contains the function according to which random numbers are to be generated.

The function should use X as variable. If the function does not depend on X, then RND_UNIFORM is a more appropriate random number generator to use.

The function is allowed to be zero at individual points, but must not be negative anywhere over the specified range.

[No default, this is a mandatory argument.]

12.121.2: range

With xmin and xmax, you indicate the smallest and largest random number that RND_FUNCTION will generate.

Both are Numbers.

[No default, these arguments are mandatory.]

Section 12.122: PRINT

The PRINT procedure simply prints the arguments it is given.

Format:

CALL PRINT(any number of arguments)

Section 12.123: PRINT_HISTOGRAM

This procedure prints the histogram called "reference". Calling this procedure does not interfere with filling of the histogram but an histogram will only be printed if the range has been set (applicable for auto range histograms only).

Format:

CALL PRINT_HISTOGRAM(reference [, x-title [, title]])

12.123.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or to GET_HISTOGRAM.

You may also supply an expression that evaluates to an Histogram.

Section 12.124: PRINT_MATRIX

Prints one or more variables of type Matrix.

Format:

CALL PRINT_MATRIX(matrix_1, matrix2, ...)

Example:

Call book_matrix(a,2,3)
Call print_matrix(a)

A matrix called A is booked, and is then immediately printed. This shows how matrices are initialised.

Section 12.125: PROJECT_LINE

Projects a line onto the viewing plane that has been chosen with the AREA statement.

The procedure should be only be called after a plot frame has been opened, e.g. with PLOT_DRIFT_AREA.

Format:

CALL PROJECT_LINE(vector_1, vector_2, vector_3)

Example:

&DRIFT
Global n=20
Global nmax=5000
Call delete_matrices
Call book_matrix(xbuf,nmax)
Call book_matrix(ybuf,nmax)
Call book_matrix(zbuf,nmax)
Call book_matrix(nbuf,n)
Call book_matrix(ibuf,n)
Global i0=1
For i From 1 Step 1 To n Do
   Global y=4*(i-1)/(n-1)-0.5
   Call drift_electron_3(-0.5,y,1.5,status,time)
   Call get_drift_line(xd,yd,zd,t)
   Call drift_info(`steps`,nd)
   If i0+nd>nmax Then
      Say "Buffer overflow, reducing n to {i-1}."
      Global n=i-1
      Leave
   Endif
   Call book_matrix(ind,nd)
   Global xbuf[i0+ind]=xd
   Global ybuf[i0+ind]=yd
   Global zbuf[i0+ind]=zd
   Global ibuf[i]=i0
   Global nbuf[i]=nd
   Global i0=i0+nd
Enddo

Do Global a Global b Global c Say "Please enter the normal vector of the viewing plane:" Parse terminal a b c If 'type(a)#`Number`' Then Leave area -1.5 -1.5 -1.5 4.5 4.5 4.5 view {a}*x+{b}*y+{c}*z=0 3d Call plot_drift_area For i From 1 Step 1 To n Do Call book_matrix(ind,nbuf[i]) Global i0=number(ibuf[i]) Global xd=xbuf[i0+ind] Global yd=ybuf[i0+ind] Global zd=zbuf[i0+ind] Call project_line(xd,yd,zd,`e-drift-line`) Enddo Call plot_end Enddo

(This shows how one can compute a set of drift lines and then look at them from various angles - probably more interesting for drift lines computed with the MC procedures, where the method ensures that the drift lines are the same in all projections.)

12.125.1: vectors

The line that has to be plotted should be stored in a set of 3 vectors of equal length, in the range [2,MXLIST].

These arguments should be of type Matrix.

Section 12.126: PROJECT_MARKERS

Projects a set of markers onto the viewing plane that has been chosen with the AREA statement.

The procedure should be only be called after a plot frame has been opened, e.g. with PLOT_DRIFT_AREA.

Format:

CALL PROJECT_MARKERS(vector_1, vector_2, vector_3)

Example:


12.126.1: vectors

The markers that have to be plotted should be stored in a set of 3 vectors of equal length, in the range [1,MXLIST].

These arguments should be of type Matrix.

Section 12.127: REBIN_HISTOGRAM

Groups bins of an histogram.

This procedure does not change the range of the histogram. To reduce the range, use CUT_HISTOGRAM.

This procedure may be called while filling is in progress, but should not be called for AUTOSCALE histograms before the range has been established.

If the calculation fails (invalid arguments etc), then the global variable OK will be set to False, otherwise to True.

Format:

CALL REBIN_HISTOGRAM(ref_in, ngroup, ref_out)

Example:

Call book_histogram(gauss,200,-10,10)
For i From 1 To 500 Do
   Call fill_histogram(gauss,rnd_gauss)
Enddo
Call plot_histogram(gauss)
Call plot_end

Call rebin_histogram(gauss,5,new) Call hplot(new) Call plot_end

An histogram is filled with fine binning, and then rebinned for better readability.

12.127.1: ref_in

Should contain on entry an Histogram of which you wish to group the bins.

This histogram is not modified by the procedure.

[No default, this is a mandatory argument.]

12.127.2: ngroup

The number of bins to be grouped into a single bin of the output histogram.

If ngroup does not divide the number of bins in the input histogram, the incomplete set of bins at the upper end of the histogram range will be added to the overflow.

This argument should be an integer Number larger than 0 and smaller than, or equal to, the number of bins in the input histogram.

[No default, this is a mandatory argument.]

12.127.3: ref_out

Contains, on successful completion of the procedure, the rebinned histogram.

The value of this parameter on entry is not used and is lost after the procedure call.

This argument must be modifiable, i.e. this must be a simple variable name and not an expression.

Section 12.128: RESET_HISTOGRAM

Resets the contents of one or more histograms.

The range, if set, and number of bins is not touched.

If the range has not been established for an histogram of the AUTOSCALE type, then the range will eventually be computed from only those entries that were entered after the call to RESET_HISTOGRAM. In case the range of such an histogram has already been established, and you wish the histogram to regain its auto scale status, then you should book the histogram anew with BOOK_HISTOGRAM.

If arguments are omitted altogether, then all histograms currently stored as global variables are reset.

Format:

CALL RESET_HISTOGRAM(hist1, hist2, ...)

Section 12.129: RESHAPE_MATRIX

RESHAPE_MATRIX is one of two procedures which modify the shape of existing matrices.

RESHAPE_MATRIX first unpacks the matrix in a string of numbers, then fills these numbers in a new matrix of the specified dimensions. This procedure can therefore be used to change the number of dimensions of a matrix. If you wish to truncate or expand a matrix keeping the elements in place, then use ADJUST_MATRIX.

If the new matrix contains more elements than the old matrix did, then the remaining elements are assigned the value PAD (the last argument of the procedure).

If the new matrix is smaller than the old matrix, then the remaining elements are simply lost.

Format:

CALL RESHAPE_MATRIX(matrix, size_1, size_2, ..., size_n, pad)

Example:

(assume that B is a 3x4 matrix)
Global a=b[2;]
Call reshape_matrix(b,4,0.0)

The 2nd row of the matrix B is extracted with the Global statement. At this point, A is a 1x4 matrix. In order to reduce A to a 4-matrix, RESHAPE_MATRIX is used. The PAD argument is compulsory, but its value is not used here.

12.129.1: matrix

The Matrix to be acted upon.

The reshaped matrix replaces the matrix given as input. This argument should therefore be modifiable, i.e. a simple name of a matrix, not an expression.

[This is a mandatory argument, no default is supplied.]

12.129.2: size

A set of Numbers, each of which specifies the length of the reshaped matrix along a dimension.

These arguments should in principle be integers, if they are not, then they are rounded to the nearest integer.

The number of dimensions of the reshaped matrix is equal to the number of size arguments.

[These are mandatory arguments, there must at least be one of them and there can be at most MXMDIM, usually 10, dimensions. No defaults are supplied.]

12.129.3: pad

A Number used to fill elements of the matrix that did not exist before the matrix was reshaped.

[This argument is mandatory, even if the reshaped matrix is smaller than the original matrix. No default is supplied.]

Section 12.130: RND_MULTIPLICATION

Performs a Monte Carlo simulation of the number of electrons created and absorbed along the current electron drift line. Unlike AVALANCHE, this procedure does not perform a spatial simulation of an avalanche - the avalanche in this procedure develops on the current drift path, and does not spread laterally. In return, the procedure is much faster.

For each step of the drift line, the procedure uses the Townsend coefficients to compute the probability that an electron is produced, and the attachment coefficients to compute the probability that an electron is lost.

According to these probabilities, electrons are created or absorbed at each step.

The procedure can be applied both to drift lines computed with the Runge_Kutta_Fehlberg and with Monte_Carlo methods. In the latter case, the use of the PROJECTED-PATH-INTEGRATION integration parameter is recommended in order to avoid a step size dependence in the multiplication.

The procedure can be called repeatedly for the same drift line.

Format:

CALL RND_MULTIPLICATION(ne, [ni])

Example:

&DRIFT
int-par projected m-c-dist-int 0.0002
Call drift_electron_3(0.15,0,0,status,time,diff,aval,att)
Say "Mean RKF aval: {aval}, loss: {att}, product: {aval*att}, status {status}"
Call book_histogram(hist,50,0,2*aval*att)
Global nrndm=500
For i From 1 To nrndm Do
   Call drift_mc_electron(0.15,0,0)
   Call rnd_multiplication(a)
   Call fill_histogram(hist,a)
   If 'entier(i/100)*100=i' Then
      !opt log-y
      Call plot_histogram(hist)
      Call plot_end
   Endif
Enddo

Section 12.131: SET_AREA_ATTRIBUTES

Selects a given representation for the next fill area.

Calling this procedure is useful only if you draw the next fill area with GKS_AREA, most other procedures set the attributes before plotting.

Format:

CALL SET_AREA_ATTRIBUTES(representation)

12.131.1: representation

One of the existing fill area representations.

This argument is a text string.

[No default, this is a mandatory parameter.]

Section 12.132: SET_LINE_ATTRIBUTES

Selects a given representation for the next polyline.

Calling this procedure is useful only if you draw the next polyline with GKS_POLYLINE, most other procedures set the attributes before plotting.

Format:

CALL SET_LINE_ATTRIBUTES(representation)

12.132.1: representation

One of the existing polyline representations.

This argument is a text string.

[No default, this is a mandatory parameter.]

Section 12.133: SET_MARKER_ATTRIBUTES

Selects a given representation for the next polymarker.

Calling this procedure is useful only if you draw the next polymarker with GKS_POLYMARKER, most other procedures set the attributes before plotting.

Format:

CALL SET_MARKER_ATTRIBUTES(representation)

12.133.1: representation

One of the existing polymarker representations.

This argument is a text string.

[No default, this is a mandatory parameter.]

Section 12.134: SET_TEXT_ATTRIBUTES

Selects a given representation for the next text.

Calling this procedure is useful only if you draw the next text with GKS_TEXT, most other procedures set the attributes before plotting.

Format:

CALL SET_TEXT_ATTRIBUTES(representation)

12.134.1: representation

One of the existing text representations.

This argument is a text string.

[No default, this is a mandatory parameter.]

Section 12.135: SOLVE_EQUATION

(Not yet available)

Section 12.136: STORE_SIGNAL

Copies a 1-dimensional matrix to a signal.

The vectors to be stored must have the same length as the other signals currently stored. The time vector can not be changed with this command.

Format:

CALL STORE_SIGNAL(electrode, direct [, cross-induced])

12.136.1: electrode

This is the number of a read-out group. Signals are summed over the elements that compose a read-out group - signals for the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[No default, this is a mandatory parameter.]

Section 12.137: STORE_SUBMATRIX

Stores a matrix in selected areas of a (larger) matrix.

Both matrices should exist prior to the call and the size of the selected area should match the size of the matrix which is to be stored.

This procedure is used to process array indexing on the left hand side of Global statements. The procedure is not intended to be called by the user. Using the Global statement is much simpler.

Format:

CALL STORE_SUBMATRIX(ndim, nsel_1, nsel_2, ..., isel_1_1,
     isel_1_2, ..., isel_2_1, isel_2_2, ... , isel_n_1, isel_n_2,
     ref_submatrix, ref_matrix)

Section 12.138: STRING_DELETE

Returns the string with the part between characters istart and iend deleted.

Format:

CALL STRING_DELETE(string, istart, iend, output)

Example:

Call string_delete(`abc def ghi`,4,8,out)

12.138.1: string

A variable or an expression that evaluates to a String.

Not modified by the procedure.

12.138.2: istart

A Number that indicates the first character to be deleted.

Section 12.139: STRING_INDEX

Returns the starting position of a substring in a string. Returns 0 if the substring is not found within the string.

Format:

CALL STRING_INDEX(string, substring, index)

Example:

Call string_index(`abc def`,`def`,pos)

Section 12.140: STRING_LENGTH

Returns the number of characters in a string.

Format:

CALL STRING_LENGTH(string, length)

Example:

CALL STRING_LENGTH(`abc`,n)
Say "Length of string is {n} characters."

Section 12.141: STRING_LOWER

Converts a string to lower case.

Format:

CALL STRING_LOWER(string)

Example:

Global str=`ABCDEF`
Call string_lower(str)
Say {str}

Section 12.142: STRING_MATCH

Tells whether a string matches a given pattern. Patterns consist of a series of hyphen separated strings in each of which one can place a hash sign (#) to indicate the point up to which this particular piece of the string can be abbreviated.

Format:

CALL STRING_MATCH(string, pattern, match)

Example:

Call string_match(`abc-def`,`ab#cdef-de#fghi-#ghijkl`,match)
If match Then
   Say "The strings match."
Else
   Say "The strings do not match."
Endif

Section 12.143: STRING_PORTION

Returns the part of the string that begins at character istart and ends at character iend. If the ending position precedes the starting position, the string portion that is returned is reversed.

Format:

CALL STRING_PORTION(string, istart, iend, portion)

Example:

Call string_portion(`abc def ghi`,5,7,out)

Section 12.144: STRING_UPPER

Converts a string to upper case.

Format:

CALL STRING_UPPER(string)

Example:

Global str=`abcdef`
Call string_upper(str)
Say {str}

Section 12.145: STRING_WORD

Returns the i'th blank, comma or equal sign delimited word from a string.

Format:

CALL STRING_WORD(string, i, word)

Example:

Global str=`abc def ghi`
Call string_words(str,n)
Say "The string contains {n} words."
For i From 1 To n Do
    Call string_word(str,i,out)
    Say "Word {i} is {out}."
Enddo

Section 12.146: STRING_WORDS

Returns the number of words in a string. Words are delimited by blanks, commas, colons and equal signs.

Format:

CALL STRING_WORDS(string, n)

Example:

See STRING_WORD

Section 12.147: TIME_LOGGING

Registers the CPU time consumed since the previous time this procedure was called, and stores it together with a string that serves as annotation.

The entire buffer is printed out at job completion.

Format:

CALL TIME_LOGGING( string )

Example:

Call time_logging(`Until timing test`)
Global x0=0.5
Global y0=1.5
Call plot_drift_area
For i From 1 To 100 Do
   Call drift_mc_electron(x0, y0, 0, status, time)
   Call plot_drift)line
Enddo
Call time_logging(`MC drifting`)

The TIME_LOGGING routine is called a first time to ensure that in the end we will record only the time spent in MC drifting will be recorded.

Section 12.148: TOWNSEND

Returns the Townsend coefficient, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the Townsend coefficient is returned in 1/cm.

Format:

CALL TOWNSEND(ex, ey, ez, townsend)

Section 12.149: THRESHOLD_CROSSING

Returns the times at which a signal crosses a given threshold. If both direct and cross-induced signals are available, then the threshold crossings are computed for the sum of both.

Format:

CALL THRESHOLD(electrode,threshold,option,n,t1 [,t2 [,t3 ...]])

Example:

For i From 1 To 100 Do
   signal
   conv-sig range 0 1000 ...
      transfer-function (5*t/0.01)**5*exp(-5*t/0.01)
   Call threshold_crossing(1,-0.02,`rising,linear`,n,t1,t2)
   Say "Found {n} threshold crossings, 1st at {t1} nsec."
Enddo

12.149.1: electrode

This is the number of the read-out group for which you wish to know the threshold crossings. Signals are summed over the elements that compose a read-out group - signals for the individual members are not stored.

Read-out groups are formed with the SELECT command. SELECT without arguments will show how the groups are composed.

[No default, this is a mandatory parameter.]

12.149.2: threshold

The threshold level, if the signal has not been processed, it is in micro Amp.

12.149.3: options

This argument is a character string composed of the following words, separated by blanks, comma's etc. Case is irrelevant.

Option Meaning
RISING Detect rising edges crossing the threshold
FALLING Detect falling edges crossing the threshold
LINEAR Use linear interpolation (default)
QUADRATIC Use quadratic interpolation
CUBIC Use cubic interpolation
PLOT Plot a graph detailing the fits and the results
NOPLOT Do not plot the results

Several synonyms of the above are accepted too.

Section 12.150: TRANSVERSE_DIFFUSION

Returns the transverse diffusion, if available, for a given value of (Ex, Ey, Ez) or a given set of values of (Ex, Ey, Ez).

If the field is specified with vectors, then the result will also be a vector. Otherwise the result will be a scalar. It is permitted to specify 1 or 2 components of the field with scalars and the other(s) with vectors. The result will still be a vector in that case.

The electric field should be in V/cm, the diffusion is returned in sqrt(cm).

SIGMA_T can be used as a synonym for TRANSVERSE_DIFFUSION.

Format:

CALL TRANSVERSE_DIFFUSION(ex, ey, ez, sigma_t)

Section 12.151: WEIGHTING_FIELD

Returns the field vector with which the drift velocity of a moving charge is multiplied in order to get the induced current per unit moving charge.

This routine differs from WEIGHTING_FIELD_3 in that it expects only the (x,y) part of the location, assuming z=0.

This procedure should be called from within the signal section.

Format:

CALL WEIGHTING_FIELD(x, y, ex, ey, ez, electrode)

12.151.1: coordinates

WEIGHTING_FIELD uses the internal coordinate system. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If you use polar coordinates however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: assumed to be 0

The transformation from (x,y) to (rho,phi) can be performed by the CARTESIAN_TO_INTERNAL procedure.

12.151.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Er   = Ex/r
Ephi = Ey/r
Ez   = Ez

12.151.3: electrode

Here you have to enter the number of the electrode group on which you wish to measure the current. This number can be obtained by typing SELECT without arguments.

[This argument is compulsory.]

Section 12.152: WEIGHTING_FIELD_3

Returns the field vector with which the drift velocity of a moving charge is multiplied in order to get the induced current per unit moving charge.

This procedure differs from WEIGHTING_FIELD in that it expects an (x,y,z) set of coordinates.

This procedure should be called from within the signal section.

Format:

CALL WEIGHTING_FIELD_3(x, y, z, ex, ey, ez, electrode)

12.152.1: coordinates

WEIGHTING_FIELD_3 uses the internal coordinate system. If you describe your cell in Cartesian coordinates, then the internal frame is simply the Cartesian coordinate system. If you use polar coordinates however, then you should supply the following parameters:

for x: log(r)
for y: phi, in radians
for z: z

The transformation from (x,y) to (rho,phi) can be performed by the CARTESIAN_TO_INTERNAL procedure.

12.152.2: field

The field is returned in internal coordinates. The internal coordinates system is Cartesian when the cell is described in Cartesian coordinates, but when you describe the cell in polar coordinates, you've to apply the following mapping:

Er   = Ex/r
Ephi = Ey/r
Ez   = Ez

12.152.3: electrode

Here you have to enter the number of the electrode group on which you wish to measure the current. This number can be obtained by typing SELECT without arguments.

This argument is compulsory.

Section 12.153: WRITE_HISTOGRAM

Writes an histogram to disk in a format that can also be read by Garfield (see GET_HISTOGRAM), e.g. to resume filling or to perform fits in a later run.

Histograms can also be written out in a format suitable for reading by PAW (see WRITE_HISTOGRAM_RZ)

Calling this procedure does not interfere with filling of the histogram and an histogram can be written to disk before the range has been set (applicable for auto range histograms only).

Format:

CALL WRITE_HISTOGRAM(reference, file [, member [, remark]])

Example:

Global chamber=1

(calculation of e.g. arrival time histograms for chamber 1)

Global hfile '"CHAMBER"/string(chamber)/".HIST"' Global i=0 Global exist=True Global n=0 While exist Do Global i=i+1 Call inquire_histogram(reference(i),exist) If exist Then Call write_histogram(reference(i),hfile) Global n=n+1 Endif Enddo Say "Have written {n} histograms."

In this example, the input file is assumed to contain a cell section that enters the elements for chambers 1, 2, etc depending on the setting of the global variable "chamber".

At the end of the run, the user wishes to keep all histograms for further examination. The loop in the example writes all histograms to a file (hfile) the name of which is CHAMBER1.HIST, CHAMBER2.HIST etc. depending on the setting of the global variable "chamber".

All histograms are written to the same file, but they will be distinguished by their member names which are defaulted to the name of the global variables associated with the histogram.

This example assumes that no histograms have been deleted during the run, as it assumes the histograms are numbered from 1 on.

12.153.1: reference

The histogram is referenced via a global variable that has usually been returned by a call to BOOK_HISTOGRAM or to GET_HISTOGRAM.

12.153.2: file

The name of the Garfield library to which the histogram should be written.

12.153.3: member

The name to be given to the member of the Garfield library that will contain the histogram. Giving a member name is useful if you wish to store several histograms in the same file, as this will allow you to retrieve them selectively.

If the member name is omitted, a default member name equal to the name of the global variable associated with the histogram, will be assigned to the histogram. This is in many cases a meaningful default and there is therefore rarely a need to specify a member.

Section 12.154: WRITE_HISTOGRAM_RZ

Writes Garfield histograms to an RZ file suitable for reading by PAW. RZ files are not readily legible - if you wish to read the numbers, or process the data with your own program, it is probably easier to write the histogram in Garfield format (see WRITE_HISTOGRAM).

An autorange histogram can only be written out to an RZ file once its range has been established.

Format:

CALL WRITE_HISTOGRAM_RZ([reference [, file [, title]]])

Example:

Call book_histogram(a,200)
For i From 1 To 10000 Do
   Call fill_histogram(a,rnd_landau)
Enddo
Call plot_histogram(a,`Energy`,`Landau`)
Call plot_end
Call write_histogram_rz(a,`hist.rz`,`Landau distribution`)

This generates an histogram with a Landau distribution and writes the histogram to a file called "hist.rz". Garfield replies telling that the histogram has been written with PAW identifier 1 and cycle number 1. To read it back with PAW, one would type:

h/file 20 hist.rz
h/pl 1

12.154.1: reference

The histogram is referenced via a global variable, or an expression in terms of global variables.

Histogram references can be created with calls to BOOK_HISTOGRAM or GET_HISTOGRAM. Histogram references are also created by arithmetic between existing histograms.

This parameter may be omitted, or be set to `ALL`, in which case all histograms are written to the RZ file.

[Default: all histograms are written.]

12.154.2: PAW_identifier

Garfield assigns a PAW identifier to the histogram which is the same as the internal Garfield identifier - but which does not bear an immediate relation to the global variable associated with the histogram (if any).

For this reason, Garfield prints the identifier when the histogram is written.

Garfield also prints the cycle number assigned by PAW. The cycle number will be 1 if the histogram identifier is not yet in use in the RZ file. The first cycle of a histogram can be accessed from PAW without special precautions:

h/pl 5

In case, however, that the RZ file already contains an histogram with the same identifier, then the newly written histogram will be assigned a higher cycle number. The histogram now has to be accessed as follows, assuming the cycle number is 3:

h/pl 5;3

12.154.3: file

The name of the RZ file to which the histogram should be written.

The file may exist before the call is issued, but doesn't have to. If the file already exists, then it must be an RZ file formatted with a record length of 1024. The file may already contain other histograms.

[Default: `garfield.rz`.]

12.154.4: title

The title to be assigned to the histogram.

The title is ignored if all histograms are to be written out. In that case, the histograms are given the name of the variable with which they are associated, as title.

[Default: the name of the global variable if the histogram is associated with a global variable, otherwise the field is left blank.]

Section 12.155: WRITE_MATRIX

WRITE_MATRIX is used to store on disk matrices that take a lot of time to compute. These matrices can be retrieved later on with the GET_MATRIX procedure.

The Garfield WWW example pages contain a Matlab function that reads a file written by WRITE_MATRIX (contributed by Guy Garty): http://consult.cern.ch/writeup/garfield/examples/load_garf.m

Format:

CALL WRITE_MATRIX(matrix, file [, member])

Example:

If 'type(global(`ABC`))#`Matrix`' Then
   Call inquire_file(`abc.mat`,exist)
   If exist Then
      Call get_matrix(abc,`abc.mat`,`ABC`)
      Call dimensions(abc,n_dim,dim_abc)
      Global nx=number(dim_abc[1])
      Global ny=number(dim_abc[2])
      Call delete_matrix(dim_abc)
   Else
      Global nx=20
      Global ny=30
      Call book_matrix(abc,nx,ny)
      For i From 1 To nx Do
         For j From 1 To ny Do
            Global abc[i;j]=sin(i)*exp(j/10)
         Enddo
      Enddo
      Call write_matrix(abc,`abc.mat`)
   Endif
Endif

First, one checks whether ABC is already in memory. If it is, nothing is done. Otherwise, an attempt is made to recuperate the matrix from a file. If this doesn't work, then the matrix is generated and stored in the file so that next time, the matrix can be recuperated from there.

12.155.1: matrix

This argument can be either a global variable associated with a matrix, or an expression in terms of global variables that results in a matrix.

12.155.2: file

The name of the Garfield library to which the matrix is to be written.

12.155.3: member

The name to be given to the member of the Garfield library that will contain the matrix. Giving a member name is useful if you wish to store several matrices in the same file, as this will allow you to retrieve them selectively.

If the member name is omitted, a default member name equal to the name of the global variable associated with the matrix, will be assigned to the histogram. This is in many cases a meaningful default and there is therefore rarely a need to specify a member.

Section 12.156: ZEROES

Attempts to find the zeroes of a function represented by a vector of ordinates and a vector of corresponding function values.

The procedure searches for zero crossings between 2 adjacent tabulated values, then performs a linear or quadratic interpolation over the neighbouring range.

Format:

CALL ZEROES(x_vector, y_vector, nzero, zero1, zero2, ...)

Example:

Global r=row(200)/10
Global v=sin(r)
Call zeroes(r,v,nz,z1,z2,z3)
Say "Zeroes: {nz} - {z1,z2,z3}"

12.156.1: vectors

The arguments x_vector and y_vector should both be of type Matrix, and they should have the same total size. The size should be at least 2.

If the arguments are not 1-dimensional, then they are unraveled.

[These arguments are mandatory. No default is supplied.]

12.156.2: nzero

Is set on return to the Number of zeroes that have been found.

12.156.3: zeroes

Each of these arguments contains on successful completion one of the zeroes that have been found.

If there are more return arguments than zeroes found, then the excess arguments are not touched.

If more zeroes are found than return arguments are provided, then the excess zeroes are not returned.

The zeroes are in the same sequence as the ordinate vector.


Chapter 13: Do_loop

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

Section 13.1: FOR

If you use FOR in the first line of a DO loop, you request a loop variables (var) to be incremented at each iteration of the loop. Hence you have to specify the name of the variable, its initial value, the increment and the final value.

Section 13.2: var

The name of the variable to be incremented at each iteration. You may also change the value of this variable during the loop yourself.

This string should start with an alphabetic character, be at most 10 characters long and should not contain separators, algebraic operators or parentheses (see naming for a complete list of restrictions on the names of global variables).

Section 13.3: from

The initial value of the loop variable. This may be an expression in terms of global variables.

Section 13.4: step

The increment of the loop variable. The increment may assume positive and negative values but also 0.

This expression is evaluated anew each iteration.

If no step size is indicated, a default value of 1 is assumed.

Section 13.5: to

For positive increments, the loop is left as soon as the loop variable exceeds this value. For negative increments, the loop is left as soon as the variable is less than to.

This expression is evaluated anew each iteration.

Section 13.6: while

The while condition is evaluated after the loop variable, if used, has been incremented and before a new iteration begins. You have to ensure that while is assigned a value before you execute the loop. Iteration is left as soon as the condition fails to hold.

This expression is evaluated anew each iteration.

Section 13.7: until

The until condition is evaluated at the end of each iteration and does not need to have a value before the DO loop. The loop variable is incremented for the next cycle before until is calculated. Iteration is left as soon as the condition holds.

Section 13.8: LEAVE

Causes iteration to stop, no matter the WHILE, UNTIL and TO conditions.

You may specify as an argument the name of the loop variable associated with the loop you wish to leave.

Section 13.9: ITERATE

Causes the remaining part of this pass through the loop to be skipped. Execution resumes at the top of the loop.

You may specify as an argument the name of the loop variable associated with the loop you wish to leave.


Chapter 14: Global

Do not use curly brackets in Global statements.

Assigns a value to a global variable. This statement can have up to 2 arguments:

All currently defined globals are listed if there are no arguments.

If the value is omitted, then the variable is declared and will be given the value Nill, i.e. it will be of type Undefined.

Global variables are commonly used for substitution of an expression in input statements, as well as in control structures.

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.

Section 14.1: variable

A character string that satisfies the naming conventions for variables, see naming.

Section 14.2: value

The value to be one of the following:

If the value is not specified, then Nill will be assigned.

To enter a set of numbers into a Matrix, one should use the Vector statement.

Examples:

Global abc `abc`
Global abc 2<3
Global abc string(2+3)/abc

Chapter 15: If_block

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.


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


Chapter 17: 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. 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 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.

Section 17.1: GLOBAL

The global variable named after 'GLOBAL' is retrieved, formatted as a string and then used as input. If the global variable is a histogram, then the resulting string only contains the word 'Histogram' - otherwise a more or less meaningful string will be offered.

Section 17.2: INPUT

A line of input is requested from the regular input stream and this line is compared with the template.

The input line is treated like all other input, i.e. text outside quotes and within single quotes is converted to upper case.

This format is only offered for completeness - the TERMINAL input format is probably more useful.

Section 17.3: TERMINAL

A line of input is requested from the terminal, or the batch input file, as appropriate. This line is compared with the template.

The input line is treated like all other input, i.e. text outside quotes and within single quotes is converted to upper case.

This is probably the most useful format since it permits obtaining user input while a file is being read.

Section 17.4: VALUE

The expression is evaluated, the result is formatted as a string and the result is compared with the template.

The resulting value can have any of the data types known by Garfield, (Number, String, Logical, Histogram or Undefined), but the result is not of much use in the case of histograms since histograms that are formatted to a string become just the word 'Histogram'.

The expression may contain global variables if desired.

Section 17.5: template

The template is to be seen as a format for assigning bits and pieces of the input to a set of global variables.

A template can contain the following elements:

Element Purpose
`string` Locate string in the input, resume from there
var Global variable to which the field is assigned
. Ignore the corresponding input field.

Notes:

  1. All elements can be repeated many times.
  2. Instead of reverse quotes (`), one can also use single and double quotes to delimit search strings. Keep in mind however that the quote is a syntax element - the quote must therefore still be visible after the PARSE statement has been processed by the usual input routines.

Examples:

Input Template Result
1 2 3 x y z x=1, y=2, z=3
1 2 x+1 x y z x=1, y=2, z=2
1 2 3 4 x y . x=1, y=2
1 2 x y z x=1, y=2, z not defined
1 2 3 x y Error: y := 2 3 is incorrect syntax
1 2 A 3 x . 'A' y x=1 y=3
1 2 A 3 x 'A' y Error: x := 1 2 is incorrect syntax
1 `abc` 2 x y . x=1 y=`abc`
1>2 z . z=False


Chapter 18: 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.


Chapter 19: Vector

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. Matrices can be given another shape with procedure calls (RESHAPE_MATRIX).

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

Section 19.1: variable

Variables assigned with the VECTOR statement must follow the naming convention for variables, see naming.

Chapter 20: 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, with some exceptions:

Evaluation is not as quick as compiled routines but each formula is preprocessed and translated into an instruction_list, the losses for repeated evaluations are small 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 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.

Section 20.1: variables

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

20.1.1: creating

The values of local variables are always set by the program - you can not change their values nor their name.

Also some global variables are defined by the program:

In addition, you can create global variables yourself:

20.1.2: naming

Global variable names must satisfy the following conventions:

Although permitted, it is not advisable to force variable names to contain lower case characters as in the following:

Bad example:

Global "Abc" 123

20.1.3: substitution

The current value of a formula in terms of global variables is substituted in input statements if the formula is enclosed in curly brackets.

If the formula evaluates to a Number, Logical or String, then the value is simply substituted. If the result is an Histogram, then the string "Histogram" is substituted for the formula. For a 1-dimensional Matrix, the first portion of the matrix is substituted but for higher dimensional matrices, the string "n-Matrix" will appear, where n is the dimension of the matrix.

Curly brackets { } are very often mis-used, in particular they should never be used in Do_loops, in the conditions of If_lines and If_blocks, in the arguments of procedure Calls, in Parse and Global statements.

The contents of { } is evaluated and substituted before the statement is interpreted, while you would probably expect evaluation to happen only when the control statements are executed. For an overview of the use of round, square and curly brackets.

Format:

any text {formula} more text

Example:

Global a=60
Say "Tangent of {a} degrees is {tan(pi*a/180)}."

The global variable A is assigned the value 60. In the following SAY statement, A is converted from degrees to radians and its tangent is displayed.

Further examples of this use of global variables can be found in the examples given for many other commands.

Bad examples:

Global n=5               For i From 1 To 5 Do
For i From 1 To {n} Do      For j From 1 To {i} Do
    ...                        Say "j={j}"
Enddo                       Enddo
                         Enddo

The example on the left would still work if the value of n doesn't change during execution, the example on the right would fail. A priori, I is not defined at the time the loop on J is read. If it is, then the loop on J would be executed a fixed number of times that has no relation with the value of I in the outer loop.

20.1.4: types

Garfield currently knows 6 data types, which differ from those found e.g. in Fortran and in C.

Garfield variables know their own type. Garfield takes care that a version of the operators and the functions appropriate for the given data type or combination of data types is called. The type of the argument propagates to the result for most operators and functions.

Global variables come in the following types:

Type Explanation Mode
Undefined Declared but not initialised 0
String Character strings 1
Number A real or integer number 2
Logical Can be either True or False 3
Histogram 1-Dimensional histogram 4
Matrix n-dimensional matrices made up of numbers 5

The mode is a numeric equivalent of the type, the mode is used only internally for quick reference.

20.1.4.1: Undefined

A variable has type Undefined if:

All arithmetic is permitted between variables of this type and a variable of any other type. All such operations result in a variable of the type Undefined, with the exception of the TYPE function.

One constant of this type, NILL, is predefined.

20.1.4.2: String

Strings are character sequences.

Strings are usually created by enclosing a series of characters in reverse quotes, as illustrated in the examples below.

Strings can be concatenated with the / operator and can be compared with each other with the >, < and = operators. The functions NUMBER and STRING convert Strings to Numbers and vv. There is also a series of procedures that act on Strings: STRING_DELETE, STRING_INDEX, STRING_LENGTH, STRING_LOWER, STRING_MATCH, STRING_PORTION, STRING_UPPER, STRING_WORD and STRING_WORDS.

Strings are internally stored in a dynamic buffer which has a fixed maximum total size. The buffer remembers the length of each string.

There are no constant strings, but there are predefined globals of type String.

Examples:

Global gas_file `gas.dat`

Global p=1 Global gas_file `gas_p`/string(p)/`.gas`

20.1.4.3: Number

All numbers are stored in single machine precision. No distinction is made between reals and integers.

The numbers 0, 1, 2 and PI are constants, there are also predefined globals of this type.

20.1.4.4: Logical

There are only 2 logical values: True and False. They are written as such, without the dots that are used in Fortran.

Logicals in Garfield are not equivalent to numbers, i.e. one can not normally replace True by 1.

Both True and False are stored as constants, there are also some predefined globals of this type.

20.1.4.5: Histogram

Garfield histograms are currently 1-dimensional only.

Histograms are usually created with a call to BOOK_HISTOGRAM. Several instructions can generate histograms as part of their output.

They come in 2 flavours:

Autorange histograms are assigned a range on the basis of the first entries that the histogram receives. Automatic range setting is requested by specifying the AUTOSCALE option when the histogram is booked.

As long as the range of an autorange histogram has not been set, arithmetic can not be applied to it nor can the histogram be plotted. Autorange histograms can however, at any stage, be written out to a file and retrieved.

Histograms can be subject of most of the ordinary arithmetic operators and functions. Mixed arithmetic between Numbers and histograms is permitted and results in histograms.

Histograms can also be operated on by a series of procedures, For instance, histograms can, by means of the WRITE_HISTOGRAM_RZ procedure, be written out to an RZ file for further processing with PAW.

There are no predefined constant histograms, nor globals of this type.

20.1.4.6: Matrix

You can, during a Garfield run, create matrices, carry out operations on them, store them for later use etc.

Matrices can be created in a variety of ways:

The usual arithmetic operators and functions can be applied to matrices as if they were numbers. Mixed arithmetic between Numbers and matrices is permitted and results in matrices.

Parts of matrices can be addressed as illustrated in the following examples. Keep in mind that the number of dimensions does not change, A[;1] is a 2-dimensional matrix ! Use RESHAPE_MATRIX if you wish to transform a 1xn-matrix to an n-matrix, or use the NUMBER function to change a 1x1x...x1-matrix to a number.

1-dimensional matrix:

     A = (9 8 7)     A[1,2,3,1] = (9 8 7 9)

2-dimensional matrix:

         ( 1 2 3 )             ( 3 2 )
     A = ( 2 4 6 )   A[3,2;] = ( 6 4 )     A[;1] = ( 1 2 3 )
         ( 3 6 9 )             ( 9 6 )

One may use a 1-dimensional matrix to index elements of another matrix. This is particularly convenient to extract a large sub-matrix, such as in the following example where one only fits the central portion of a cosine curve with a parabola:

Global x=-pi+2*pi*(row(500)-1)/499
Global y=cos(x)
Call fit_polynomial(x[200+row(100)],y[200+row(100)],0.001, ...
   a0,a1,a2,ea0,ea1,ea2,`plot`)

Notes:

  1. Addressing outside the array bounds is not permitted.
  2. A 2x3-Matrix is not, as in Fortran, equivalent to a 6-Matrix - one has to use both indices in a 2x3-Matrix and only a single index in a 6-Matrix.

20.1.5: storage

Every Histogram, Logical, Matrix, Number and String, whether constant, variable or intermediate result, is accessed through an array called R.

The value of Numbers and Logicals is stored directly in R, while for Histograms, Matrices and Strings a reference number is kept in R.

Each element of R has type information attached to it.

All R's from R(0) downwards are assumed to be constants that are not affected by the execution of the instruction list.

20.1.6: constants

Some frequently used constants are stored as constants for use by all instruction lists. These are stored in the space between R(0) and R(-6). They are not affected by garbage collects.

Although changing R(0) to R(-6) is by itself not prevented, the "jump always" code will for instance not work if R(-1) is set to something else than the value 1. Similar trouble can arise from changing the other constants in this range.

The space below R(-7) can be used for constants present in user entry points. These constants are deleted when the list is deleted with which they are associated.

The values of the constants which can be used in all lists are:

Location Name Value Mode
R(0) 0 0 Number
R(-1) 1 1 Number
R(-2) 2 2 Number
R(-3) PI 3.14159265 Number
R(-4) FALSE False Logical
R(-5) TRUE True Logical
R(-6) NILL Nill Undefined

Notes:

  1. The values for False and True are internally represented as 0 and 1 respectively, but arithmetic between Logicals and Numbers is not encouraged.

20.1.7: predefined

Some global variables are predefined and you may not change their values, one global (OK) may be user redefined, but this is not recommended:

Global Type Explanation
BATCH Logical True if running in batch, False otherwise.
INTERACT Logical True if running interactively, False otherwise.
MACHINE String The type of computer on which you're running.
OK Logical True if last instruction was successful.
TIME_LEFT Number The amount of CPU time that remains.

Section 20.2: operators

Garfield has, internally, different operators for different data types.

There are also operators for certain kinds of mixed arithmetic, such as between numbers and histograms and between numbers and matrices. Mixed arithmetic of logicals and numbers is currently not permitted.

Garfield recognises the following binary operators:

Operator Acts on Gives Effect
+ -N-HM same addition
+ --L-- --L-- or
+ S---- S---- commutative concatenation
- -N-HM same subtraction
- --L-- --L-- exclusive or
* -N-HM same multiplication
* --L-- --L-- and
/ -N-HM same division
/ S---- S---- concatenation
**, ^ -N-HM same exponentiation
& --L-- --L-- and
| --L-- --L-- or
= SN-HM --L-- equality
= --L-- --L-- equivalence
#, <>, >< SN-HM --L-- non-equality
#, <>, >< --L-- --L-- non-equivalence
> SN-HM --L-- greater than
>=, => SN-HM --L-- greater than or equal to
< SN-HM --L-- less than
<=, =< SN-HM --L-- less than or equal to

and the following unary operators:

Operator Acts on Gives Effect
+ -N-HM same assignment
- -N-HM same negative
^, ~ --L-- --L-- not

Notes:

  1. The operators act element by element on variables of type Histogram and Matrix.
  2. The sorting sequence for characters in Strings depends on the computer system that is used.
  3. Mixed operations between Number and Histograms or between Numbers and Matrices result in Histograms and Matrices respectively.
  4. All operators can be applied to type Undefined, the result being Undefined.
  5. The equality and non-equality operators have a tolerance of 1E-4 on all computers except Cray where a tolerance of 1E-8 is used.

Section 20.3: functions

Garfield currently recognises the following intrinsic functions:

Function Acts on Gives Effect
ABS -N-HM same absolute value
ARCCOS -N-HM same arc cosine
ARCCOSH -N-HM same arc hyperbolic cosine
ARCSIN -N-HM same arc sine
ARCSINH -N-HM same arc hyperbolic sine
ARCTAN -N-HM same arc tangent
ARCTANH -N-HM same arc hyperbolic tangent
COS -N-HM same cosine
COSH -N-HM same hyperbolic cosine
ENTIER -N-HM same integer part
EXP -N-HM same exponential
GLOBAL S---- any global with name of the string
LANDAU -N-HM same Landau density function
LOG -N-HM same logarithm
MINIMUM ---HM -N--- minimum of matrix or histogram
MAXIMUM ---HM -N--- maximum of matrix or histogram
NOT --L-- --L-- negation of logical value
NUMBER S---- -N--- conversion of string to number
NUMBER ----M -N--- first element of the matrix
PRODUCT ---HM -N--- product of matrix or histogram
REFERENCE S--HM -N--- reference of a given string etc
REF_HISTOGRAM -N--- ---H- histogram with given reference
REF_MATRIX -N--- ----M matrix with given reference
REF_STRING -N--- S---- string with given reference
ROW -N--- ----M row of number 1 to argument
SIN -N-HM same sine
SINH -N-HM same hyperbolic sine
SQRT -N-HM same square root
STRING SNLHM S---- conversion to string
SUM ---HM -N--- sum of matrix or histogram
TAN -N-HM same tangent
TANH -N-HM same hyperbolic tangent
TRAILING -N-HM same complement of ENTIER
TYPE SNLHM S---- type of the argument

In addition, the following random number generators are known:

Function Argument Effect
RND_EXPONENTIAL mean Exponential distribution with given mean
RND_GAUSS - Normal distribution N(0,1)
RND_LANDAU - Landau distribution
RND_POISSON mean Poisson distribution with given mean
RND_POLYA theta Polya distribution with given theta
RND_UNIFORM - Uniform distribution over [0,1]
RND_FUNCTION - Random number according to a function
RND_HISTOGRAM histogram Random number according to an histogram

Notes:

  1. The functions act element by element on arguments of type Histogram and Matrix.
  2. All functions can be applied to type Undefined, the result being Undefined.
  3. Further functions and random number generators can be added on request.
  4. More elaborate operations are available as procedures Calls.

20.3.1: NUMBER

Converts a variable of type Matrix or String to a variable of type Number.

If the argument is a String, it should contain a simple number, not an expression.

If the argument is a Matrix, then its first element will be returned.

20.3.2: ROW

Returns a 1-dimensional Matrix filled with the number 1 to n, where n is the argument.

The argument is mandatory.

20.3.3: RND_EXPONENTIAL

Generates exponentially distributed random numbers.

The optional argument specifies the mean (and the standard deviation) of the distribution to be generated. If the argument is omitted, a mean of 1 is assumed.

The mean is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as mean the corresponding element of the argument.

20.3.4: RND_FUNCTION

Generates random number according to the function that has, on beforehand, been specified with a call to PREPARE_RND_FUNCTION.

A random number sequences according to only one function can be generated at the time.

This generator has no arguments.

20.3.5: RND_GAUSS

Returns a random number according to a normal distribution, i.e. a Gaussian distribution with mean 0 and sigma 1.

This function has no arguments.

20.3.6: RND_LANDAU

Returns a random number according to a Landau distribution.

This function has no arguments.

20.3.7: RND_HISTOGRAM

Generates random number according to the Histogram given as argument.

Separate random number sequences according to different histograms can be generated concurrently.

The argument is mandatory.

20.3.8: RND_POISSON

Generates Poisson distributed random numbers.

The optional argument specifies the mean of the distribution to be generated. If the argument is omitted, a mean of 1 is assumed.

The mean is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as mean the corresponding element of the argument.

20.3.9: RND_POLYA

Generates Polya distributed random numbers. A Polya distribution with parameter theta is in fact a gamma distribution with parameter theta+1. For theta equal to 0, the Polya distribution reduces to the exponential distribution.

The argument specifies the theta parameter of the distribution to be generated. If the argument is omitted, a theta of 1 is assumed.

The theta parameter is usually specified as a Number but may also be of type Histogram and Matrix. In the latter two cases, variables of the same type will be returned, taking for each output element as theta the corresponding element of the argument.

20.3.10: RND_UNIFORM

Returns a uniformly distributed random number in the range [0, 1].

This function has no argument.

20.3.11: STRING

Converts a variable of any type to a variable of type String as follows:

The STRING function is for instance used to create file names that depend on parameters of the chamber being studied:

Global argon 70
Global co2 30
Global gas_file `Argon_`/string(argon)/`_CO2_`/string(co2)/`.gas`
Call inquire_file(gas_file,exist)
If exist Then
   get {gas_file}
Else
   write {gas_file}
   magboltz argon {argon} co2 {co2}
Endif

20.3.12: TYPE

Takes an expression as argument and returns, in the form of a String, one of the following values: `String`, `Number`, `Logical`, `Histogram`, `Matrix` or `Undefined`.

This function provides a functionality which is similar to the INQUIRE_TYPE procedure.

Section 20.4: instruction_list

When a formula is pre-processed, it is translated into a series of instructions which are placed at the end of the instruction list.

The instruction list usually contains many pieces, identified by entry_points which can be executed independently.

The instruction list consists, as the name says, of a list of instructions.

Each instruction is made up of 4 integers:

  1. either a function specification code or an index in the array R;
  2. code for the operation;
  3. an index in the array R;
  4. the index for the outcome, in R for intermediate results, in the result list for final results

20.4.1: argument

The instruction to assign a register to a subroutine argument reads:

Description Codes
R(j) -> Arg(k) i 8 j k

The first code (i) can have the values 0 and 1, 1 requests the originating register not to be changed on return from the call.

20.4.2: arithmetic

Instruction list codes for arithmetical operations.

Numerical binary arithmetic:

Description Codes
R(i) + R(j) -> R(k) i 1 j k
R(i) - R(j) -> R(k) i 2 j k
R(i) * R(j) -> R(k) i 3 j k
R(i) / R(j) -> R(k) i 4 j k
R(i) ** R(j) -> R(k) i 5 j k

Comparison of numbers resulting in a logical:

Description Codes
R(i) equal to R(j) -> R(k) i 10 j k
R(i) not equal to R(j) -> R(k) i 11 j k
R(i) less R(j) -> R(k) i 12 j k
R(i) less or equal R(j) -> R(k) i 13 j k
R(i) greater R(j) -> R(k) i 14 j k
R(i) gr. or equal R(j) -> R(k) i 15 j k

Logical binary arithmetic:

Description Codes
R(i) and R(j) -> R(k) i 16 j k
R(i) or R(j) -> R(k) i 17 j k

20.4.3: call

The instruction to call a procedure which has n arguments and has the identification code m, reads:

Description Codes
Call procedure m with n args m 9 n 0

The procedures are listed separately, see Call.

20.4.4: functions

Codes for the various intrinsic functions.

Numerical functions:

Description Codes Name
trailing R(i) -> R(j) -11 6 i j TRAILING
arctanh R(i) -> R(j) -9 6 i j ARCTANH
arccosh R(i) -> R(j) -8 6 i j ARCCOSH
arcsinh R(i) -> R(j) -7 6 i j ARCSINH
- R(i) -> R(j) -6 6 i j -
square root R(i) -> R(j) -5 6 i j SQRT
arctan R(i) -> R(j) -4 6 i j ARCTAN
arccos R(i) -> R(j) -3 6 i j ARCCOS
arcsin R(i) -> R(j) -2 6 i j ARCSIN
log R(i) -> R(j) -1 6 i j LOG
exp R(i) -> R(j) 1 6 i j EXP
sin R(i) -> R(j) 2 6 i j SIN
cos R(i) -> R(j) 3 6 i j COS
tan R(i) -> R(j) 4 6 i j TAN
| R(i) | -> R(j) 5 6 i j ABS
+ R(i) -> R(j) 6 6 i j -
sinh R(i) -> R(j) 7 6 i j SINH
cosh R(i) -> R(j) 8 6 i j COSH
tanh R(i) -> R(j) 9 6 i j TANH
Entier R(i) -> R(j) 11 6 i j ENTIER
Sum H_R(i) -> R(j) 13 6 i j SUM
Product H_R(i) -> R(j) 14 6 i j PRODUCT
Landau R(i) -> R(j) 18 6 i j LANDAU
Minimum R(i) -> R(j) 19 6 i j MINIMUM
Maximum R(i) -> R(j) 20 6 i j MAXIMUM
Row of 1 to R(i) -> R(j) 40 6 i j ROW

Logical functions:

Description Codes Name
not R(i) -> R(j) 10 6 i j NOT

Type conversions:

Description Codes Name
string R(i) -> number R(j) -12 6 i j NUMBER
formatted R(i) -> R(j) 12 6 i j STRING
number R(i) -> string R(j) 51 6 i j REF_STRING
number R(i) -> histogram R(j) 54 6 i j REF_HISTOGRAM
number R(i) -> matrix R(j) 55 6 i j REF_MATRIX
name global R(i) -> string R(j) 16 6 i j GLOBAL
type of R(i) -> string R(j) 17 6 i j TYPE

Random numbers:

Description Codes Name
Uniform random number -> R(j) 21 6 - j RND_UNIFORM
Gaussian random number -> R(j) 22 6 - j RND_GAUSS, RND_NORMAL
Exp. random number -> R(j) 23 6 i j RND_EXPONENTIAL, RND_EXP
Poisson random number -> R(j) 24 6 i j RND_POISSON
Landau random number -> R(j) 25 6 i j RND_LANDAU
Polya, theta R(i) -> R(j) 26 6 i j RND_POLYA
Function random number -> R(j) 27 6 i j RND_FUNCTION
Histogram random R(i) -> R(j) 28 6 i j RND_HISTOGRAM

The random number generators RND_EXPONENTIAL and RND_POISSON have the mean of the distribution as argument. The argument of RND_POLYA is the "theta" parameter. These arguments are optional, they default to 1. They can generate random number sequences of different data types.

RND_HISTOGRAM takes an Histogram as argument and always returns a single random number.

20.4.5: goto

The jump instruction reads:

Description Codes
If R(i) Goto Ins(R(j)) i 7 j 0

The first code (i) can of course be set to -1 in order to do the jump under all conditions or to 0 to jump never.

A value out of range for R(j) (typically 0) generates a return. No direct jump instruction code is provided at present. You are allowed to modify the value of R(j) during execution.

20.4.6: results

The instruction to assign a register to an output variable reads:

Description Codes
R(i) -> output variable (j) 0 0 i j

20.4.7: return

To return to the calling procedure, to stop procedure execution, and to stop program execution, the following instructions can be used:

Description Codes
Return to calling procedure i -9 0 0
Stop procedure execution i -9 1 0
Stop program execution i -9 2 0

These instructions are referred to as Return, Exit and Quit. The statement is executed if R(i) has the value 1, if R(i) is 0, the statement is skipped, otherwise an error condition is raised.

Section 20.5: entry_points

The instruction list consists of several sub-lists that are executed independently. The information about a sub-list (the first and last instruction, first and last constant, number of variables expected, number of results returned and a few flags) are stored in an entry point list. This list is used by the interpreting routines.

Each time you ask a function to be translated, this will be done in a new entry point. Similarly, when you enter the editor, you are assigned an entry point to store your instructions in. The entry point description for en edited entry point is updated when leaving the editor.

You can not change the description of an entry point but you can delete entry points, add new ones and see the description of one.

Section 20.6: ADD-ENTRY-POINT

Performs an update of the entry point you were playing with sofar and then creates a new entry point that will become the current entry point.

Format:

ADD-ENTRY-POINT

Section 20.7: CLEAR-ENTRY-POINT

Removes an entry point from the entry point list. The storage associated with it can from then on be recovered by a garbage collect, which is automatically performed by the translation routine but which can also be requested by the user.

Format:

CL-ENTRY [entry_reference]

Examples:

CL-ENTRY
CL-ENTRY 5

In the first example, the current entry point (the one you are editing) is dropped. You may continue to modify it etc. and it can also be executed as long as no garbage collect is done.

In the second example, the entry point with reference number 5 is dropped. The reference number can be obtained from the MEMORY command, details about an entry point are provided by the DISPLAY-ENTRY-POINT command.

Section 20.8: DELETE

Deletes instructions from the instruction list.

Format:

DELETE [from [to|LAST]]

Example:

DEL
DEL 1 LAST

(Both examples delete all instructions.)

Section 20.9: DISPLAY-ENTRY-POINT

Shows full details about an entry point, such as the number of variables expected, the range of the instructions and constants. The output also shows whether the list has been dropped (but not yet been reclaimed), whether the list is executable (note that a list that has been edited is always marked executable) and which interpreter should be used for the execution (sequential or with jumps).

Note that the description of an entry point that is being edited is not always entirely up to date.

Format:

DISPLAY-ENTRY-POINT [entry_reference]

Example:

DISP-ENTRY

Shows details about your current entry point.

Section 20.10: EXECUTE

Executes one or more lines in the instruction list sequentially, ignoring goto statements. This instruction is therefore mainly useful for debugging infinite loops.

Format:

EXECUTE [from [to|LAST]]

Example:

EXEC

(Execute the whole instruction list, skipping branching statements.)

Section 20.11: EXIT

Leaves the editor.

Format:

EXIT

Section 20.12: FUNCTION

Translates the function provided in the argument into an instruction list. No need for quotes around the function, even if it contains blanks or commas etc.

Format:

FUNCTION function

Example:

F ARCTAN (EX/EY)

Section 20.13: GARBAGE-COLLECT

Reclaims the storage in the instruction and constants buffer that is associated with sub-lists that have been cleared. The entry point list is updated to reflect the cleanup. Once the instruction list underwent a garbage collect, cleared entry points can no longer be executed.

Format:

GARBAGE-COLLECT

Section 20.14: INSERT

Inserts lines in the instruction list before the line given as argument. The lines to be input must be in raw format (4 integers per line) and they are roughly checked on correct syntax.

Format:

INSERT before

Section 20.15: LIST

Lists (part of) the instruction list in raw format.

Format:

LIST [from [to|LAST]]

Example:

LIST 5

(Lists line 5 only.)

Section 20.16: MEMORY

Displays the memory occupation: number of registers, constants and instructions that are in use. The list of entry points is also shown, for more details about one of them, use the DISPLAY-ENTRY-POINT instruction.

Format:

MEMORY

Section 20.17: OPTIONS

The local options described below may as usual be mixed with the global options, see the top level OPTIONS command.

Format:

OPTIONS [NO-SYNTAX-CHECK | ALGEBRA-SYNTAX-CHECK | ...
         PROCEDURE-SYNTAX-CHECK] ...
        [SIGNAL-UNDERFLOW | IGNORE-UNDERFLOW]

Examples:

&SIGNAL
(avalanche, time resolution and other settings)
Global phi0=10*pi/180
@
opt ignore-underflow
exit
signal ion-tail cross-induced noelectron-pulse ...
   ion-angles 20 angular-spread exp(-((phi/{phi0})**2))

(Avalanches are spread around the wire with a standard deviation of 10 degrees. This would lead to many underflows in the calculation and the spread would be rejected as a result. This is why the IGNORE-UNDERFLOW option is used.)

OPTION NO-SYNTAX-CHECK DEBUG

(If you are confident you won't make typing errors ...)

20.17.1: SYNTAX-CHECK

New instructions entered via INSERT are checked by default (ALGEBRA-SYNTAX-CHECK) on correct syntax as part of a sequential algebra instruction list, which can in principle be executed entirely within the ALGEXn routines.

The instruction codes for return, goto, argument and call are processed at a higher level. Such instruction codes are used for instance when addressing elements of matrices. These codes are accepted only if you have set PROCEDURE-SYNTAX-CHECK.

You may change also switch syntax checking off altogether.

20.17.2: IGNORE-UNDERFLOW

By default, exponentials of negative numbers less than -88 are signaled as underflows. Formulae in which they occur are not evaluated.

To have such exponentials set to 0 and to continue evaluating the formula, the IGNORE-UNDEFLOW option is used.

When IGNORE-UNDERFLOW is in effect, underflows are not counted.

Section 20.18: PRINT

Prints (part of) the instruction list in a legible format.

Format:

PRINT [from [to|LAST]]

Example:

PRINT 2 10

(Prints lines 2 through 10.)

Section 20.19: REGISTER

Displays (one argument) or modifies (two arguments) the contents of an element of the memory/register array.

You have access to the entire storage area, constant elements included.

Format:

REGISTER array_index value

Examples:

REG 5 10
REG 5

(First assign the value 10 to R(5), then check the value.)

Section 20.20: RESET

Clears the algebra buffers: all instructions, constants and entry points are removed. This instruction should be used with care since there might be sub-lists around that other instructions still need.

Format:

RESET

Section 20.21: RESULTS

Displays the number of results expected by the calling section.

Format:

RESULTS

Section 20.22: SIMPLIFY

Simplifies the present instruction list.

During the simplification, constants are evaluated, complementary operations are cancelled, assignments are propagated and removed, equal subexpressions are identified and stored and unexecutable steps are dropped from the instruction list.

Some of these simplifications are skipped if the instruction list contains (un)conditional jumps since the jump address can not a priori be assumed to be known.

Format:

SIMPLIFY

Section 20.23: TEST

Executes the entire instruction list associated with the current entry point. The arguments of this command are used as values of the variables. There should be precisely one argument per variable declared in the entry point description.

This instruction differs from EXECUTE in that goto is executed. Loops, jumps and if's therefore work as usual.

Format:

TEST var1 var2 ...

Example:

TEST 2 3 6 10

(Execute the instruction list after substituting 2 for R(1), 3 for R(2), 6 for R(3) and 10 for R(4).)

Section 20.24: VARIABLES

Lists the names of the valid variables.

Format:

VARIABLES

Chapter 21: comment

Comment lines start with an asterisk.

Format:

* anything you wish

Chapter 22: control_keys

Control keys can be used to interrupt the program.

Section 22.1: Apollo

The program can be stopped by typing control-Q.

An interrupt mechanism that will stop the current computation but not the program has not yet been implemented for Apollo.

Control-Z is interpreted as an EOF by the Fortran run time I/O library. Program execution is terminated after this control.

Section 22.2: CMS

CMS lacks control keys.

The program can be stopped if necessary by hitting the CP key and then typing IPL CMS. There is no elegant interrupt when a plot is being produced in interactive mode.

The standard EOF mark in VM (a blank return) is intercepted and is treated like a blank input line.

The line separation character (#) is switched off during startup of the program since the symbol has a meaning in Garfield.

Section 22.3: Unix

The program can be stopped by typing control-C.

There is currently no elegant interrupt to stop lengthy calculations without terminating program execution.

Control-Z will place the program in the background, you will need to type "bg" in addition to make it continue to run.

Section 22.4: Vax

The program can be stopped by typing control-Y.

Control-C on a Vax will terminate execution of the command that is being executed and then return control to the command reading routine. The graphics buffers are emptied if plotting is in progress, to make sure GKS is in a well defined state. The terminal printing buffer is flushed. Other I/O channels are left untouched, hence a dataset attached to logical unit 12 (used for short term sequential dataset access) may be left open. This is harmless since the dataset will be closed when a new dataset has to be opened. The same goes for dataset access that is transparent to the user.

The RTL I/O routines have to be replaced so as to avoid blocking of the terminal I/O channel when the AST occurs in an RTL routine. The reason for this is that AST intercepting routine simply unwinds the stack until the routine which has been LIB$ESTABLISH'ed, usually the command reading routine.

Control-Z is interpreted as an EOF by the Fortran run time I/O library. Program execution is terminated after this control.


Chapter 23: dataset

The dataset commands manipulate Garfield datasets.

Although Garfield datasets are for the operating system ordinary sequential files, they are libraries for Garfield purposes. Each Garfield file consists of one or members. A member in a Garfield library 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.

Section 23.1: format

Each member in a Garfield library has a name and a type, neither of which needs to be unique.

The member name is usually specified by the user and is only required if a dataset contains several members of the same type, e.g. two cell descriptions.

The type is chosen by Garfield and is used to ensure that e.g. the cell description reading routine doesn't attempt to read a signal. Thus, you may give the cell and track descriptions associated with a single chamber the same member name, and you can therefore use nearly identical GET statements in the cell, gas and signal sections.

In addition to the name and a type, a remark string can be attached to a member. This string is chosen by the user and is meant to make identification of the member easier.

Garfield libraries are on most computers variable record length sequential files to the operating system. On IBM, the datasets are opened with a fixed record length of 133.

The first record is a line of length 133 which is only there to make sure the operating system doesn't reduce the record length between successive accesses. This record is written automatically when a new file is opened.

Each member starts with a header record formatted as follows:

Character Contents
1 a percent sign (%) to indicate the start of a member
2 a blank, changed to 'X' if the member is deleted
3-10 the string "Created "
11-18 day (dd/mm/yy) on which the member was written
19-22 the string " at "
23-30 time (hh.mm.ss) at which the member was written
31 is blank
32-39 member name
40 is blank
41-48 type of the member
49 is blank
50-80 remark (char 51-79) surrounded by double quotes

Section 23.2: type

The type given to a member is chosen by the program according to the following scheme:

Type Description Main user
ARRIVAL Output of the ARRIVAL instruction User
CELL Compact format cell description Internal
ISOCHRON Equal time contours (isochrones) User
GAS Compact format gas description Internal
GRAPHCOL Colour table Internal
GRAPHREP Representation table Internal
HIST Histograms Both
MATRIX Matrices Internal
MINIMUM Output from the MINIMISE instruction User
OUTPUT General output User
SIGNAL Signals User
TRACK Prepared tracks Internal
TRANSLAT Input translation table Internal
XTPLOT Output from the XT-PLOT instruction User

Types marked "User" are intended for use by the user and can freely be modified. Types marked "Internal" are not meant to be of use to the user, and should also not be modified.

Section 23.3: DEFAULT

Is very similar to Vax/VMS SET DEFAULT command: it enables setting defaults for any component of Vax/VMS file names (node, disk, directory, file name, file type and version number) and of VM/CMS file names (file name, file type and file mode).

This command can not be issued from within a dataset subsection.

Format:

% DEFAULT file_specification

Examples:

% DEF
% DEF 'VAXODIE::'
%default .GARFLIB

The first example shows the current default, the second tells Garfield that it should try to find the files on the node called VAXODIE (note the quotes, the colons are separators and would be discarded without the quotes). The last example ensures that the libraries to be read and written have extension GARFLIB.

Section 23.4: DELETE

Marks a member in a dataset for removal. Removing members physically from a dataset is done by PURGE . RECOVER will undo a %DELETE. Both the member and the type may be wildcards (a * matches every string).

Format:

%DELETE dsname member [type]

Section 23.5: DUMP-HELP-FILE

Prints the complete contents of the help file, this command does not exist on Vax computers.

Beware ... this command will generate a huge amount of output !

Section 23.6: EXIT

Leaves a dataset subsection. You enter a dataset subsection by typing only a % sign with further arguments. Within such a section, no other subsections may be entered, neither may you leave the calling section from within the subsection.

Format:

EXIT

Section 23.7: INDEX

Produces a directory listing of members in a dataset.

The member and type, if you give them at all, may be wildcards, i.e. a * matches any number of every character. Only the members that match both will be in the list.

Also the INQUIRE_MEMBER procedure can be used to determine whether a member exists in a dataset.

Format:

%INDEX dsname [member] [type]

Section 23.8: LIST

Types the contents of some member to the output. You may optionally request listing of only one type of member, note however that both the member and the type may be of the wildcard type (a * matches any string).

Format:

%LIST dsname [member] [type]

Section 23.9: PACK-HELP-FILE

Packs the readable help file into a direct access file which is used by the on-line help utility. There should be no need to execute this command at CERN. Elsewhere, it has to be executed only once when a new release of the help file is distributed.

The VMS help utility is used on Vax computers. This instruction will therefore create a help library rather than a direct access dataset on such devices.

Before this command is executed, one has to ensure that the readable (or raw) help file is available. It is distributed as:

CMS
GARFIELD RAWHELP
Apollo, Cray, Sun
help_raw$garfield
Vax
GARFIELD.HLP (accessed as HELP_RAW$GARFIELD)

This command is not executed if a direct access help file exists when the command is entered, except on Vax where a new version of the library is generated.

Section 23.10: PURGE

This instruction removes deleted members from a dataset. No recovery is possible unless you made a backup yourself. Member and type may not be specified.

Format:

%PURGE dsname

Section 23.11: RECOVER

Recovers deleted members from a dataset that has not yet been purged. Both the member and the type may be of the wildcard type (a * matches every string).

Format:

%RECOVER dsname member [type]

Chapter 24: 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 occurence of the error.

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


Chapter 25: 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 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.

Section 25.1: workstation

A "workstation" in the context of Garfield, is approximately the same as the workstation defined in the GKS standard: a device that can do one or more of the following:

Examples are an X-terminal, a printer, a PostScript file, a mouse or a set of crosshairs.

In interactive jobs, Garfield by default usually has only X-terminal output, while in batch it will have only PostScript output.

These defaults can be changed both with the command line line arguments -terminal and -metafile and from the running program via the commands described below.

Workstations can be in 3 states in Garfield, 2 of which are also in the GKS definition:

defined
A workstation in state "defined" does not receive graphics ouput, but its description (type, name of file associated with it, address etc) is available. A file associated with a workstation in this state is not open, nor is a graphics output window displayed.
open
The same state as "defined" except that a file associated with such a workstation is open. Also graphics output windows are open. However, neither the file nor the graphics window receive output.
active
In this state, a file and a graphics window do receive output.

Moving between the 3 states is accomplished with the following set of commands:

state reached from previous by to return to previous
defined ADD-WORKSTATION DELETE-WORKSTATION
open OPEN-WORKSTATION CLOSE-WORKSTATION
active ACTIVATE-WORKSTATION DEACTIVATE-WORKSTATION

Section 25.2: ACTIVATE-WORKSTATION

Activates a workstation. The graphics output is sent only to the workstations that are active.

A workstation that is to be activated, must already be open.

The argument is an alphanumeric string designating the workstation, two workstations are predefined: TERMINAL and METAFILE. You can define additional workstations via !ADD-WORKSTATION.

Format:

! ACTIVATE-WORKSTATION workstation

Example:

! deact metafile
(make some plots)
! act metafile
(make final version of plots again)

You do not wish to fill the metafile with useless plots. Therefore, you first make a few tests without metafile active and once you are happy with them, you activate the metafile and make the plots again.

Section 25.3: ADD-WORKSTATION

Is used to create additional workstations.

Two workstations are predefined in Garfield: TERMINAL and METAFILE, you may not create workstations by those names (unless you delete them first).

After !ADD-WORKSTATION, the workstation is in the state 'defined', which in GKS terminology means that the workstation is neither 'open' nor 'active'. Use !OPEN-WORKSTATION and !ACTIVATE-WORKSTATION to first open and then activate the newly defined workstation.

For output-only workstations (2nd format), a file name must be given. In both formats, either the type (e.g. MG600 or APPENDIX_E) or the GKS identifier (the driver number) must be specified, but not both. The connection identifier and the offset between logical unit and connection identifier are both optional and can both be used together with TYPE and with GKS-IDENTIFIER.

Format for input/output workstations:

! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid]
                       [CONNECTION-IDENTIFIER conid]

Format for output (metafile, PostScript etc) workstations:

! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid]
                       [OFFSET offset] FILE-NAME file

Example:

!add postscript type ps file-name garfield.ps

This instruction adds a PostScript formatted metafile.

Section 25.4: ARROW-TIP-ANGLE

Vector plots, such as those produced in the field section, contain small arrows. The half tip angle of these arrows can be modified with this command.

The angle should be entered in degrees.

Format:

!ARROW-TIP-ANGLE  angle

Example:

!arrow-angle 60

This would make the tip angles twice the default.

[The default setting is 30 degrees.]

Section 25.5: ARROW-TIP-LENGTH

Vector plots, such as those produced in the field section, contain small arrows. The length of the tip can be modified with this command.

The length should be specified as a fraction of the total length of the arrow.

Format:

!ARROW-TIP-LENGTH fraction

Example:

!arrow-length 0.2

This would make the tip a bit shorter than the default.

[The default setting is 0.3.]

Section 25.6: CLEAR-SCREEN

Clears all active workstations.

Format:

!CLEAR-SCREEN

Section 25.7: CLOSE-WORKSTATION

Closes a workstation. The argument is an alphanumeric string designating the workstation.

Before !CLOSE-WORKSTATION, the workstation should be in the state 'open', afterwards it is in the state 'defined'. It can be re-opened with !OPEN-WORKSTATION and then be activated with !ACTIVATE-WORKSTATION.

Any file attached to the workstation being closed, will also be closed. This file may be overwritten if you perform an !OPEN-WORKSTATION again.

Format:

! CLOSE-WORKSTATION workstation

Example:

!close metafile

This will deactivate workstation METAFILE if still active, then close the workstation and close the file receiving the graphics output.

Section 25.8: COLOUR

Some graphics terminals allow the use of colours - if you have such a device, you may prefer to use colours to distinguish the various components of a plot instead of linetype, markertype and the like.

Each workstation has (at least) two predefined colours: the colour used by default for all items: FOREGROUND and the screen which is in BACKGROUND, items plotted with this colour are therefore normally invisible.

For each additional colour, you have to state how much red, blue and green there is in it, each on a scale of 0 to 1 inclusive. White (or FOREGROUND) has 1 for all three, the BACKGROUND has 0 for all three.

The format allows for a workstation to be specified, this should for the time not be used.

Format:

! COLOUR colour_name RED red BLUE blue GREEN green [WORKSTATION wkid]

Examples:

! COL RED BLUE 0 GREEN 0 RED 1
! COL LIGHT_BLUE BLUE 1 RED 0 GREEN 1

Section 25.9: CONTOUR-PARAMETERS

Contour are computed using a number of numerical parameters for which defaults have been set that are suitable for a wide of applications.

However, if the area over which the contours are to plotted is much smaller than 1, then contours will occasionally be "jumping" from one contour segment to another, with the default set of parameters. This can be cured by lowering the epsilon parameters by a factor of 10.

Contour plotting works as follows:

  1. a grid is scanned to find grid points between which a contour is expected to pass
  2. if a contour passes between 2 neighbouring grid points, first a bisection search and then a Newton search are performed to find an accurate point on the contour
  3. at each point on the contour, the gradient is computed, a step perpendicularly to the gradient is taken, where the gradient is again computed along which a Newton search is made to find the contour back
  4. tracing is terminated when either of the following conditions is fulfilled:

Format:

! CONTOUR-PARAMETERS [ BISECTION-ITERATIONS n_bisection ] ...
                     [ EPSILON-GRADIENT eps-gradient ] ...
                     [ EPSILON-TRACING eps_tracing ] ...
                     [ GRID-TOLERANCE tol ] ...
                     [ NEWTON-ITERATIONS n_Newton ] ...
                     [ STEP-MAXIMUM steps ]

Example:

area -0.01 -0.01 0.01 0.01
!cont-par eps-gra 1e-4 eps-tra 1e-4
plot cont V

Since the area is small, the step size scaling factor for computing gradients and for making steps perpendicular to the gradient are reduced to 10**-4.

25.9.1: BISECTION-ITERATIONS

The maximum number of bisections that is allowed to find a coarse starting point for a new contour between 2 grid points.

Small values are recommended since a Newton search anyhow refines the starting point.

[Default: 10]

25.9.2: EPSILON-GRADIENT

The epsilon used to compute the gradient.

For coordinates near 0, this is the absolute sampling size. For large coordinates, the parameter is taken relative.

When the area is very small (e.g. around 10**-3) or when there is a lot of structure in the contours, then it is a good idea to reduce the value of this parameter to e.g. 10**-4.

[Default: 10**-3]

25.9.3: EPSILON-TRACING

The epsilon used to follow a contour perpendicularly to the gradient.

For coordinates near 0, this is the absolute step size. For large coordinates, the parameter is taken relative.

When the area is very small (e.g. around 10**-3) or when the contours make sharp bends, then it is a good idea to reduce the value of this parameter to e.g. 10**-4.

[Default: 10**-3]

25.9.4: GRID-TOLERANCE

Since the contours are piecewise straight, it can be that a contour segment does not appear to pass between 2 grid points between the exact contour would pass.

In such cases, the algorithm checks whether the contour passes near a grid point within a certain fraction of the grid size, set with this option.

This parameter rarely needs updating. If the parameter is too small, then some contours will be drawn twice. Contours are not missed due to a poor setting of this parameter.

[Default: 0.1]

25.9.5: NEWTON-ITERATIONS

Maximum number of Newton iterations when refining the starting point of a contour and when finding the contour back after a step perpendicular to the gradient.

[Default: 10]

25.9.6: STEP-MAXIMUM

Maximum number of steps in any single contour.

If this parameter is too small, then the contours will be drawn as a series of overlapping pieces.

[Default: 500]

Section 25.10: DEACTIVATE-WORKSTATION

Deactivates a workstation.

After this operation, the workstation is in the GKS state 'open'. The workstation can then be closed via !CLOSE-WORKSTATION or re-activated by !ACTIVATE-WORKSTATION.

This instruction is used to disable temporarily graphics output to the metafile (e.g. when you wish to optimise some parameters without getting a huge metafile) or to the terminal.

Format:

! DEACTIVATE-WORKSTATION workstation

Example:

! deact terminal

Temporarily suspends graphics output to the terminal.

Section 25.11: DELETE-WORKSTATION

Deletes a workstation from the workstation tables.

After this operation, all information about the workstation is lost. A workstation can therefore not be opened or activated again after a !DELETE-WORKSTATION - it has to be added to the tables again with !ADD-WORKSTATION.

Format:

! DELETE-WORKSTATION workstation

Example:

!delete metafile

You opened the metafile by accident and decide you don't need a metafile at all during this run.

Section 25.12: EXIT

Leaves the graphics subsection.

Format:

EXIT

Section 25.13: GET-COLOURS

Reads a list of colours from a dataset which has been written by a call to WRITE-COLOURS. This command can only be executed if you are using a terminal which has colour facilities.

The representation and colour tables are closely connected. When retrieving representations and colours, the recommended approach is to first read the colours and then the representations. Since the representations contain a colour sequence number (assigned on the basis of the colour table present when processing REPRESENTATION statements) rather than a colour name, reading a new colour table without updating the colour references in the representation table, can create incorrect colour references. Representation files do contain colour names, ensuring correct references.

You may modify colours after having retrieved them from a file - modifications of colours do not change their sequence number.

Format:

! GET-COLOURS dsname [member]

Examples:

!GET-COL TEST PARROT

Picks up the member PARROT on dataset TEST.

Section 25.14: GET-REPRESENTATION

Loads a representation table from a dataset written by the WRITE-REPRESENTATION command. Any data that you may have entered using REPRESENTATION statements, will be overwritten.

Be sure that all colours that are referenced by the representations in the file, are defined before issuing a !GET-REPRESENTATION command. In practice, this means that GET-COLOURS commands should precede !GET-REPRESENTATION commands. Items that reference an undefined colour will be shown with a colour set to FOREGROUND.

Format:

! GET-REPRESENTATION dsname [member]

Examples:

!GET-REP TEST MG*

Picks up the first member that matches MG*, presumably MG600.

Section 25.15: INQUIRE-DEFERRAL-UPDATE-STATE

Shows the deferral and update states of the workstation specified. If no argument is given, and if the argument is *, the states of all known workstations are shown.

Format:

! INQUIRE-DEFERRAL-UPDATE-STATE

Example:

!inq-def

Section 25.16: INQUIRE-LEVEL

Informs you about the level of the GKS the program is running with.

Format:

!INQUIRE-LEVEL

Section 25.17: INQUIRE-OPERATING-STATE

Tells you in which state GKS is at the moment.

Format:

!INQUIRE-OPERATING-STATE

Section 25.18: INQUIRE-WORKSTATIONS

Lists the known workstations, their states and associated files.

Format:

!INQUIRE-WORKSTATIONS

Section 25.19: LAYOUT

Gives control over the placement of labels and numbers along the axes of Cartesian plots.

All distances are measured in Normalised Device Coordinates (NDC) which cover the graphics screen from 0 to 1 both in x and in y. The image in Garfield figures covers both in x and in y, the range [0.1, 0.9] leaving the margins for labels, numbers, comments, the time stamp and the title.

Format:

!LAYOUT [ X-NUMBER  x_number ] ...
        [ Y-NUMBER  y_number ] ...
        [ X-DECADE  x_decade ] ...
        [ Y-DECADE  y_decade ] ...
        [ X-LABEL   x_label ] ...
        [ Y-LABEL   x_label ] ...
        [ TITLE     title ]

25.19.1: X-NUMBER

Margin between the x-axis and the upper edge of the numbers shown along the x-axis.

The numbers are plotted centered horizontally at the coordinate they represent.

The size of the numbers can be controled with the NUMBERS representation.

[Initial setting: 0.007]

25.19.2: Y-NUMBER

Margin between the y-axis and the right edge of the numbers shown along the y-axis.

The numbers are plotted centered vertically at the coordinate they represent.

The size of the numbers can be controled with the NUMBERS representation.

[Initial setting: 0.007]

25.19.3: X-DECADE

In plots with a logarithmic x-axis, the margin between upper edge of the exponents of 10 and the x-axis.

The "10" or "1" is plotted centered horizontally at the coordinate it represents, the exponent is plotted such that its lower left edge coincides with the upper right edge of the "10".

The size of the numbers, both the "10" or "1" and the exponent, can be controled with the NUMBERS representation.

[Initial setting: 0.015]

25.19.4: Y-DECADE

In plots with a logarithmic y-axis, the margin between right edge of the exponents of 10 and the y-axis.

The "10" or "1" is plotted centered vertically at the coordinate it represents, the exponent is plotted such that its lower left edge coincides with the upper right edge of the "10".

The size of the numbers, both the "10" or "1" and the exponent, can be controled with the NUMBERS representation.

[Initial setting: 0.015]

25.19.5: X-LABEL

Margin between the lower edge of the plot and the label plotted along the x-axis.

The label is plotted right-aligned with the coordinate frame.

The size of the characters can be controled with the LABELS representation.

[Initial setting: 0.01]

25.19.6: Y-LABEL

Margin between the left edge of the plot and the label plotted along the y-axis.

The label is plotted right-aligned with the coordinate frame.

The size of the characters can be controled with the LABELS representation.

[Initial setting: 0.01]

25.19.7: TITLE

Margin between the top edge of the plot and the title.

The title is plotted left-aligned with the coordinate frame.

The size of the characters can be controled with the TITLE representation.

[Initial setting: 0.01]

Section 25.20: MAP-COLOURS

Plots a table of the currently defined colours.

Format:

!MAP-COLOURS

Section 25.21: OPEN-WORKSTATION

Opens a workstation. The argument is an alphanumeric string designating the workstation.

A workstation to be opened must already have been defined, for instance via !ADD-WORKSTATION. After !OPEN-WORKSTATION, the workstation is in the GKS state 'open' and can be activated by means of !ACTIVATE-WORKSTATION.

Format:

! OPEN-WORKSTATION workstation

Example:

!add falco type falco
!open falco
!act falco

This example shows how to add, open and activate a workstation named FALCO of type FALCO.

Section 25.22: OPTIONS

This command is used to modify the setting of some graphics switches: plotting of a grid, logarithmic/linear axes and the presence of a time-stamp on pictures in a metafile.

If you switch GRID on, a coordinate grid is plotted on top of your plots.

The gas plots have forced vertical logarithmic scales, the logarithmic/linear options are reset when these plots are produced. These options are otherwise not touched.

Format:

! OPTIONS [GRID | NOGRID] ...
          [TIME-STAMP | NOTIME-STAMP] ...
          [LOGARITHMIC-X | LINEAR-X] ...
          [LOGARITHMIC-Y | LINEAR-Y] ...
          [CLEAR-BEFORE-PLOT | NOCLEAR-BEFORE-PLOT] ...
          [CLEAR-AFTER-PLOT | NOCLEAR-AFTER-PLOT] ...
          [WAIT-BEFORE-PLOT | NOWAIT-BEFORE-PLOT] ...
          [WAIT-AFTER-PLOT | NOWAIT-AFTER-PLOT] ...
          [DISPLAY-CONTROL-CHARACTERS | EXECUTE-CONTROL-CHARACTERS]

Example:

!OPT GRID

(The plots that follow will have a grid overlaid.)

25.22.1: LOGARITHMIC-X

Requests the x axis be logarithmic in the following plot.

This option is used mainly internally but you can use it from the input too. Don't be surprised however if your request is overruled !

25.22.2: LOGARITHMIC-Y

Requests the y axis be logarithmic in the following plot.

This option is used mainly internally but you can use it from the input too. Don't be surprised however if your request is overruled !

25.22.3: GRID

Requests a grid be overlayed on the following plots, which can make reading the values easier.

The grid is plotted with the representation GRID.

[By default, no grid is displayed.]

25.22.4: TIME-STAMP

Requests a time stamp be displayed on each plot. The string displayed in the time stamp can be modified with the STAMP graphics command.

[By default, a time stamp is displayed and the stamp indicated by default the version of Garfield used for making the plot.]

25.22.5: CLEAR-BEFORE-PLOT

By default, the (graphics) screen is cleared before and after a plot has been made. If you wish to overlay several plots, you have to suppress the clears with the NOCLEAR-BEFORE-PLOT and NOCLEAR-AFTER-PLOT options.

25.22.6: CLEAR-AFTER-PLOT

On workstations where graphics and printout are displayed in different windows, the automatic clear of the graphics screen after each plot is useless. You can suppress it by requesting NOCLEAR-AFTER-PLOT.

The NOCLEAR-AFTER-PLOT option is primarily used when one wishes to add elements to a plot. This option can, in combination with CLEAR-BEFORE-PLOT, also be used to overlay two consecutive plots.

When overlaying plots, it is advisable to use the REPRESENTATION command to set the colours of the TITLE, the LABELS and the NUMBERS to BACKGROUND in all but the last plot.

Example:

!opt noclear-after nowait-after
!rep title text-colour background
!rep numbers text-colour background
!rep labels text-colour background

&FIELD area -1 -1 1 1 plot cont v

!opt noclear-before !rep numbers text-colour foreground !rep labels text-colour foreground

&DRIFT area -1 -1 1 1 drift wire

!rep title text-colour red !opt wait-after Call gks_select_nt(0) Call plot_text(0.1,0.95,`My own title`,`title`) Call plot_end

!opt clear-before

25.22.7: WAIT-BEFORE-PLOT

By default, a prompt is displayed to hit return before any graphics output is sent to the screen.

This is useful on ordinary terminals, but less so on workstations, and you may wish to switch this option off on such devices.

25.22.8: WAIT-AFTER-PLOT

By default, a message is displayed when the plot is finished and the user is then prompted to hit the return key before the screen is switched back to alphanumeric mode.

This behaviour is not meaningful on workstations and it might therefore be a good idea to switch this option off on such devices.

25.22.9: DISPLAY-CONTROL-CHARACTERS

Various characters have a special meaning for the underlying graphics system. With HPLOT for instance, the symbols [ and ] are used to indicate that the enclosed text should be shown using the Greek font.

If you wish special characters to be interpreted this way, then specify the option EXECUTE-CONTROL-CHARACTERS. But many of the built-in plots contain special characters, e.g. [ and ] are used as delimiters of the units. These plots will therefore not come out right if you switch this option on. In practice, this option is only useful if you wish to have full control, in user plots, over the special characters that a specific graphics system offers.

If on the other hand you select DISPLAY-CONTROL-CHARACTERS, then [ and ] are displayed as such. Furthermore, on some graphics systems, several special symbols are easily accessible:

  1. In units (recognised by the squared brackets that enclose them), the strings 'cm2', 'cm3', 'micron', 'microsec' and 'microamp', are shown in their usual way (superscript 2 for 'cm2', Greek mu for 'micron' etc.
  2. Some particle names (e.g. electron-, mu+, tau-) as well as some chemical compounds (e.g. CO2, C3H8) are shown the way they are normally printed with superscripts to indicate the charge and subscripts showing the number of atoms per molecule.
  3. Greek letters, diacritics and ligatures are accessible as SGML entities, e.g. &Ksi; &eacute; and &szlig; (for a list, see entities) For a list of SGML entities, see for instance: http://home.eclipse.net/~lionheart/html/entities.html

[The default is DISPLAY-CONTROL-CHARACTERS.]

Section 25.23: REPRESENTATION

This command enables you to change the appearance of the various components ('items') of the plot such as the box and tickmarks, drift lines, isochrones, contours, titles, functions etc.

Each item is associated with one or more primitives: polyline, text, polymarker or fill area. Each of the primitives has a series of attributes.

Example: the title of the plot is a piece of text and the attributes of text you can change are the font, the character quality, character size etc.

Per REPRESENTATION statement, you may modify only one item; if an item consists of more than one primitive, you are further restricted to only one of these.

If the attributes are omitted, the current representation is shown. If the item is omitted, all representations are displayed.

Format:

! REPRESENT item attribute value attribute value ...

Examples:

!rep title text-font -7, text-precision stroke, text-colour red, ...
            character-height 0.03
!rep isochrones linetype solid polyline-colour blue
!rep isochrones polymarker-colour blue
!rep isochrones

The first example will ensure the title is plotted in the locally defined (font number is negative) font -7, using the colour RED (which you are supposed to have defined beforehand). The characters will be a bit larger than default.

The next two examples show how isochrones can be plotted in blue. Isochrones consist both of lines segments and single points, hence two statements are needed: polyline and polymarker.

The last example inquires the representation of the isochrones. Both the polyline and polymarker attributes are shown.

25.23.1: item

Items are the basic components of the plot. All components that occur in the plots produced by the Fortran portion of the program are predefined. For plots made from the procedure executor, a utility routine will be provided to add items.

In the list below, no distinction is made between the primitives via which the items are plotted. The distinction is important though when you update.

25.23.1.1: ASTERISK

Polymarker item: can be used as marker type argument to the PLOT_MARKER procedure.

Is initialised to be an asterisk, of which you can change the size and colour.

25.23.1.2: AUGER-ELECTRON

Polyline and polymarker item: Auger electrons result from the return of an excited atom to a lower energy state by the emission of an electron rather than a photon - an mechanism known as Auger effect. The electron that is emitted may have enough energy to ionise further gas molecules, in which case these electrons look like delta electrons.

If an Auger electron generates secondary electrons, then a line is drawn showing its trajectory. Otherwise a marker indicates the point where it was produced.

25.23.1.3: BOX-TICKMARKS

Polyline and fill area item: the polyline item corresponds to the coordinate axes, the fill area item is used in 3D diagrams for the 3 backmost panels of the box.

The fill area item should in principle have an interior style of SOLID and a light colour. The colour will not be used as such - rather, various shades will be used depending on the exposition of the panel with respect to the light source.

25.23.1.4: CIRCLE

Polymarker item: can be used as marker type argument to the PLOT_MARKER procedure.

Is initialised to be a circle, of which you can change the size and colour.

25.23.1.5: COMMENT

Polyline and text item: the polylines clarify lines such as boundaries and changes in status of drift lines.

The text item is used for the information underneath the title and also to explain what the polyline of the same type mean.

25.23.1.6: CONDUCTORS-1

Fill area item: conductors in the chamber as entered with the SOLIDS statement, but also the wires when asking for a 3D plot of a chamber in which the field is computed from wire locations rather than a field map.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.7: CONDUCTORS-2

Fill area item: conductors in the chamber as entered with the SOLIDS statement and for which a representation with this type was explicitely requested.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.8: CONDUCTORS-3

Fill area item: conductors in the chamber as entered with the SOLIDS statement and for which a representation with this type was explicitely requested.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.9: CONTOUR-HIGHLIGHT

Polyline item: the highlighted contours as made by the PLOT-FIELD commands in the field, drift and signal sections.

25.23.1.10: CONTOUR-LABELS

Text item: the function values shown on the contours plotted by PLOT-FIELD commands, if contour labeling has been requested.

25.23.1.11: CONTOUR-NORMAL

Polyline item: the normal contours as made by the PLOT-FIELD commands in the field, drift and signal sections.

25.23.1.12: CROSS

Polymarker item: can be used as marker type argument to the PLOT_MARKER procedure.

Is initialised to be a cross, of which you can change the size and colour.

25.23.1.13: C-WIRES

Polymarker item: the wires of label C are plotted using this representation provided the WIRE-MARKERS option is in effect.

If this option is not active, then the wires will be shown with WIRES.

25.23.1.14: DASHED

Polyline item: can be used as argument in procedures such as PLOT_LINE and PLOT_ARROW whenever a polyline representation is needed.

The representation is not used by normal Garfield commands.

25.23.1.15: DASH-DOTTED

Polyline item: can be used as argument in procedures such as PLOT_LINE and PLOT_ARROW whenever a polyline representation is needed.

The representation is not used by normal Garfield commands.

25.23.1.16: DELTA-ELECTRON

Polyline and polymarker item: Delta electrons look like a hairs along the track. They result from particularly large energy transfers of the particle to an electron of a gas molecule. The electrons thus liberated from the molecule have sufficient energy to ionise further gas molecules before drifting towards the anodes.

If the delta electron generates several further electrons, then it will be drawn as a line, otherwise as a marker.

25.23.1.17: DIELECTRICA-1

Fill area item: the dielectrica in the chamber as entered with the SOLIDS statement.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.18: DIELECTRICA-2

Fill area item: the dielectrica in the chamber as entered with the SOLIDS statement and for which this representation was explicitely requested.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.19: DIELECTRICA-3

Fill area item: the dielectrica in the chamber as entered with the SOLIDS statement and for which this representation was explicitely requested.

This representation is used as such if the chamber is shown as a CUT view.

For 3D impressions, the interior style should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source. The shades can be seen with the SHADING-MAP graphics command.

The elements of the field map are shown with a separate set of representations: MATERIAL-1, MATERIAL-2, MATERIAL-3, MATERIAL-4 and MATERIAL-5.

25.23.1.20: DOT

Polymarker item: can be used as marker type argument to the PLOT_MARKER procedure.

Is initialised to be a dot, of which you can change the representation.

25.23.1.21: DOTTED

Polyline item: can be used as argument in procedures such as PLOT_LINE and PLOT_ARROW whenever a polyline representation is needed.

The representation is not used by normal Garfield commands.

25.23.1.22: E-DRIFT-LINE

Polyline item: Electron drift lines.

25.23.1.23: ERROR-BAND

Polyline and fill area: Error bands plotted with the PLOT_ERROR_BAND procedure call.

25.23.1.24: ERROR-BAR

Polyline and fill area: Error bars plotted with the PLOT_ERROR_BAR procedure call. Also used in graphs made by the fitting routines.

25.23.1.25: FUNCTION-1

Polyline and polymarker item: the primary graph in a plot, such as PLOT GRAPH or DRIFT TRACK TIME-GRAPH.

25.23.1.26: FUNCTION-2

Polyline and polymarker: the secondary graph in a plot, for instance the integrated diffusion in the x(t) plot.

25.23.1.27: FUNCTION-3

Polyline and polymarker: not yet used by Garfield, can be used for user plots.

25.23.1.28: FUNCTION-4

Polyline and polymarker: not yet used by Garfield, can be used for user plots.

25.23.1.29: FUNCTION-5

Polyline and polymarker: not yet used by Garfield, can be used for user plots.

25.23.1.30: FUNCTION-6

Polyline and polymarker: not yet used by Garfield, can be used for user plots.

25.23.1.31: FUNCTION-7

Polyline and polymarker: not yet used by Garfield, can be used for user plots.

25.23.1.32: GOTHIC

Text item: intended for user applications, the font of the representation is set to Gothic.

Not all graphics systems will recognise this representation.

25.23.1.33: GOTHIC-ITALIC

Text item: intended for user applications, the font of the representation is set to Gothic italics.

Not all graphics systems will recognise this representation.

25.23.1.34: GREEK

Text item: intended for user applications, the font of the representation is set to Greek characters.

Not all graphics systems will recognise this representation.

25.23.1.35: GRID

Polyline used to draw the coordinate grid on the plots.

The grid is shown only if the GRID graphics option is in effect.

25.23.1.36: ION-DRIFT-LINE

Polyline item: ion drift lines.

25.23.1.37: ISOCHRONES

Polyline and polymarker item: the isochrones in a drift line plot.

With the initial default settings, i.e. when the DRAW-ISOCHRONES option is on, an attempt is made to link the points on an isochrone with lines.

When a point on an isochrone can not be linked to another point of the same contour, and also when the MARK-ISOCHRONES option is on, a marker is plotted on the drift line.

25.23.1.38: LABELS

Text item: the labels along the axes. This item is also used for the '10**n' part of the scaling factor, the exponent is plotted with the item NUMBERS.

25.23.1.39: MATERIAL-1

Fill area item: used with field maps to draw the area covered by the material with the lowest dielectric constant.

The materials are only shown when PLOT-MAP has been requested in the FIELD-MAP command.

Solids are shown with a separate set of representations: DIELECTRICA-1, DIELECTRICA-2, DIELECTRICA-3, CONDUCTORS-1, CONDUCTORS-2 and CONDUCTORS-3.

25.23.1.40: MATERIAL-2

Fill area item: used with field maps to draw the area covered by the material with the 2nd lowest dielectric constant.

The materials are only shown when PLOT-MAP has been requested in the FIELD-MAP command.

Solids are shown with a separate set of representations: DIELECTRICA-1, DIELECTRICA-2, DIELECTRICA-3, CONDUCTORS-1, CONDUCTORS-2 and CONDUCTORS-3.

25.23.1.41: MATERIAL-3

Fill area item: used with field maps to draw the area covered by the material with the 3rd lowest dielectric constant.

The materials are only shown when PLOT-MAP has been requested in the FIELD-MAP command.

Solids are shown with a separate set of representations: DIELECTRICA-1, DIELECTRICA-2, DIELECTRICA-3, CONDUCTORS-1, CONDUCTORS-2 and CONDUCTORS-3.

25.23.1.42: MATERIAL-4

Fill area item: used with field maps to draw the area covered by the material with the 4th lowest dielectric constant.

The materials are only shown when PLOT-MAP has been requested in the FIELD-MAP command.

Solids are shown with a separate set of representations: DIELECTRICA-1, DIELECTRICA-2, DIELECTRICA-3, CONDUCTORS-1, CONDUCTORS-2 and CONDUCTORS-3.

25.23.1.43: MATERIAL-5

Fill area item: used with field maps to draw the area covered by the material with other dielectric constants.

The materials are only shown when PLOT-MAP has been requested in the FIELD-MAP command.

Solids are shown with a separate set of representations: DIELECTRICA-1, DIELECTRICA-2, DIELECTRICA-3, CONDUCTORS-1, CONDUCTORS-2 and CONDUCTORS-3.

25.23.1.44: MESSAGE

Text item: the line asking you to hit return to signal to the program that it can continue.

25.23.1.45: NUMBERS

Text item: the numbers along the coordinate axes. This item also covers the exponent if the scale is more than 1 decade.

25.23.1.46: OTHER-WIRES

Polymarker item: the wires with label other than S, P and C are plotted using this representation if the WIRE-MARKERS option is in effect.

If this option is not active, then the wires will be shown with WIRES.

25.23.1.47: OUTLINE

Polyline item: the outer limits of the solids as shown in 3D and CUT type plots if the OUTLINE option is in effect.

25.23.1.48: OUTSIDE-AREA

Fill area item: used for areas in CUT type layout plots which are not part of the area box.

25.23.1.49: PHOTON

Polyline and polymarker item: When a particle ionises a gas molecule, the molecule can return to its ground state by emitting a photon, which can be absorbed further on by another gas molecule.

25.23.1.50: PLANES

Polyline and fill area item: the planes in the cell (PLANE statement). The fill area item is used in 3D layouts, the polyline item is used for other projections.

The fill area representation should in principle be set to SOLID. The colour is not used as such, rather various shades of it will be used depending on the exposition of the various surface panels with respect to the light source.

25.23.1.51: PLUS

Polymarker item: can be used as marker type argument to the PLOT_MARKER procedure.

Is initialised to be a plus sign, of which you can change the size and colour.

25.23.1.52: PRESTIGE

Text item: intended for user applications, the font of the representation is set to Prestige Elite.

Not all graphics systems will recognise this representation.

25.23.1.53: P-WIRES

Polymarker item: the wires of label P are plotted using this representation provided the WIRE-MARKERS option is in effect.

If this option is not active, then the wires will be shown with WIRES.

25.23.1.54: TIMES-ITALIC

Text item: intended for user applications, the font of the representation is set to Times italics.

Not all graphics systems will recognise this representation.

25.23.1.55: TIMES-ROMAN

Text item: intended for user applications, the font of the representation is set to Times Roman.

Not all graphics systems will recognise this representation.

25.23.1.56: SOLID

Polyline item: can be used as argument in procedures such as PLOT_LINE and PLOT_ARROW whenever a polyline representation is needed.

The representation is not used by normal Garfield commands, but serves as default for several procedures.

25.23.1.57: S-WIRES

Polymarker item: the wires with label S are plotted using this representation provided the WIRE-MARKERS option is in effect.

If this option is not active, then the wires will be shown with WIRES.

25.23.1.58: TITLE

Text item: the global title of the plot.

25.23.1.59: TRACK

Polyline and polymarker item: This can be either of 2 things:

The two kinds of tracks coincide unless

In both cases, the track can be a point in some circonstances. in that event, a marker is used rather than a line.

25.23.1.60: TUBE

Polyline item: the tube enclosing the wires, the tube is described with the TUBE statement.

25.23.1.61: WIRES

Fill area item: Wires are, unless the WIRE-MARKERS option is active, plotted as areas to allow them to be picked in the GRAPHICS-INPUT instruction. Note that, by default, the wires are plotted as hollow circles. This might give the false impression that this is a polyline item.

If the WIRE-MARKERS option is active, then wires are shown using C-WIRES, OTHER-WIRES, P-WIRES or S-WIRES as appropriate.

25.23.2: fill_area_attributes

Fill area, as the name suggests, means covering a potentially large part of the plot in some way.

25.23.2.1: FILL-AREA-INTERIOR-STYLE

The FILL-AREA-INTERIOR-STYLE is the way the area is covered, there are 4 possibilities:

25.23.2.1.1: HATCHED

A series of parallel lines, see also FILL-AREA-STYLE-INDEX.

25.23.2.1.2: HOLLOW

Only the boundaries are drawn. The appearance is therefore very similar to a polyline - which is why this style is by default used to draw the wires.

25.23.2.1.3: PATTERN

Some pattern, see also FILL-AREA-STYLE-INDEX.

25.23.2.1.4: SOLID

The whole area is filled with the chosen colour. No pattern or hatch style is used.

25.23.2.2: FILL-AREA-STYLE-INDEX

The hatch or pattern with which the area should be filled, refer to the GKS guide for a catalogue.

25.23.2.3: FILL-AREA-COLOUR

The colour to be used to fill the area.

Two colours are known on every workstation: BACKGROUND and FOREGROUND. If your workstation allows, you may add further colours with the COLOUR command.

25.23.2.4: FILL-AREA-PATTERN-SIZE

In the event you select PATTERN to fill the area, you may vary the size of the pattern box. Two values are needed: the x and the y scaling.

25.23.2.5: FILL-AREA-REFERENCE-POINT

The coordinate of the point from where the pattern boxes are tiled to fill the area.

25.23.3: polyline_attributes

Polylines are lines, straight or curved, closed or not.

Polylines can be coloured (POLYLINE-COLOUR), can be thick or thin (LINEWIDTH-SCALE-FACTOR) and can be dashed, dotted, dash-dotted etc. (LINETYPE).

25.23.3.1: LINETYPE

The polyline line type describes the number of interruptions in the polyline. Examples are solid, dashed, dash-dotted.

[Default is SOLID.]

25.23.3.1.1: DASHED

A series of dashes: - - - - -

25.23.3.1.2: DASH-DOTTED

Alternating dots and dashes: .-.-.-.-.

25.23.3.1.3: DOTTED

A series of dots: .........

25.23.3.1.4: SOLID

A normal solid line without interruptions.

25.23.3.1.5: other

Most GKS versions allow other line types than those mentioned above. The documentation should contain a catalogue of the number by which they're selected.

These implementation dependent line types should have a negative number.

25.23.3.2: LINEWIDTH-SCALE-FACTOR

The width of the line, usually ignored on terminals, but respected in e.g. PostScript files.

[Default is 1.]

25.23.3.3: POLYLINE-COLOUR

The colour to be used to plot lines.

Two colours are known on every workstation: BACKGROUND and FOREGROUND. If your workstation has colour facilities, you can add further colours with the COLOUR command.

[Default is FOREGROUND.]

25.23.4: polymarker_attributes

Polymarkers are things like small circles or stars that are used to indicate a point or a series of points without drawing a line between them.

25.23.4.1: MARKER-TYPE

The symbol you wish to use, 5 are predefined, several more can be found in the GKS manual.

You could also envisage using the PLOT_ERROR_BAR procedure.

25.23.4.1.1: ASTERISK

A star: *

25.23.4.1.2: CIRCLE

A circle: o

25.23.4.1.3: CROSS

A cross: x

25.23.4.1.4: DOT

A point: .

25.23.4.1.5: PLUS

A plus sign: +

25.23.4.1.6: other

If your GKS has other markers than those mentioned above, you can select them by specifying the (negative) number by which they're labelled in your GKS guide.

25.23.4.2: MARKER-SIZE-SCALE-FACTOR

The size of the marker. Note that this is a very badly defined quantity, the actual size depends largely on the output device which is used.

25.23.4.3: POLYMARKER-COLOUR

The colour used for plotting the markers.

Two colours are known on every workstation: BACKGROUND and FOREGROUND. If your workstation allows, you may add further colours yourself with the COLOUR command.

25.23.5: text_attributes

The text attributes you may modify are the font, quality, character spacing, character horizontal vs vertical distortion, character height and colour attributes.

25.23.5.1: CHARACTER-EXPANSION

Font designers stipulate a given ratio between height and width of a given character. You may overrule this ratio by choosing an expansion different from 1.

25.23.5.2: CHARACTER-HEIGHT

The height of the character, the width is adjusted automatically.

25.23.5.3: CHARACTER-SPACING

If you wish extra spacing, ask for a number larger than 0.

25.23.5.4: TEXT-COLOUR

The colour used to plot the text.

Two colours are known on every workstation: BACKGROUND and FOREGROUND. If your workstation allows, you may add further colours with the COLOUR command.

25.23.5.5: TEXT-FONT

The font from which the characters are taken. If you choose a fancy font, you may have to switch to high precision to see the effect.

25.23.5.5.1: HIGZ

In HIGZ compilations, one can choose the font both by name and by font number.

Moreover, provided one selects a PostScript font and provided that the DISPLAY-CONTROL-CHARACTERS graphics option is in effect, one can use SGML entities for symbols without keyboard equivalent.

Also, effects like super and sub scripts can be obtained with SGML-like tags.

Information on HIGZ can be found in http://consult.cern.ch/writeup/higz

Example:

!rep title text-font times-roman text-precision high ch-height 0.05
Call plot_frame(0,0,10,10,` `,` `,` `)
Call plot_text(1,6,`&eacute;l&egrave;ve`,`title`)
Call plot_text(1,4,`&Tau;&rho;&omicron;&chi;&iota;&alpha;`/...
   ` &Mu;&upsilon;&omicron;&nu;&iota;&omicron;&upsilon;`,`title`)
Call plot_end

(The representation of the TITLE is changed from the default HIGZ-SOFTWARE font to large TIMES-ROMAN characters, and then used to write the French word for "student" and the Greek for "muon track" on the screen.)

25.23.5.5.1.1: fonts

The correspondance between font numbers and font names is shown in the table below:

Font name Font Notes
HIGZ-SOFTWARE 0 Used by default
TIMES-ITALIC -1 Italic Times
TIMES-BOLD -2 Bold Times
TIMES-BOLD-ITALIC -3 Bold-italic Times
HELVETICA -4 Helvetica
HELVETICA-OBLIQUE -5 Oblique Helvetica
HELVETICA-BOLD -6 Bold Helvetica
HELVETICA-BOLD-OBLIQUE -7 Bold-oblique Helvetica
COURIER -8 Courier
COURIER-OBLIQUE -9 Oblique Courier
COURIER-BOLD -10 Bold Courier
COURIER-BOLD-OBLIQUE -11 Bold-oblique Courier
SYMBOL -12 Mainly Greek characters
TIMES-ROMAN -13 Roman Times
ZAPF-DINGBAT -14 Stars, phones, hearts etc
HOLLOW-TIMES-ITALIC -15 Hollow forms of the above
HOLLOW-TIMES-BOLD -16 idem
HOLLOW-TIMES-BOLD-ITALIC -17 idem
HOLLOW-HELVETICA -18 idem
HOLLOW-HELVETICA-OBLIQUE -19 idem
HOLLOW-HELVETICA-BOLD -20 idem
HOLLOW-HELVETICA-BOLD-OBLIQUE -21 idem
HOLLOW-SYMBOL -22 idem
HOLLOW-TIMES-ROMAN -23 idem
HOLLOW-ZAPF-DINGBAT -24 idem

These fonts have the following appearance:

Notes:

  1. "Italic" is a cursive form of roman, designed to replicate handwriting. "Oblique" is a text style created by slanting a roman font to simulate italics. "Roman" characters have a vertical stem. For details about type setting terminology, see for instance http://typographic.razorfish.com/
  2. Certain fonts can be missing on some output devices.

25.23.5.5.1.2: entities

In PostScript output that uses PostScript fonts, Greek characters, diacritics, ligatures and some special symbols can be created. This can be done both by entering the PS octal code for the symbol or by using the SGML entity name.

When using the PS code, remember that the backslash that precedes the symbol number is by default an escape character in Garfield. You must therefore set the escape character to something else before using these codes. It is therefore probably easier to use the SGML entities.

The correspondance for some symbols commonly used in French, German and Polish is listed in the table below. The SGML entity names for most Greek characters are easy to guess: &alpha;, &beta;, &Zeta; etc. The terminal sigma and alternative theta are in the table, accented Greek characters (dialytica and tonos) are currently not available via entities (they are not in the standard Greek PostScript fonts).

PostScript characters are as a rule not visible on the screen.

PostScript SGML entity Symbol
\366 &aacute; á
\367 &Aacute; Á
\276 &acirc; â
\300 &Acirc; Â
\260 &agrave; à
\265 &Agrave; À
\357 &aring; å
\362 &Aring; Å
\311 &auml; ä
\314 &Auml; Ä
\321 &ccedil; ç
\322 &Ccedil; Ç
\323 &eacute; é
\324 &Eacute; É
\327 &ecirc; ê
\330 &Ecirc; Ê
\325 &egrave; è
\326 &Egrave; È
\331 &euml; ë
\332 &Euml; Ë
\333 &icirc; î
\334 &Icirc; Î
\335 &iuml; ï
\336 &Iuml; Ï
\370 &lstrok; Lower case l with stroke, not in HTML
\350 &Lstrok; Upper case L with stroke, not in HTML
\337 &ntilde; ñ
\340 &Ntilde; Ñ
\371 &oslash; ø
\351 &Oslash; Ø
\345 &ouml; ö
\346 &Ouml; Ö
\347 &ucirc; û
\354 &Ucirc; Û
\374 &ugrave; ù
\375 &Ugrave; Ù
\355 &uuml; ü
\356 &Uuml; Ü
\361 &aelig; æ
\341 &AElig; Æ
\256 &filig; fi ligature, not in HTML 3
\257 &fllig; fl ligature, not in HTML 3
\372 &oelig; oe ligature, not in HTML 3
\352 &OElig; OE ligature, not in HTML 3
\373 &szlig; ß
\126 G &sigmaf; final sigma, not in HTML 3
\112 G &thetasym; alternative theta, not in HTML 3
\302 &acute; acute accent, not in HTML 3
\046 &amp; &
\047 &apos; apostrophe, not in HTML 3
\100 &commat; @
\312 &deg; ° degrees, not in HTML 3
\044 &dollar; $
\041 &excl; !
\263 S &ge; greater or equal, not in HTML 3
\301 &grave; grave accent, not in HTML 3
\076 S &gt; >
\111 S &int; integral sign, not in HTML 3
\243 S &le; less or equal, not in HTML 3
\133 &lsqb; [
\074 S &lt; <
\043 &num; #
\045 &percnt; %
\275 &permil; parts per thousand, not in HTML 3
\261 S &plusmn; ± plus-minus, not in HTML 3
\135 &rsqb; ]
\264 S &times; × product, not in HTML 3

Notes:

  1. The letter "S" after the octal PostScript code indicates that the character comes from the Symbol font, a "G" indicates that the letter comes from the Special font.
  2. A list of SGML entities (many of which are not accessible inside Garfield) can be found at: http://home.eclipse.net/~lionheart/html/entities.html

25.23.5.5.1.3: tags

The following SGML tags are recognised:

Tag Meaning
<SUB> Go to subsript
</SUB> End of subscript
<SUP> Go to superscript
</SUP> End of superscript

Note: tags are case sensitive.

25.23.5.5.2: GTS-GRAL

GTS-GRAL provides a large number of fonts. Only a few of these can be referenced by a name, for the others one should consult the manual.

Garfield does not provide support for diacritical marks with GTS-GRAL/GKS.

25.23.5.5.2.1: fonts

The correspondance between font number and font names is shown in the table:

Font name Font Notes
PRESTIGE -2 Prestige Elite
TIMES-ROMAN -3 Roman Times
TIMES-ITALIC -104 Italic Times
GREEK -13 Greek characters
ITALIC-GREEK -113 Italic Greek characters
GOTHIC -9 Gothic characters
ITALIC-GOTHIC -109 Italic gothic characters

25.23.5.6: TEXT-PRECISION

Changes the quality of the character representation. GKS has 3 different qualities from which you may choose:

25.23.5.6.1: STROKE

This is the highest quality GKS has to offer, all attributes are respected but you have to pay a price in terms of long waiting times before a plot is finished and huge metafiles (if any). This quality would normally used for the final version of a plot that has to go into a thesis or a writeup.

High quality representations are normally only meaningful when a suitable font has been selected.

A synonym for STROKE is HIGH.

25.23.5.6.2: CHARACTER

This is the standard quality. Most attributes are respected and the general appearance is usually satisfactory.

A synonym for CHARACTER is MEDIUM.

25.23.5.6.3: STRING

This is the lowest quality of character output in GKS. This is the recommended setting for interactive work during which you do not wish to spend your time looking at the way characters are plotted.

Usually hardware fonts are used and most attributes are ignored, such as the orientation and size of the characters.

Section 25.24: RESET-COLOURS

Resets the colour table to contain only BACKGROUND and FOREGROUND.

Format:

!RESET-COLOURS

Section 25.25: SET-DEFERRAL-STATE

Sets the deferral and update states.

Format:

!SET-DEFERRAL-STATE ...
     { AS-SOON-AS-POSSIBLE | BEFORE-NEXT-INTERACTION-GLOBALLY | ...
       BEFORE-NEXT-INTERACTION-LOCALLY | AT-SOME-TIME } ...
     { SUPPRESSED | ALLOWED}

Section 25.26: SHADING-MAP

Produces a map of the various colour shades that can be used in 3D views. Depending on the illumination and point of view, lighter or darker variations of the shades are used.

The map contains the shaded variations of the the colours of the fill area representations BOX-TICKMARKS, PLANES, CONDUCTORS-1, CONDUCTORS-2, CONDUCTORS-3, DIELECTRICA-1, DIELECTRICA-2 and DIELECTRICA-3 representations that are used for one or more solids.

These shades are only generated during execution of the AREA statement. No colour memory is allocated for representations that are not in use - it can therefore be that parts of the shading map are left empty.

The number of shades of each colour can be set with the COLOURS option of the AREA command.

Section 25.27: STAMP

Sets the time stamp comment string, the string which is plotted after the time and date in the time stamp. By default, this string is simply a dot.

This string may contain expressions in terms of global variables.

Whether the time stamp appears at all is controled with the TIME-STAMP graphics option.

Format:

! STAMP string

Examples:

!stamp

global vc=2000 ... !stamp "Vc=\{vc\}"

In the first example, you ask the program to display the current time stamp comment string. In the second example, you first set a global variable VC, probably in the &CELL section. You then include the value of this variable in the stamp. Note the use of the escape character (backslash, see ESCAPE): without backslash, VC would be substituted and subsequent changes in the value of VC would not be reflected in the string that is plotted. With the backslash, the { and } are preserved as part of the string and substitution of the value of VC is done only when the string is plotted.

Section 25.28: WRITE-COLOURS

Writes a list of colours to a dataset so that you can easily retrieve them later on by GET-COLOURS.

Format:

! WRITE-COLOURS DATASET dsname [member] [REMARK remark]

Example:

! WR-COL TEST.DAT PARROT "Lots of bright colours"

Section 25.29: WRITE-REPRESENTATION

Writes the representation table to a file such that it can later on be retrieved easily. The idea is that you keep the tables for the various terminal types in one dataset, using the terminal name for member name.

Representation datasets are read with GET-REPRESENTATION.

Format:

! WRITE-REPRESENTATION DATASET dsname [member] [REMARK remark]

Example:

! WR-REP TEST.DAT MG600 "For Monterey terminals"

Chapter 26: 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 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.)

Section 26.1: dsname

The dataset name. The name should be enclosed in quotes if it contains any of the following: blank, comma, colon, quote, equal sign.

This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes.

Double quotes should be used when case is important, e.g. on Unix systems.

Section 26.2: label

A string of up to 80 characters.

If this string is found at the start of a line in the input file, the file is closed and reading continues from the previously opened file.

Specifying EOF as label implies the file is read until the end of the physical file.

["EOF" is default]


Chapter 27: output

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.

Section 27.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

Chapter 28: recording

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"

Section 28.1: dsname

The dataset name. The name should be enclosed in single quotes if it contains any of the following: blank, comma, colon, double quote, equal sign. This means in practice that the quotes are required on a Vax for all dataset access outside the home disk. On VM/CMS, the blanks between file-name and file-type (and perhaps file-mode) may be replaced by dots, thus avoiding the need to add the quotes. On Unix systems, the name should be surrounded by double quotes so as to avoid case conversion of the file name.

Chapter 29: 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.

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

Section 29.1: Aegis

You may enter any command while in the sub-shell.

The PGM_$INVOKE system call is used to invoke /com/sh with your command as argument.

To return to Garfield, type:

return

Section 29.2: DCL

There are no constraints on the use of the $ to give DCL commands, except that one additional subprocess is needed - which may cause trouble if the subprocess quotum is low on your Vax.

The LIB$SPAWN system call is used.

To return from the subprocess to Garfield, type:

LOGOUT

Section 29.3: CMS

Issuing VM/CMS commands from within the program is a delicate exercise: no other program may be executed ... which is something lots of commonly used public EXEC files do. No protection against the consequences of wrong use is offered. You will normally notice that something went wrong in the form of a delayed program crash. (The program should never crash under normal operation.)

Trips to the outside world are safe since they employ SUBSET mode, in which no illegal commands -in the above sense- are permitted. This mode of use is therefore recommended.

The CERN library routine VMCMS is used, see its documentation for details about the restrictions.

To get back into Garfield, type:

RETURN

Section 29.4: Unix

Unix comes with a variety of shells. By default, your commands will be executed via the shell contained in the environment variable "SHELL" (or "shell" if "SHELL" is not set). If not set, the "trusted C shell", tcsh is assumed. If you prefer another shell, then insert a line like:

SHELL "csh"

in your .garfinit file. Note the double quotes around the shell name. As for most parameter setting commands, one can type SHELL without arguments to find out what the current setting is.

The shell is called via a C language interface to the "system" procedure, and there are no restriction on the commands you can issue from sub-shell.

To return to Garfield, type:

exit

Chapter 30: 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.

Section 30.1: ESCAPE

Sets or displays the escape character.

The escape character prevents the character that follows it from being translated, even if there is an entry for it in the translation table.

The escape character prefixed to curly brackets also inhibits evaluation of a formula enclosed in a pair curly brackets.

Format:

ESCAPE character

Example:

esc ^

(Replaces the current escape character by a caret.)

30.1.1: character

The new escape character to be used.

To avoid interference with low level input processing, the escape character may not be set to any of the following symbols:

Description Symbol Reserved as
single quote ' Word delimiter
double quote " Word delimiter
reverse quote ` Character string
blank ( ) Word separator
comma , Word separator
equal sign = Word separator
ampersand & Section header
commercial at @ Algebra sub-header
percent sign % Dataset sub-header
question mark ? Help
exclamation mark ! Graphics sub-header
dollar sign $ Shell commands
number sign # Minimal abbreviation
asterisk * Comment lines
smaller than < Input redirection
larger than > Output redirection
round brackets () Formulae
square brackets [] Matrix indices
curly brackets {} Formula evaluation

[The escape character is initially set to \.]

Section 30.2: TRANSLATE

Using the TRANSLATE command, you can modify the input translation table. Changes are in effect from the moment the command has been issued onwards until further notice. The input translation commands are themselves subject to the current translation table.

Input translation is carried out immediately after reading the line, before case conversion and also before substitution of expressions enclosed by curly brackets.

Characters preceded by the escape character (by default set to backslash: \, see also ESCAPE) are not translated.

If arguments are omitted altogether, the current translation table is displayed.

Format:

TRANSLATE [CYCLES ncycle] ...
     [INTEGER | HEXADECIMAL] char_in [INTEGER | HEXADECIMAL] char_out

Example:

TRANSLATE "." "&", X Y

From this point onwards, you can type .CELL in addition to &CELL to enter the cell section. In addition, all characters X found in the input are changed into Y. The number of translation cycles is not changed.

30.2.1: INTEGER

Indicates the character is specified via its integer code in the range from 0 to 255.

30.2.2: HEXADECIMAL

Indicated the character is specified via its hexadecimal code in the range from 0 to FF.

30.2.3: char_in_out

Either a single character, perhaps enclosed by double quotes to preserve case, or an integer or an hexadecimal number.

30.2.4: ncycle

The number of times the input string should be subjected to the translation table. This number must be in the range 0 (i.e. no translation) to 256.

Section 30.3: GET-TRANSLATION-TABLE

Retrieves the translation table from a dataset to which it has been written by means of a WRITE-TRANSLATION-TABLE command. The member name is optional if only one translation table has been stored in the dataset.

Format:

GET-TRANSLATION-TABLE dsname [member]

Example:

GET-TRANS garflib.dat vax

Reads a member called VAX from the library GARFLIB.DAT.

Section 30.4: WRITE-TRANSLATION-TABLE

Writes the current translation tables to a dataset for later retrieval by GET-TRANSLATION-TABLE. The keywords DATASET and REMARK are optional if the member name is not omitted if a remark is present.

Format:

WRITE-TRANSLATION-TABLE DATASET dsname [member] [REMARK remark]

Example:

WR-TRANS trans.dat vax

Formatted on 0100-08-27 at 04:53.